> 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_38/session_09_intelligence_portal.md). # Session 09: Intelligence Portal **Session ID**: `phase38-session09-intelligence-portal` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours *** ## Objective Deliver the Hermes Intelligence portal and visualizers wired to the existing live Hermes chat backend. *** ## Non-Negotiable Delivery Bar The portal is done only when a user opens the Intelligence view, speaks, the words drive a real `/__hermes_chat` run, a real Hermes answer streams back, the answer is spoken and shown in the transcript, visualizers react to real chat events, and recovery paths are tested. *** ## Source Items * 3.3 `ADAPT`: Intelligence portal plus visualizers wired to live Hermes and voice. * `SKIP`: obsolete upstream `agent-core-3d.tsx`. * `SKIP - N/A`: upstream `INTEGRATION.md`. *** ## Scope ### In Scope (MVP) * Add portal, visualizer, mind-map, and synthetic-voice modules under AI OS component conventions. * Integrate the portal into the existing Hermes chat surface or launch it from there, not as a disconnected route. * Route voice `ask_hermes` calls through `admin.chat.send(...)` and the existing `/__hermes_chat` SSE stream. * Feed visualizers from real `admin.chat.events`. * Reserve synthetic output and attract mode for explicit idle/demo states only. * Speak answers through the Realtime session from Session 08 and render the same transcript in the portal. * Add tests for the voice tool-call bridge, event mapping, recovery states, and visual components. ### Out of Scope * Obsolete upstream `agent-core-3d.tsx`. * Internal-only upstream `INTEGRATION.md`. * Synthetic answers that replace the real Hermes backend. * A second chat backend or parallel chat route. * Dream engine endpoints except where already owned by Session 07. *** ## Detailed Port Item ### 3.3 Intelligence Portal And Visualizers Upstream added about 4,300 lines across `src/components/intelligence-portal.tsx`, `hermes-mind-3d.tsx`, Oracle visualizers, Aurora/Cosmos stages, `src/lib/mind-map.ts`, `src/lib/synthetic-voice.ts`, Hermes route integration, and Vite voice/Dream endpoints. * Upstream component and lib patch lines: 2096 through 5471. * Upstream route integration patch line: 5472. * Upstream Vite patch line: 6506. * Upstream sources: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/hermes-mind-3d.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/intelligence-portal.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-plasma.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-rider.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-sonar.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/oracle-waveform.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/stage-aurora.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/stage-cosmos.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/lib/mind-map.ts`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/lib/synthetic-voice.ts`, `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/routes/agents.hermes.tsx`, and `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/vite.config.ts`. * AI OS component target: `/home/aiwithapex/projects/aios/src/components/hermes/intelligence/`. * AI OS lib target: `/home/aiwithapex/projects/aios/src/lib/`. * AI OS integration target: `/home/aiwithapex/projects/aios/src/components/hermes/chat/hermes-chat-tab.tsx` or an equivalent portal launcher inside the existing Hermes chat surface. * Real backend requirement: voice `ask_hermes` tool calls must route through `src/hooks/use-hermes-admin.ts` `admin.chat.send(...)`, which fetches the `/__hermes_chat` SSE path in `/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts`. * Current AI OS hook/bridge landmarks: `src/hooks/use-hermes-admin.ts` around lines 707-789 and `scripts/lib/hermes-admin-bridge.ts` existing chat handling. * Event mapping: `intelEvents` must map from the same parsed SSE stream exposed by `admin.chat.events`. * Synthetic voice: `src/lib/synthetic-voice.ts` or equivalent may power idle or demo visualization only when clearly explicit, never as a substitute for live Hermes output. * Voice answer: spoken through the Session 08 Realtime session and shown in the portal transcript. * Skip: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/src/components/agent-core-3d.tsx` because upstream `INTEGRATION.md` marks it obsolete/dead. * Skip: `/home/aiwithapex/projects/claudeos/claude-os-v2.8.1/INTEGRATION.md` because it is internal merge guidance, not shippable product documentation. * Risk: high because this is a large new UI surface with voice, visualizers, and possible network egress. *** ## Prerequisites * [ ] Sessions 05 and 08 completed. * [ ] Voice UI and docs present OpenAI Realtime as default and `OPENAI_BASE_URL` as the compatible override. * [ ] Existing Hermes chat backend and `admin.chat` hook behavior are characterized. * [ ] Any new visualizer dependency is reviewed against bundle and security constraints before adding it. *** ## Deliverables 1. Intelligence UI with Aurora, Cosmos, and Classic modes. 2. Portal and visualizer components under AI OS Hermes conventions. 3. Voice `ask_hermes` tool-call bridge to the real `admin.chat.send(...)` backend. 4. Real SSE event mapping from `admin.chat.events` to portal visualizers. 5. Spoken answer playback plus transcript rendering. 6. Recovery states for mic denied, no key, provider down, and mid-stream abort. 7. Render tests, event mapping tests, and integration test that drives a mocked-spawn `/__hermes_chat` through the voice tool-call handler. *** ## Success Criteria * [ ] In a real browser, a spoken question starts a real Hermes chat run, streams a real answer, speaks it back, and shows it in the transcript. * [ ] Aurora, Cosmos, and Classic modes render and react to real chat events. * [ ] Synthetic/attract output is explicit idle/demo state only. * [ ] `ask_hermes` resumes the same Hermes session across turns where session continuity exists. * [ ] Mic-denied, no-key, provider-down, and mid-stream abort paths show actionable recovery states. * [ ] Integration tests prove a mocked-spawn `/__hermes_chat` stream reaches the portal through the voice tool-call handler. * [ ] Visual components have render tests. * [ ] `agent-core-3d.tsx` and `INTEGRATION.md` are recorded as skipped. --- # 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_38/session_09_intelligence_portal.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.