> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session05-command-endpoint/spec.md).

# Session Specification

**Session ID**: `phase40-session05-command-endpoint` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 2d288e5f6539fb47b303a7a44a1c26d1e30e4350

***

## 1. Session Overview

This session adds the deterministic Hermes command endpoint required by Phase 40 before the later command menu UI can run local Hermes commands. The endpoint lives in the existing AI OS Hermes admin bridge, keeps the current loopback, Host-header, same-run token, admin gate, body-size, schema, timeout, safe-error, and redaction boundaries, and exposes only the allowlisted command set named in the Phase 40 PRD.

The work is next because Session 03 delivered the shared bridge-output sanitizer and Session 04 completed the adjacent admin chat runtime refactor. Session 05 consumes those foundations by adding command execution without copying the upstream monolithic Vite middleware or adding the later product UI.

The session provides parser and hook surfaces so future UI work can call the endpoint, but it does not add the command menu. All command execution remains token/admin-gated and non-shell, and `update` additionally requires explicit confirmation because it can mutate the local Hermes install.

***

## 2. Objectives

1. Add POST `/__hermes_cmd` to the Hermes admin bridge with allowlisted `version`, `status`, `insights`, `doctor`, and `update` commands.
2. Execute commands through non-shell argv arrays, Hermes source-entrypoint or CLI fallback resolution, terminal-safe environment flags, and per-command timeouts.
3. Return sanitized, bounded, typed command responses and controlled errors for invalid commands, missing confirmation, missing Hermes binary, non-zero exits, and timeouts.
4. Add admin parser, hook, and focused test coverage for command execution contracts without building the visual command menu.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session01-baseline-and-port-invariants` - Provides the semantic-port and local control-plane invariants this endpoint must preserve.
* [x] `phase40-session03-shared-redaction-foundation` - Provides the shared bridge-output sanitizer and likely-secret detector required before command output becomes browser-visible.
* [x] `phase40-session04-chat-overrides-and-runtime` - Provides the current admin chat runtime, Hermes command resolution owner, and hook/parser patterns this session must not regress.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Existing Hermes admin bridge endpoint list, preflight guard, JSON body reader, `executeCommand()` helper, and shared sanitizer usage in `scripts/lib/hermes-admin-bridge.ts`.
* Existing admin hook mutation pattern in `src/hooks/use-hermes-admin.ts`.
* Existing admin parser and parser tests in `src/lib/hermes-admin-types.ts` and `src/lib/__tests__/hermes-admin-types.test.ts`.

### Environment Requirements

* Local checkout with dependencies installed or installable through `bun install`.
* No live Hermes install or provider credentials required for planned tests; mocked spawn fixtures should cover command resolution, argv, timeout, output, redaction, and failure behavior.

***

## 4. Scope

### In Scope (MVP)

* AI OS exposes a token/admin-gated POST `/__hermes_cmd` endpoint from `scripts/lib/hermes-admin-bridge.ts`.
* The endpoint accepts only `version`, `status`, `insights`, `doctor`, and `update`; every other command is rejected before spawn.
* `update` requires explicit confirmation in addition to token/admin gating.
* Hermes resolution follows the existing chat path: prefer the source entrypoint under `~/.hermes/hermes-agent`, then fall back to configured or discovered `hermes` CLI wrappers.
* Command execution uses non-shell argv arrays, stripped inherited Python env, `NO_COLOR=1`, `TERM=dumb`, output caps, and command-specific timeouts: 20 seconds for `version`, 25 seconds for `status`, 30 seconds for `insights`, 60 seconds for `doctor`, and 300 seconds for `update`.
* Browser-visible stdout, stderr, timeout details, and failure details are sanitized by the shared bridge-output sanitizer.
* Admin types and `useHermesAdmin` expose a command action for later UI work.

### Out Of Scope (Deferred)

* Command menu, slash actions, or any visible command UI - Reason: Session 13 owns command UX after the endpoint exists.
* Broad shell execution or arbitrary Hermes argv - Reason: Phase 40 requires a deterministic allowlist only.
* Reporting partial timed-out command output as success - Reason: the PRD requires timeout failures to fail loudly.
* Direct upstream Vite middleware copy - Reason: AI OS owns split bridge modules, and `vite.config.ts` already registers the admin bridge as a whole.

***

## 5. Technical Approach

### Architecture

Implement the command endpoint in `scripts/lib/hermes-admin-bridge.ts` beside the existing admin chat endpoint. Register `/__hermes_cmd` through the bridge `ENDPOINTS` array so the existing `registerHermesAdminBridge()` call in `vite.config.ts` picks it up without adding route-specific Vite middleware.

Refactor the current Hermes resolution path so chat and commands share source entrypoint and CLI fallback behavior without hard-coding `chat` into the base resolver. The source-entrypoint path should spawn the venv Python executable with `hermes_cli/main.py` plus the selected subcommand argv. The CLI fallback should spawn the wrapper with the selected subcommand argv directly.

Use the existing `executeCommand()` process helper for bounded non-shell execution. Add a command-specific allowlist that owns argv, timeout, label, and confirmation requirements. Successful responses should return sanitized output and exit metadata. Timeout and non-zero responses should return controlled errors and never mark partial output as successful.

### Design Patterns

* Boundary validation: Parse and validate command payloads at the admin bridge boundary before spawning any process.
* Non-shell argv arrays: Keep all command execution in explicit argv arrays and pin the exact argv in tests.
* Parser-owned contracts: Add command request and response types/parsers to `src/lib/hermes-admin-types.ts` before exposing them through hooks.
* Local control-plane defense in depth: Preserve loopback, Host-header, token, admin, method, body-size, schema, timeout, safe-error, and redaction gates.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                     | Est. Lines |
| ---- | ----------------------------------------------------------- | ---------- |
| None | No new production source file is expected for this session. | 0          |

### Files To Modify

| File                                                | Changes                                                                                                                                                          | Est. Lines |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-admin-bridge.ts`                | Add command allowlist, subcommand-aware Hermes resolution, `/__hermes_cmd` handler, endpoint registration, timeout/error mapping, and sanitized output handling. | \~230      |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts` | Add bridge coverage for command gates, allowlist, confirmation, argv, source/CLI fallback, env cleanup, timeout, non-zero exits, and redaction.                  | \~260      |
| `scripts/lib/sanitize.ts`                           | Extend shared bridge-output redaction only if command-output fixtures expose a missing safe pattern.                                                             | \~30       |
| `scripts/lib/__tests__/sanitize.test.ts`            | Add command-output redaction fixtures and safe non-secret negative coverage.                                                                                     | \~70       |
| `src/lib/hermes-admin-types.ts`                     | Add command names, request/response body types, error parser compatibility, and command response parser.                                                         | \~80       |
| `src/lib/__tests__/hermes-admin-types.test.ts`      | Add command response parser coverage for valid output and malformed payloads.                                                                                    | \~70       |
| `src/hooks/use-hermes-admin.ts`                     | Add command mutation state and `runCommand` action with duplicate-trigger prevention while in-flight.                                                            | \~90       |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`     | Cover command action payloads, confirmation, disabled/token/offline states, parser failures, and duplicate in-flight prevention.                                 | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] POST `/__hermes_cmd` rejects non-loopback, bad Host, bad token, disabled admin mode, wrong method, invalid JSON, and unknown commands before spawn.
* [ ] Allowed commands spawn only the documented argv: `version`, `status`, `insights --days 30`, `doctor`, and `update --yes`.
* [ ] `update` cannot run without explicit confirmation.
* [ ] Timeouts return failure and do not report partial output as success.
* [ ] Missing Hermes binary, spawn failure, non-zero exit, and invalid payloads return controlled, browser-safe errors.
* [ ] Browser-visible stdout, stderr, timeout, and failure details are redacted by default.
* [ ] `useHermesAdmin` exposes a typed command action for later UI work without adding command menu UI.

