> 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-session12-compact-and-chat-polish/spec.md). # Session Specification **Session ID**: `phase40-session12-compact-and-chat-polish` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: a70ed3778f95d75fb53dd2560cdfe95cb492a4c7 *** ## 1. Session Overview This session finishes the next chat polish slice in the Phase 40 Hermes semantic port. It adds a compact flow that asks Hermes for a summary, starts a fresh local chat after the summary succeeds, and shows the carryover as visible chat context bound to that one active chat instance. This is the next executable session because the analyzer reports Phase 40 sessions 1 through 11 complete, and session 12 depends on Session 04 chat runtime behavior plus Session 11 selector/context layout. It also unblocks Session 13 command UX, whose `/compact` slash action depends on this compact behavior being present. The work stays inside the existing split AI OS Hermes chat implementation. It should extend `HermesChatTab`, `ChatComposer`, `ChatMessageList`, and chat helpers rather than copying upstream monolithic route code or adding a new bridge endpoint. *** ## 2. Objectives 1. Implement compact as a normal Hermes summary request followed by a fresh local chat with visible carryover scoped to the current chat instance. 2. Add assistant reply copy controls using local button and icon patterns without exposing private prompt, path, or transcript data beyond the visible reply text. 3. Add a "Hermes is thinking" elapsed state before first output with stable layout and timer cleanup. 4. Narrow startup-warning filtering so only known Hermes startup diagnostics are suppressed while legitimate model replies beginning with `Warning:` remain visible. *** ## 3. Prerequisites ### Required Sessions * [x] `phase40-session04-chat-overrides-and-runtime` - Per-chat model/provider options, runtime stream safeguards, and `info` event parsing are available. * [x] `phase40-session11-chat-model-selector-and-context-meter` - Chat selector, context meter, controlled model state, and composer toolbar placement are available. ### Required Tools Or Knowledge * React 19 component state and effect cleanup patterns. * Existing `UseHermesAdminResult.chat.sendPromptForTranscript` and `sendPrompt` contracts. * Existing Hermes chat component and helper ownership under `src/components/hermes/chat/`. * Vitest, Testing Library, and happy-dom timer/clipboard test patterns. ### Environment Requirements * Repository dependencies installed with the pinned Bun version. * No live Hermes credentials are required for component and hook tests. * Demo mode and public surfaces remain read-only and fixture-safe. *** ## 4. Scope ### In Scope (MVP) * AI OS chat users can compact the current visible chat context - Use the existing admin transcript helper to request a summary and avoid a new bridge write path. * AI OS chat users can continue in a fresh local chat after compaction - Show a visible carryover message that is bound to the current fresh chat instance. * AI OS chat users can copy assistant replies - Add stable accessible copy controls on assistant messages and streamed replies only. * AI OS chat users can see that Hermes is still preparing an answer - Replace the generic typing dots before first output with elapsed thinking copy that does not shift layout. * AI OS chat users do not lose legitimate `Warning:` replies - Filter only known startup-warning lines and preserve model-authored warning text. * Product language remains AI OS aligned - Keep "Hermes Intelligence" for the portal and use "Voice" only for speech-specific controls or recovery copy. ### Out Of Scope (Deferred) * Command menu and slash actions - Reason: Session 13 owns command UX after compact flow exists. * Renaming the Intelligence portal to Voice - Reason: Phase 40 explicitly preserves Hermes Intelligence as the broader typed, spoken, and visual reasoning surface. * Claiming exact context reclamation - Reason: compact is a summary-and-fresh-chat flow, not proof of exact tokenizer or context-window recovery. * Documentation updates - Reason: Session 17 updates docs after implementation behavior ships and tests pass. *** ## 5. Technical Approach ### Architecture Keep compact behavior in `HermesChatTab`, where prompt state, selected session, local messages, selected model, grounding options, and write gates already meet. Use `admin.chat.sendPromptForTranscript` for the summary request so compact remains a normal Hermes chat request through the existing admin boundary. After a successful transcript result, clear the selected session, reset ordinary prompt and attachment state, and append a visible assistant carryover message to the new local chat. Carryover must be scoped by an internal local chat instance identifier rather than only by `selectedSessionId`. Starting a new chat, selecting a historical session, resetting, canceling in-flight work, or leaving demo/live mode should clear stale carryover so the summary cannot appear in an unrelated chat. Reply copy and thinking-state polish belong in `ChatMessageList` because it owns rendered messages and stream output. Warning filtering should be a small helper in `chat-types.ts` so thread messages, local messages, stream output, and tests all share one rule. ### Design Patterns * Existing admin boundary: reuse `sendPromptForTranscript` and `sendPrompt` instead of adding a compact endpoint. * Scoped lifecycle state: compact and thinking timers reset on chat/session changes and clean up intervals on unmount. * Product-only UI states: status copy stays concise and avoids raw bridge diagnostics, paths, prompts, provider payloads, or tokens. * Local helper extraction: warning filtering, compact prompt creation, and carryover message construction live with other chat helpers for focused tests. *** ## 6. Deliverables ### Files To Create No new source files are planned. This session extends the existing Hermes chat component boundary. ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/chat/hermes-chat-tab.tsx` | Add compact request state, local chat instance scoping, carryover lifecycle, compact send option merging, and reset/cancel cleanup. | \~180 | | `src/components/hermes/chat/chat-composer.tsx` | Add compact action control and status copy in the existing composer action row with stable disabled states. | \~70 | | `src/components/hermes/chat/chat-message-list.tsx` | Add assistant reply copy controls, elapsed thinking state, filtered message rendering, and accessible feedback. | \~170 | | `src/components/hermes/chat/chat-types.ts` | Add compact prompt/carryover helpers, startup-warning filtering, and any small shared types. | \~130 | | `src/components/hermes/chat/index.ts` | Export any new chat helpers or types needed by tests. | \~10 | | `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` | Cover compact carryover isolation, copy controls, thinking elapsed state, warning filtering, and label boundaries. | \~260 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Compact requests a Hermes summary through the existing admin chat boundary and starts a fresh local chat only after a successful summary. * [ ] Compact carryover is visible in the fresh chat and cannot appear after selecting another thread, starting another new chat, resetting, canceling, or toggling demo/live mode. * [ ] Compact uses the currently selected ordinary model or MoA preset options when requesting the summary. * [ ] Assistant replies and streamed replies expose copy controls with accessible labels and success/failure feedback. * [ ] The pre-output state shows "Hermes is thinking" with elapsed time and cleans up its timer when output starts, the request ends, or the component unmounts. * [ ] Known startup-warning lines are suppressed, and a legitimate model response beginning with `Warning:` remains visible. * [ ] "Hermes Intelligence" remains the chat portal label; "Voice" is not introduced for non-speech chat controls. ### Testing Requirements * [ ] Focused component tests cover compact success, compact failure/abort, carryover isolation, copy controls, elapsed thinking, warning filtering, and label language. * [ ] Existing model selector, context meter, image, grounding, and send payload tests remain compatible. * [ ] Existing admin hook transcript tests remain compatible. ### Non-Functional Requirements * [ ] Compact, copy, and thinking controls keep stable dimensions and do not overlap on mobile or desktop layouts. * [ ] Browser-facing UI exposes only safe labels and visible reply text. * [ ] No generated private data, raw local paths, auth JSON paths, API keys, tokens, account IDs, raw prompts, or raw bridge diagnostics are introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * Compact should reuse `admin.chat.sendPromptForTranscript`: the hook already captures streamed output as a transcript result, the bridge already preserves model/provider overrides, and the session stub says compact is a normal Hermes summary request rather than a new endpoint. * The compact carryover should be a local assistant message rather than hidden prompt state: the session requires visible carryover, and visible local state lets tests prove that carryover is bound to the active chat instance without persisting private transcript data. * Documentation changes are deferred to Session 17: the Phase 40 plan explicitly says docs must describe shipped behavior only after implementation exists. ### Conflict Resolutions * Phase 40 source detail groups command menu and compact as adjacent upstream route behavior, while the spec-system stubs split compact into Session 12 and command UX into Session 13. The selected interpretation follows the analyzer's candidate order and the session stubs: Session 12 implements compact and chat polish only; Session 13 adds command menu and slash actions after this session. * Upstream Voice naming does not override AI OS product language. The Session 12 stub, Phase 40 decisions, and repository instructions all say to keep "Hermes Intelligence" for the portal and use "Voice" only for speech-specific controls. ### Key Considerations * Keep route `src/routes/agents.hermes.tsx` thin and unchanged unless implementation discovers an actual wiring issue. * Preserve the Session 11 selector/context toolbar and avoid crowding the composer action row. * Do not leak image private paths, grounding seed context, raw prompt bodies, or transcript internals through compact status copy. * Do not add a persisted compact history store; compact carryover is session-scoped UI state. ### Potential Challenges * The transcript helper also drives `admin.chat.output`; compact implementation must avoid leaving the summary as a normal streamed reply before seeding the fresh carryover. * Stale carryover can survive state transitions if local chat identity is only inferred from `selectedSessionId`; use an explicit local instance key and reset paths. * Clipboard APIs may be unavailable in happy-dom or restricted browsers; provide safe feedback and tests that mock success and failure. * Warning filtering can become too broad; keep the allowlist to known startup diagnostic prefixes only. ### Relevant Considerations * \[P38] **Upstream ports are semantic, not wholesale**: Translate chat polish into existing AI OS chat owners instead of copying upstream route code. * \[P38] **Local control-plane gates are defense in depth**: Reuse the existing admin chat boundary and do not add new local write routes. * \[P38] **OpenAI Realtime keys stay environment-only**: Do not introduce browser key state or provider credential copy while preserving Intelligence naming. * \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Demo/public mode must remain fixture-only and write-disabled. * \[P00] **Stack conventions**: Stay within Bun, Vite 8, TanStack Start, React 19, Radix UI, and local component conventions. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Compact is an async write path; it needs duplicate-trigger prevention while in-flight and clear success, failure, abort, offline, and disabled states. * Carryover is a revisitable context; it must reset or revalidate on new chat, selected thread, cancel, reset, and demo/live transitions. * Copy controls and thinking status are interactive UI; they need platform-appropriate accessibility labels, focus behavior, input support, and stable layout. *** ## 9. Testing Strategy ### Unit Tests * `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx`: compact summary request options, successful carryover message, failed/aborted compact state, carryover isolation across selected sessions and new chat, copy reply success/failure, elapsed thinking with fake timers, startup-warning filtering, and Intelligence label language. * `src/hooks/__tests__/use-hermes-admin.test.tsx`: run existing transcript and send payload tests to prove compact can continue relying on the hook contract. ### Integration Tests * `src/components/hermes/__tests__/hermes-sections.test.tsx`: run existing page-level chat wiring coverage if component props or exports change. ### Runtime Verification * Start the app with `bun run dev` and inspect `/agents/hermes` at desktop and mobile widths. * Verify compact, copy, cancel, reset, model selector, context meter, attach image, send, and Intelligence controls wrap without overlap. ### Edge Cases * Compact clicked while chat or upload is in flight. * Compact with selected historical session messages, local new-chat messages, stream output, attachments, and no visible messages. * Compact summary fails, aborts, or returns empty output. * User selects a different thread after compact succeeds. * Clipboard success, clipboard failure, and unavailable clipboard API. * Stream output starts with a known Hermes startup warning versus a legitimate model-authored `Warning:` reply. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase40-session04-chat-overrides-and-runtime`, `phase40-session11-chat-model-selector-and-context-meter`. * Depended by: `phase40-session13-command-ux-and-slash-actions`, `phase40-session17-docs-metadata-and-gitignore-closeout`, `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-session12-compact-and-chat-polish/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.