> 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/specs/phase41-session03-hermes-route-modes-and-hooks/spec.md). # Session Specification **Session ID**: `phase41-session03-hermes-route-modes-and-hooks` **Phase**: 41 - Hermes All-Access Remediation **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 139ad798dfa94839bf20d712fe020aa86b1c793c *** ## 1. Session Overview This session moves the browser-side Hermes route and hook contracts from the legacy ready `read-only` state to the Phase 41 `live-local` state. It is next because Session 02 made the server bridge and parser report local write readiness by default, while `useHermes()` still emits `read-only` for ready local Hermes and `useHermesAdmin()` still exposes mutation readiness through the old admin-enabled naming. The work is intentionally focused on types, route-mode calculation, hook capability decisions, and tests. It does not rename the visible Hermes shell component, replace every read-only label in the UI, or implement mutation control copy; those are assigned to Sessions 07 and 08. The result should let later Hermes, Knowledge Graph, Voice, Intelligence, and mutation sessions depend on one browser contract: ready local Hermes is `live-local`, write readiness comes from the Session 02 bridge contract, token failures remain explicit, and demo/privacy, production, offline, credential, and dependency blockers remain named exceptions instead of normal local mode. *** ## 2. Objectives 1. Replace ready local Hermes route mode with `live-local` and remove `read-only` from the route-mode type contract. 2. Add a repo-owned route-mode helper so status, token, demo, offline, setup, and endpoint failures map consistently. 3. Align `useHermes()` with `live-local`, automatic token readiness, sensitive read gating, and demo fallback behavior. 4. Align `useHermesAdmin()` capability state with the Session 02 `writeReady` bridge contract while keeping token failures explicit. *** ## 3. Prerequisites ### Required Sessions * [x] `phase41-session01-local-access-startup-contract` - Provides canonical `AI_OS_LOCAL_ALL_ACCESS=1` normal local startup behavior. * [x] `phase41-session02-hermes-bridge-status` - Provides the expanded Hermes admin status parser with `writeReady`, `localAccessMode`, compatibility alias state, and blockers. ### Required Tools Or Knowledge * Hermes read route mode and bridge parsers in `src/lib/hermes-types.ts`. * Hermes read hook behavior in `src/hooks/use-hermes.ts`. * Hermes write/admin hook behavior in `src/hooks/use-hermes-admin.ts`. * Existing hook and parser tests in `src/hooks/__tests__/` and `src/lib/__tests__/`. ### Environment Requirements * No real `.env.local`, generated private data, credentials, bearer tokens, local logs, coverage, browser reports, or raw operator data are edited or committed. * Tests use fixture tokens and mocked bridge responses only. *** ## 4. Scope ### In Scope (MVP) * AI OS local operators can resolve a ready Hermes route as `live-local` - update `HermesRouteMode` and route-mode mapping. * AI OS browser hooks can distinguish local live readiness, demo/privacy mode, setup-required, offline, endpoint, and token-failure states - update `useHermes()` and tests. * AI OS browser hooks can allow Hermes write/admin capability when Session 02 `writeReady` is true and an automatic same-run token is available - update `useHermesAdmin()` and tests with duplicate-trigger prevention while in-flight preserved. * Maintainers can rely on route-mode, admin-type, hook, and parser regressions that prove ready local behavior no longer depends on manual admin setup. * Existing component consumers compile against the new `live-local` route mode without requiring the Session 07 visual rename. ### Out Of Scope (Deferred) * Renaming `HermesReadOnlyPage`, `ReadOnlyLabel`, route metadata, tab copy, and broad shell identity - Reason: Session 07 owns Hermes shell identity. * Hermes chat, mission, document, Pantheon, Ministry, and Obsidian mutation-control UX changes - Reason: Session 08 owns mutation controls. * Knowledge Graph, Voice, Intelligence, OpenClaw, Claude Code, local-agent, public demo, extension, docs, archive, and generated-data work - Reason: Sessions 04 through 17 own those surfaces. * Hand-editing `src/data/live-data.json` or any ignored generated runtime data - Reason: Session 17 owns generated data closeout. *** ## 5. Technical Approach ### Architecture Keep the route-mode calculation close to the Hermes browser contract. Add an exported helper in `src/lib/hermes-types.ts`, such as `getHermesRouteMode`, so `useHermes()` can delegate route-state decisions instead of embedding another ad hoc mode ladder. The helper should map demo mode, browser/offline state, status query state, Hermes installed/configured status, and token query state to `loading`, `offline`, `setup-required`, `demo-only`, `live-local`, or `endpoint-error`. Use the Session 02 admin parser fields already present in `src/lib/hermes-admin-types.ts`. `useHermesAdmin()` should treat `status.writeReady === true` as local write readiness and keep `adminEnabled` as a compatibility alias for now only when it matches `writeReady`. `canUseAdmin` remains true only when the hook is enabled, write-ready status has loaded, the browser is online, and a same-run token is available. Update tests at the helper, read-hook, admin-hook, and parser-contract layers. The read hook must continue to prevent sensitive reads when token bootstrap fails. The admin hook must continue to prevent duplicate mutation triggers while a request is in flight and must still surface token-failure, offline, production, explicit local-disablement, and dependency-style status failures instead of turning them into silent read-only behavior. ### Design Patterns * Parser-owned contract: Server status payloads are trusted only after strict parser validation. * Hook-owned readiness projection: UI components consume stable hook states instead of duplicating bridge logic. * Compatibility alias during migration: Keep `adminEnabled` for existing consumers while routing new decisions through `writeReady`. * Fail-closed token handling: Token failure blocks sensitive reads and writes without exposing private data. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | --------------------------------------------------------------------------------------------------------------------- | ---------- | | None | No new production files are required; this session modifies existing type, hook, component-consumer, and test owners. | \~0 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/lib/hermes-types.ts` | Replace ready `read-only` route mode with `live-local` and add a route-mode helper for ready, setup, token, demo, offline, and endpoint states. | \~70 | | `src/hooks/use-hermes.ts` | Use the helper, return `live-local` for ready local Hermes, preserve sensitive read token gating, and update demo fallback decisions. | \~45 | | `src/hooks/use-hermes-admin.ts` | Base write capability on `writeReady` status plus token readiness, preserve duplicate-trigger guards, and surface blocked states through explicit hook states. | \~55 | | `src/components/hermes/hermes-cli-cheatsheet.tsx` | Make route-mode consumer logic compile and treat `live-local` as ready without broad shell copy changes. | \~10 | | `src/components/hermes/hermes-status-bar.tsx` | Adjust readiness support copy or props only where needed for hook contract consistency; defer broad identity copy. | \~20 | | `src/lib/__tests__/hermes-types.test.ts` | Add route-mode helper tests for `live-local`, demo, setup, offline, endpoint, and token failure. | \~90 | | `src/hooks/__tests__/use-hermes.test.tsx` | Update ready local expectations to `live-local` and add token bootstrap success/failure coverage. | \~80 | | `src/hooks/__tests__/use-hermes-admin.test.tsx` | Update capability tests for `writeReady`, token-missing, disabled/local-blocked, offline, and duplicate-trigger behavior. | \~120 | | `src/lib/__tests__/hermes-admin-types.test.ts` | Add or adjust parser assertions that `adminEnabled` remains a compatibility mirror for `writeReady`, not the normal manual gate. | \~35 | | `src/routes/__tests__/agents.test.tsx` | Update Hermes route hook expectations only where route-mode test fixtures assert ready local `read-only`. | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Ready local Hermes resolves to `live-local`. * [ ] `HermesRouteMode` no longer includes `read-only` as the ready local state. * [ ] `useHermes()` keeps public reads and sensitive token-gated reads separated and surfaces token bootstrap failure explicitly. * [ ] `useHermesAdmin()` reports `canUseAdmin` true in normal local dev when `writeReady` is true and the automatic token is available. * [ ] Hook-level blocked states are limited to real token, demo/privacy, production, offline, credential, explicit local access, or dependency failures. ### Testing Requirements * [ ] Route-mode helper tests cover live-local, demo, setup, offline, endpoint, and token failure scenarios. * [ ] Hook tests cover token bootstrap success and token failure without manual admin env setup. * [ ] Admin hook tests cover `writeReady` capability, token missing, local access disabled, offline, and duplicate-trigger prevention. ### Non-Functional Requirements * [ ] No hook or test reintroduces manual `HERMES_DASHBOARD_ADMIN=1` as the normal local readiness requirement. * [ ] Browser-facing status and errors remain redacted and do not expose provider keys, bearer tokens, auth JSON, raw prompts, transcripts, raw command output, private paths, or local usernames. * [ ] Component changes are compile-safe and do not pull Session 07 shell identity or Session 08 mutation-control scope forward. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary targeted tests pass *** ## 8. Implementation Notes ### Working Assumptions * `getHermesRouteMode()` should be added even though the current code embeds the logic in `useHermes()`: The Session 03 stub names both `HermesRouteMode` and `getHermesRouteMode()`, and the codebase benefits from parser-style unit coverage for this central state mapping. Planning can proceed because the helper is additive and keeps the hook thinner. * `adminEnabled` should remain in `UseHermesAdminResult` during this session as a compatibility alias for current component consumers: Session 02 parser already requires `adminEnabled` to match `writeReady`, and Session 07 owns the broader component rename/copy sweep. Planning can proceed because new readiness decisions can use `writeReady` while preserving compile compatibility. * No database-layer work is needed: The analyzer reports `monorepo: false`, conventions state there is no app database, and this session only touches browser hooks, parsers, and tests. ### Conflict Resolutions * `.spec_system/PRD/PRD_UX.md` still says Hermes and OpenClaw agent pages should keep read-only/default-off admin boundaries, while AGENTS, the master PRD, Phase 41 PRD, `.spec_system/CONSIDERATIONS.md`, and Session 03 require local all-access behavior. The Phase 41 local all-access policy wins for current implementation; the older UX text is a documented migration target for Session 16. * The Session 03 stub mentions `getHermesRouteMode()`, but the current repo has no such helper. The chosen interpretation is to create it in `src/lib/hermes-types.ts` because it makes the route-mode contract testable without inventing a new module. * Several components still contain visible read-only copy. The chosen interpretation is to update only compile-sensitive route-mode consumers here because Session 07 explicitly owns Hermes shell identity and copy. ### Key Considerations * `src/data/live-data.json` is generated and gitignored; this session must not edit it. * Local control-plane safeguards remain defense in depth: loopback, Host-header, same-run token, schema, timeout, safe-error, redaction, no-shell argv, and path confinement are not weakened by hook changes. * Keep `AI_OS_*` as the canonical host namespace and do not add new global `findtrend` identifiers. ### Potential Challenges * Route-mode rename can cascade into UI tests that assert old labels: keep the implementation focused on hook contract tests and update route tests only when they depend on the ready mode. * `adminEnabled` naming is legacy but widely consumed: keep it as a compatibility mirror while adding tests that readiness is derived from `writeReady`. * Token failure can look like endpoint failure: keep token view state explicit so sensitive sections report token failure rather than ready or setup-required. ### Relevant Considerations * \[P41] **Local access default migration**: Ready local Hermes must stop presenting read-only as the default route mode. * \[P41] **Do not accept scaffolding as delivery**: The plan includes hook behavior and tests, not label-only changes. * \[P38/P40] **Local control-plane gates are defense in depth**: Token and loopback boundaries remain automatic security controls. * \[P40/P41] **Write safeguards are reusable**: Hook capability should depend on the existing bridge readiness and token safeguards. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Async hook state can enable actions before status and token readiness have actually resolved. * Token failure can accidentally fall through to ready local state or trigger sensitive reads. * Duplicate admin mutations can fire if capability state changes while a mutation is already pending. *** ## 9. Testing Strategy ### Unit Tests * Test route-mode helper mapping in `src/lib/__tests__/hermes-types.test.ts`. * Test Hermes read hook ready, setup, demo, offline, endpoint, and token-failure states in `src/hooks/__tests__/use-hermes.test.tsx`. * Test Hermes admin hook write-ready, token-missing, disabled/local-blocked, offline, and duplicate-trigger states in `src/hooks/__tests__/use-hermes-admin.test.tsx`. ### Integration Tests * Update Hermes route tests in `src/routes/__tests__/agents.test.tsx` only where mocked ready local state depends on the old route mode. * Keep parser contract assertions in `src/lib/__tests__/hermes-admin-types.test.ts` aligned with the Session 02 status shape. ### Runtime Verification * Run `bun run test -- src/lib/__tests__/hermes-types.test.ts src/hooks/__tests__/use-hermes.test.tsx src/hooks/__tests__/use-hermes-admin.test.tsx src/lib/__tests__/hermes-admin-types.test.ts src/routes/__tests__/agents.test.tsx`. * Run `bun run typecheck` because route-mode type changes touch browser TypeScript. * Run ASCII and LF validation for touched files. ### Edge Cases * Demo mode remains a named demo/privacy exception and should not fetch live bridge data. * Offline browser state should not fetch token, public reads, sensitive reads, or admin status. * Ready Hermes with token failure should keep sensitive reads and admin writes blocked. * `writeReady: false` with named blockers should not be normalized into a generic ready state. * Legacy compatibility alias fields remain parsed but do not define normal local readiness. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase41-session01-local-access-startup-contract`, `phase41-session02-hermes-bridge-status` * Depended by: `phase41-session04-knowledge-graph-write-path`, `phase41-session05-voice-token-bootstrap`, `phase41-session06-intelligence-action-access`, `phase41-session07-hermes-shell-identity`, `phase41-session08-hermes-mutation-controls`, `phase41-session10-claude-code-execution` *** ## 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/specs/phase41-session03-hermes-route-modes-and-hooks/spec.md?ask=&goal= ``` `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.