### Testing Requirements

* [ ] Focused Hermes admin bridge tests cover gates, allowlist, confirmation, source-entrypoint argv, CLI fallback argv, timeout kill behavior, non-zero exit behavior, and sanitized output.
* [ ] Sanitizer tests cover command-output positive and negative fixtures.
* [ ] Parser tests cover command response parsing and malformed responses.
* [ ] Hook tests cover request serialization, confirmation, disabled/token and offline views, duplicate in-flight prevention, and error handling.

### Non-Functional Requirements

* [ ] Command execution remains local-only, admin-gated, non-shell, timeout-bounded, and output-bounded.
* [ ] The endpoint exposes no raw home paths, auth JSON paths, account IDs, emails, tokens, command bodies, or secret-shaped strings.
* [ ] Existing chat, mission, Pantheon, documents, image, and Obsidian admin actions continue using the same bridge registration and guard behavior.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] No user-facing command menu, slash action, or debug surface is added in this endpoint-only session

***

## 8. Implementation Notes

### Working Assumptions

* The existing `executeCommand()` helper is the right process executor for this endpoint: it already uses non-shell `spawn()`, bounded stdout/stderr buffers, timeout killing, and shared output sanitization in `scripts/lib/hermes-admin-bridge.ts`.
* Hermes command resolution should be refactored rather than duplicated: `resolveHermesCommand()` currently hard-codes `chat`, while the Phase 40 PRD requires command endpoint behavior to resolve Hermes the same way chat does. A shared base resolver or subcommand-aware resolver keeps that behavior aligned and testable.

