> 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-session06-intelligence-action-access/spec.md). # Session Specification **Session ID**: `phase41-session06-intelligence-action-access` **Phase**: 41 - Hermes All-Access Remediation **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 6f7abfe63be090533f3be61800256dfb0ed91b61 *** ## 1. Session Overview This session makes typed Ask Hermes and the Hermes Intelligence voice controls use the Phase 41 local all-access readiness contract. Sessions 03 and 05 are complete, so the browser-side Hermes contract now has ready local `live-local` behavior, write readiness comes from `writeReady`, and the voice broker can bootstrap a token without manual `AI_OS_VOICE_TOKEN` setup. The work removes the normal local `admin-disabled` framing from Intelligence and Ask Hermes without weakening real blockers. Demo/privacy mode, offline state, same-run token failures, missing provider keys, browser microphone permission, unavailable broker, and provider failures stay visible, specific, and recoverable. The result should be a user-facing Intelligence portal that lets local operators type or start voice when automatic local readiness exists, shows streamed results in the transcript and activity surfaces, and rejects only real dependency failures with focused tests. *** ## 2. Objectives 1. Replace Intelligence voice and Ask Hermes normal local gating with local all-access readiness derived from `writeReady`, token availability, and explicit dependency states. 2. Remove `admin-disabled` and manual local admin setup copy from normal local Intelligence states. 3. Preserve and test named recovery paths for demo/privacy, offline, token failure, provider-key failure, broker failure, microphone failure, and provider failure. 4. Expand hook and portal tests so local success and each named blocked state are covered. *** ## 3. Prerequisites ### Required Sessions * [x] `phase41-session03-hermes-route-modes-and-hooks` - Provides `live-local`, `writeReady`, and hook write-readiness behavior without manual admin setup. * [x] `phase41-session05-voice-token-bootstrap` - Provides automatic voice token bootstrap for direct and bridge-started voice broker paths. ### Required Tools Or Knowledge * Hermes admin hook readiness in `src/hooks/use-hermes-admin.ts`. * Intelligence voice controller in `src/hooks/use-hermes-intelligence-voice.ts`. * Intelligence portal UI in `src/components/hermes/intelligence/intelligence-portal.tsx`. * Current Intelligence type contract in `src/components/hermes/intelligence/intelligence-types.ts`. * Existing hook and component tests under `src/hooks/__tests__/` and `src/components/hermes/intelligence/__tests__/`. ### Environment Requirements * Focused tests must use mocked bridge, broker, provider, and media APIs; no real provider credentials are required. * Provider keys, bearer tokens, raw provider payloads, transcripts, auth JSON, local usernames, and private paths must not be written to committed files or browser-visible test fixtures. * No app database, ORM, migration, or persisted data schema work is required. *** ## 4. Scope ### In Scope (MVP) * AI OS local operator can use typed Ask Hermes from the Intelligence portal when local write readiness and same-run token readiness exist - update portal readiness, copy, and tests. * AI OS local operator can start Voice from the Intelligence portal when local write readiness, token readiness, provider key, broker, browser media, and network dependencies are available - update voice hook/portal failure mapping and tests. * AI OS local operator sees specific recovery guidance for demo/privacy, offline, token, provider-key, broker, microphone, timeout, and provider failures - keep recovery text product-facing and free of secret-shaped diagnostics. * Maintainer can rely on focused hook and portal tests for local success, token failure, broker failure, provider-key failure, demo/privacy, offline, and duplicate-trigger behavior. ### Out Of Scope (Deferred) * Voice token bootstrap internals - Reason: Session 05 owns token bootstrap and broker process behavior. * Hermes mutation controls outside typed Ask Hermes and Intelligence voice - Reason: Session 08 owns broader Hermes mutation controls. * Hermes shell identity and broad read-only label replacement outside Intelligence - Reason: Session 07 owns shell identity. * OpenClaw, Claude Code, local-agent, public demo, docs, archive, and generated-data closeout - Reason: later Phase 41 sessions own those surfaces. * Hand-editing `src/data/live-data.json` or other ignored generated local data - Reason: Session 17 owns generated data closeout. *** ## 5. Technical Approach ### Architecture Keep Intelligence readiness as a thin projection over existing Hermes readiness instead of creating a new access model. `useHermesAdmin()` already reports `writeReady`, `canUseAdmin`, token failure, offline, and disabled states. The Intelligence portal should interpret `canUseAdmin` as automatic local readiness, while any unavailable state should be mapped to named recovery copy that does not describe normal local mode as manually admin-disabled. Update `src/components/hermes/intelligence/intelligence-types.ts` so the voice failure code set uses product-specific dependency names rather than `admin-disabled`. Then update `src/hooks/use-hermes-intelligence-voice.ts` to fail demo mode and missing local readiness with specific recoveries such as `demo-gated`, `local-readiness`, `missing-token`, `broker-unavailable`, `missing-key`, `provider-failed`, `mic-denied`, and `offline`. Keep duplicate-trigger guards, cleanup on stop/unmount, abort handling, media track cleanup, and no secret-bearing request bodies. Update `src/components/hermes/intelligence/intelligence-portal.tsx` so Start Voice and Ask Hermes gate on a named local readiness projection, not manual admin setup. The portal should keep controls disabled during demo, offline, token-failure, pending, in-flight, and active voice states; it should show visible results through transcript/activity rows on success and show specific recovery guidance for each real blocker. ### Design Patterns * Hook-owned readiness projection: components consume stable readiness states rather than duplicating bridge error parsing. * Named recovery states: user-facing copy names the recoverable dependency, not legacy admin setup. * Fail-closed token handling: token failure blocks voice and chat without leaking token values. * Scoped async lifecycle: voice media, peer, channel, abort controller, and timers clean up on stop, error, and unmount. * Duplicate-trigger prevention: Ask Hermes and Start Voice ignore repeated triggers while work is in flight. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---- | ------------------------------------------------------------------------------ | ---------- | | None | This session modifies existing Intelligence hook, component, types, and tests. | \~0 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/intelligence/intelligence-types.ts` | Replace `admin-disabled` voice failure with named local readiness and demo/privacy failure codes. | \~15 | | `src/hooks/use-hermes-intelligence-voice.ts` | Update voice failure mapping, demo/local readiness handling, start gating, and Ask Hermes error recovery while preserving cleanup and duplicate-trigger guards. | \~90 | | `src/components/hermes/intelligence/intelligence-portal.tsx` | Derive Intelligence readiness from automatic local readiness, remove manual admin setup recovery copy, keep product-facing recoveries, and gate controls by real blocker states. | \~120 | | `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` | Add regressions for local readiness success, demo/local-readiness failure, token failure, provider-key failure, broker failure, provider failure, offline, media failure, and duplicate prevention. | \~130 | | `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` | Add portal tests for local success, typed Ask Hermes, demo/privacy, token failure, broker/provider recoveries, disabled controls, and absence of manual admin setup copy. | \~150 | | `tests/e2e/hermes-intelligence.spec.ts` | Adjust route-level Intelligence smoke expectations only if existing smoke asserts old admin-disabled wording. | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Typed Ask Hermes is enabled in normal local mode when `admin.canUseAdmin` is true, token is present, chat is not pending, and no voice Ask Hermes request is in flight. * [ ] Start Voice is enabled in normal local mode when local readiness, token, browser media, broker, provider key, and online state are available. * [ ] Normal local Intelligence copy no longer tells the operator to enable local Hermes admin mode. * [ ] Demo/privacy, offline, missing-token, rejected-token, provider-key, broker, microphone, timeout, and provider failures show specific recovery guidance. * [ ] Hook cleanup still stops media tracks, closes data channel and peer resources, aborts active requests, and resets timers. ### Testing Requirements * [ ] Voice hook tests cover successful local start, broker launch failure, token failure, missing provider key, provider failure, microphone denial, offline state, duplicate start prevention, and duplicate Ask Hermes prevention. * [ ] Portal tests cover local ready controls, typed Ask Hermes result rendering, demo/privacy gating, token failure recovery, voice failure recovery, and no manual admin setup copy. * [ ] Route-level Intelligence smoke is updated if it asserts superseded copy. ### Non-Functional Requirements * [ ] Browser-facing recovery text does not expose provider keys, bearer tokens, raw provider payloads, raw prompts, transcripts beyond active in-memory UI state, auth JSON, local usernames, private paths, or command output. * [ ] No new global `findtrend` identifier, runtime dependency, database artifact, or generated private data is added. * [ ] Local control-plane protections remain intact: loopback, Host-header, same-run token, schema, timeout, safe error, redaction, no-shell argv, and path confinement are not weakened. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused hook and portal tests pass *** ## 8. Implementation Notes ### Working Assumptions * `admin.canUseAdmin` is the correct local readiness input for Intelligence controls during this session: Session 03 made `canUseAdmin` depend on `writeReady` and same-run token availability, and the current portal already consumes `UseHermesAdminResult`. Planning can proceed because this avoids a second readiness contract. * `adminEnabled` may remain present as a compatibility field, but Intelligence should stop using it for normal local copy: Session 03 keeps `adminEnabled` as a compatibility mirror while Phase 41 requires removal of manual admin setup posture from shipped local user paths. * The e2e file may only need expectation updates, not new browser automation: existing unit and component tests already exercise most hook and portal behavior, and the session stub asks for focused portal and voice/intelligence hook tests. ### Conflict Resolutions * `.spec_system/PRD/PRD_UX.md` still describes Hermes and OpenClaw agent pages with read-only/default-off admin boundaries, while AGENTS, the master PRD, Phase 41 PRD, CONSIDERATIONS, SECURITY-COMPLIANCE, and Session 06 require local all-access Intelligence behavior. Phase 41 wins for current implementation; the older UX text is a current-state documentation gap for later Phase 41 documentation/spec-memory sessions. * `src/hooks/use-hermes-intelligence-voice.ts` currently names missing readiness `admin-disabled`, while Session 06 requires removing normal local manual admin recovery copy. The chosen interpretation is to rename the Intelligence-facing failure code and copy while leaving `useHermesAdmin()` broad mutation state names for Session 08 and broader compatibility work. ### Key Considerations * Preserve provider-key, credential, voice token, broker, demo/privacy, offline, and dependency blockers. * Do not claim voice or Intelligence execution unless route and tests prove real execution or a recoverable failure. * Keep browser-visible recovery text safe and product-facing. * Keep generated private runtime data out of git. ### Potential Challenges * `admin.canUseAdmin` false can mean several states: use status, chat state, token, offline, and demo mode to choose specific recovery copy. * Removing `admin-disabled` from Intelligence types can require coordinated test fixture updates: update hook, portal, and exported type expectations together. * Voice and typed Ask Hermes have separate in-flight guards: keep both guards covered so duplicate triggers do not create multiple chat streams or broker starts. ### Relevant Considerations * \[P41] **Local access default migration**: Intelligence must no longer treat normal local mode as manually disabled. * \[P41] **Do not accept scaffolding as delivery**: The plan requires real hook behavior, visible results, recoveries, and tests. * \[P38/P40] **Local control-plane gates are defense in depth**: Token and loopback checks stay automatic security controls. * \[P40/P41] **Write safeguards are reusable**: Existing token, bridge, and cleanup protections must be reused while copy and readiness change. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Start Voice or Ask Hermes could remain disabled in normal local all-access mode because of legacy admin copy or stale gate checks. * Token, provider, broker, and offline failures could collapse into generic disabled copy, hiding the actual recovery path. * Async voice resources could leak media tracks, peer connections, channels, abort controllers, or timers after failure or portal close. *** ## 9. Testing Strategy ### Unit Tests * Add or update `src/hooks/__tests__/use-hermes-intelligence-voice.test.tsx` for local start success, missing token, rejected token, missing provider key, broker launch failure, provider failure, microphone denial, offline, cleanup, and duplicate prevention. ### Integration Tests * Add or update `src/components/hermes/intelligence/__tests__/intelligence-portal.test.tsx` for enabled local controls, typed Ask Hermes transcript rendering, demo/privacy gating, token failure recovery, voice failure recovery, and no manual admin setup copy. * Update `tests/e2e/hermes-intelligence.spec.ts` only if existing route smoke expects legacy admin-disabled wording. ### Runtime Verification * Run focused Vitest files for the hook and portal. * Run broader targeted Hermes/Intelligence tests if focused changes affect shared contracts. ### Edge Cases * Token missing after `writeReady` is true. * Broker launch succeeds but health is not ready. * Broker launch returns missing provider key. * Provider session creation fails or times out. * Microphone access is denied after provider session succeeds. * Portal closes while voice is active. * Prompt submit is attempted while Ask Hermes is already in flight. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase41-session03-hermes-route-modes-and-hooks`, `phase41-session05-voice-token-bootstrap` * Depended by: `phase41-session08-hermes-mutation-controls`, `phase41-session14-end-to-end-test-matrix`, `phase41-session15-active-docs-and-runbooks` *** ## 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-session06-intelligence-action-access/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.