> 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/phases/phase_40/session_05_command_endpoint.md).

# Session 05: Command Endpoint

**Session ID**: `phase40-session05-command-endpoint` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add a deterministic, token-gated, and admin-gated Hermes command endpoint backed by the shared redaction layer.

***

## Scope

### In Scope (MVP)

* Add POST `/__hermes_cmd` in `scripts/lib/hermes-admin-bridge.ts` and register it in the current Vite bridge wiring.
* Preserve loopback and same-run token checks; require admin mode for command execution and explicit confirmation for `update`.
* Allowlist only `version`, `status`, `insights`, `doctor`, and `update` with documented argv and timeouts.
* Resolve Hermes through the same source-entrypoint and CLI fallback rules used by chat.
* Use inherited env cleanup, `NO_COLOR=1`, `TERM=dumb`, non-shell argv arrays, and shared redaction for stdout, stderr, timeout details, and failures.
* Add admin types and a `useHermesAdmin` hook method for later UI work.

### Out of Scope

* Command menu UI.
* Broad shell execution.
* Reporting partial timed-out output as success.

***

## Prerequisites

* [ ] Session 03 shared redaction helper is available.

***

## Deliverables

1. Admin command endpoint, route registration, parser/types, and hook surface.
2. Tests for unknown commands, timeout failures, update confirmation contract, admin/demo/token gates, redacted output, and useful non-secret output.

***

## Success Criteria

* [ ] Public/demo mode cannot execute the endpoint.
* [ ] `update` cannot run without admin capability and UI confirmation.
* [ ] Timed-out commands fail loudly and do not report partial output as success.
* [ ] Browser-visible command output is redacted by default.

***

## Folded Source Session Split

The section below preserves the original Phase 40 session split detail for this session, including dependencies, decisions, outputs, and acceptance checks.

### Session 05: Command Endpoint

**Objective**: Add a deterministic, token-gated and admin-gated Hermes command endpoint backed by the shared redaction layer.

**Scope**:

* Add POST `/__hermes_cmd` in `scripts/lib/hermes-admin-bridge.ts` and register it in the current Vite bridge wiring.
* Preserve loopback and same-run token checks; require admin mode for command execution and explicit confirmation for `update`.
* Allowlist only `version`, `status`, `insights`, `doctor`, and `update` with the documented argv and timeouts.
* Resolve Hermes through the same source-entrypoint and CLI fallback rules used by chat, with inherited env cleanup, `NO_COLOR=1`, and `TERM=dumb`.
* Use shared redaction for stdout, stderr, timeout details, and failures.
* Add admin types and a `useHermesAdmin` hook method for later UI work.

**Outputs**:

* Admin command endpoint, route registration, parser/types, and hook surface.
* Tests for unknown commands, timeout failures, update confirmation contract, admin/demo/token gates, redacted output, and useful non-secret output.

**Dependencies / Notes**:

* Depends on Session 03.
* Should complete before the command menu UI session.

**Acceptance Checks**:

* Public/demo mode cannot execute the endpoint.
* `update` cannot run without admin capability and UI confirmation.
* Timed-out commands fail loudly and do not report partial output as success.
* Browser-visible command output is redacted by default.


---

# 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/phases/phase_40/session_05_command_endpoint.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.