### Conflict Resolutions

* The upstream source wires command endpoint and command menu behavior near each other, while the Phase 40 session split separates Session 05 endpoint work from Session 13 command UX. The chosen interpretation is to ship only the admin bridge, types, hook, and tests now.
* The PRD says to register the endpoint in Vite bridge wiring, but this repo registers Hermes admin endpoints through `registerHermesAdminBridge()` and the bridge-local `ENDPOINTS` list. The chosen interpretation is to add `/__hermes_cmd` to `ENDPOINTS`; no direct `vite.config.ts` edit is expected unless implementation finds a second explicit endpoint list.

### Key Considerations

* Keep AI OS naming and do not add new global `findtrend` identifiers.
* Preserve public demo/write boundaries; command execution must not become available through demo or hosted output.
* Keep command output useful enough for local troubleshooting while sanitizing private paths, account material, emails, token-shaped strings, and control sequences.
* Use synthetic fixture labels shorter than real key patterns in tests and docs.

### Potential Challenges

* Refactoring Hermes resolution could regress chat argv construction: mitigate with existing chat tests plus a focused assertion that chat still spawns `chat` with prior option ordering.
* Timeout behavior can race with child close: mitigate by testing timeout kill, close-after-timeout, and no-success-on-timeout paths.
* Redaction can over-redact model or command words: mitigate with safe negative fixtures for `doctor`, `insights`, `gpt-5.5`, `openai-codex`, and normal status prose.

### Relevant Considerations

* \[P38] **Local control-plane gates are defense in depth**: Preserve socket loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error checks for the new command bridge.
* \[P38] **Upstream ports are semantic, not wholesale**: Translate upstream command behavior into the existing AI OS bridge and hook owners instead of copying upstream middleware files.
* \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Route command output, stderr, and failure details through the shared sanitizer before returning JSON.
* \[P38] **OpenAI Realtime keys stay environment-only**: Preserve the broader Phase 40 rule that provider credentials remain environment/script-only and never become browser request body material.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* External command input can become shell-like unless the endpoint uses a small schema-validated allowlist and explicit argv arrays.
* `update` can mutate the local Hermes install unless confirmation, admin gating, timeout failure, and no-partial-success behavior are enforced.
* Command output can leak local paths, account IDs, emails, or token-shaped values unless every success and failure path uses shared redaction.

***

## 9. Testing Strategy

### Unit Tests

* Add parser tests in `src/lib/__tests__/hermes-admin-types.test.ts` for valid command responses, missing required fields, wrong field types, and malformed command names.
* Add sanitizer tests in `scripts/lib/__tests__/sanitize.test.ts` for command output with ANSI escapes, home paths, emails, account-like IDs, key/value secrets, and safe non-secret command/model words.

### Integration Tests

* Add Hermes admin bridge tests for `/__hermes_cmd` method, loopback/Host, token, admin, invalid JSON, unknown command, missing update confirmation, source-entrypoint argv, CLI fallback argv, env cleanup, timeout kill, non-zero exit, missing binary, and sanitized stdout/stderr.
* Add hook tests for `runCommand()`, command mutation state, duplicate prevention while in-flight, confirmation payloads, disabled/token/offline states, and parser failure handling.

### Runtime Verification

* Run focused command endpoint checks: `bunx vitest run scripts/lib/__tests__/sanitize.test.ts scripts/lib/__tests__/hermes-admin-bridge.test.ts src/lib/__tests__/hermes-admin-types.test.ts src/hooks/__tests__/use-hermes-admin.test.tsx`.
* Run script and app typechecks because this session touches both script-side bridge code and browser TypeScript.

### Edge Cases

* `update` with no confirmation, wrong confirmation, and valid confirmation.
* A timed-out `update` with partial stdout or stderr.
* Output containing ANSI/CSI sequences, raw home paths, symlink-realpath-style homes, auth JSON labels, account IDs, emails, and token-shaped values.
* Safe output containing normal command words, provider slugs, model IDs, and ordinary status prose.
* Missing source-entrypoint files with CLI wrapper fallback, and no available Hermes binary.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session01-baseline-and-port-invariants`, `phase40-session03-shared-redaction-foundation`, `phase40-session04-chat-overrides-and-runtime`
* Depended by: `phase40-session13-command-ux-and-slash-actions`, `phase40-session18-full-validation-and-handoff`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session05-command-endpoint/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.