> 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-session04-chat-overrides-and-runtime/spec.md).

# Session Specification

**Session ID**: `phase40-session04-chat-overrides-and-runtime` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-02 **Base Commit**: 991444067326cc8cada6e19fd3b94c9459e1564b

***

## 1. Session Overview

This session adds per-chat Hermes model and provider overrides to the existing AI OS admin chat bridge without building the later visual model selector. The work extends the current chat option contract, hook payload construction, and `/__hermes_chat` server-side parser so one chat request can target a selected ordinary model or a MoA preset while preserving session resume, image prompts, Knowledge Graph grounding, graph/yolo tool options, and the non-shell argv boundary.

The session is next because Session 02 expanded the browser-safe model, provider, configured-provider, and MoA preset response shape, and Session 03 created the shared redaction layer required before new browser-visible diagnostics. Session 04 consumes those foundations in the chat write path.

The runtime portion ports only safeguards that fit the current AI OS split bridge: unbuffered and terminal-safe child process output, heartbeat comments, pre-output timeout, post-output idle success after output, browser disconnect cleanup, timer cleanup, and sanitized `info` SSE diagnostics that stay out of normal assistant message text.

***

## 2. Objectives

1. Carry `model?: string` and `provider?: string` through Hermes chat send options, hook payload construction, server parsing, and spawned argv.
2. Validate client and server override values with bounded allowlist rules, including provider `moa` for preset sends, and reject injection-shaped input with controlled errors.
3. Add chat streaming runtime safeguards for first output, post-output idle success, heartbeat, browser disconnect, and timer cleanup.
4. Parse and retain sanitized `info` SSE events as diagnostics without adding them to assistant message text or Intelligence transcripts.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session01-baseline-and-port-invariants` - Provides the local control-plane, semantic-port, chat SSE, graph, and privacy invariants this chat write path must preserve.
* [x] `phase40-session02-models-and-provider-readiness` - Provides expanded safe model/provider output, configured-provider summaries, and MoA preset discovery that future UI selectors will consume.
* [x] `phase40-session03-shared-redaction-foundation` - Provides reusable bridge-output sanitization and likely-secret detection for browser-visible diagnostics.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Existing Hermes admin chat route in `scripts/lib/hermes-admin-bridge.ts`.
* Existing chat hook and send option owner in `src/hooks/use-hermes-admin.ts` and `src/components/hermes/chat/chat-types.ts`.
* Existing admin SSE parser owner in `src/lib/hermes-admin-types.ts`.
* Existing focused tests for Hermes admin bridge, admin hook, admin parsers, and Intelligence event mapping.

### Environment Requirements

* Local checkout with dependencies installed or installable through `bun install`.
* No provider credentials, live Hermes login, or real local Hermes install required for the planned tests; mocked spawn fixtures should cover argv, timeout, stream, and redaction behavior.

***

## 4. Scope

### In Scope (MVP)

* AI OS chat callers can pass one safe `model` and optional `provider` override for a single Hermes chat request without mutating `~/.hermes/config.yaml`.
* AI OS chat callers can send a MoA preset by passing provider `moa` and the preset name as the model value.
* The admin bridge rejects invalid model/provider override values before spawn and keeps shell parsing disabled by passing every override as argv entries.
* The current graph/yolo/toolset, image prompt prefix, and session resume behavior remains compatible with override argv construction.
* The chat SSE stream includes sanitized `info` diagnostics where useful, but the hook and Intelligence mapper keep those diagnostics out of assistant message text.
* Chat child process handling has bounded first-output and post-output behavior with heartbeat, disconnect cleanup, timer cleanup, and safe errors.

### Out Of Scope (Deferred)

* Building the visual model selector - Reason: Session 11 owns the chat model selector and context meter UI.
* Adding command endpoint or command menu behavior - Reason: Sessions 05 and 13 own command execution and command UX.
* Renaming Intelligence, changing voice secrets, or changing Realtime provider behavior - Reason: Phase 40 keeps existing voice and Intelligence ownership unless later sessions explicitly change it.
* Persisting selected chat model/provider defaults - Reason: this session owns per-request overrides only and must not mutate Hermes config.

***

## 5. Technical Approach

### Architecture

Extend the existing chat write path in place. `HermesChatSendOptions` remains the client-side option carrier, `chatPayloadOptions()` remains the hook payload gate, and `handleChatRequest()` remains the server boundary that validates the body, resolves Hermes, opens SSE, spawns the child process, and handles runtime cleanup.

Use conservative identifier validation for `model` and `provider` on both the client and server. The exact regex should accept ordinary provider slugs, model IDs, and MoA preset names proven safe by Sessions 02 and 03, while rejecting whitespace, shell metacharacters, empty values, control bytes, and overlong values. The server remains the authority even when the client rejects bad input early.

Runtime safeguards should be implemented as small helpers inside `scripts/lib/hermes-admin-bridge.ts` unless a local helper already exists. The bridge should set terminal-safe spawn environment values, stream chunk output as assistant text, stream sanitized stderr/runtime notices as `info` diagnostics when appropriate, and clear all timers on success, error, timeout, spawn failure, or browser disconnect.

### Design Patterns

* Boundary validation: Validate request fields at the closest server boundary, with client-side validation only as early feedback.
* Non-shell argv arrays: Preserve the existing `spawn()` no-shell contract and assert option ordering in tests.
* Parser-owned contracts: Add the `info` SSE event to `src/lib/hermes-admin-types.ts` so hooks and Intelligence mapping consume one typed event shape.
* Local control-plane defense in depth: Keep loopback, token, admin, body-size, schema, timeout, safe-error, and redaction gates in the bridge path.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                              | Est. Lines |
| ---- | ---------------------------------------------------- | ---------- |
| None | No new production file is expected for this session. | 0          |

### Files To Modify

| File                                                   | Changes                                                                                                                                                     | Est. Lines |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/chat/chat-types.ts`             | Add optional chat model/provider override fields to the send option contract.                                                                               | \~10       |
| `src/hooks/use-hermes-admin.ts`                        | Validate and serialize chat override payload options, preserve duplicate-send guards, parse `info` events, and keep diagnostics out of output accumulation. | \~70       |
| `src/hooks/__tests__/use-hermes-admin.test.tsx`        | Cover model/provider serialization, invalid override rejection, duplicate in-flight send behavior, and `info` event handling.                               | \~90       |
| `src/lib/hermes-admin-types.ts`                        | Add typed `info` chat SSE event parsing and malformed event coverage hooks.                                                                                 | \~35       |
| `src/lib/__tests__/hermes-admin-types.test.ts`         | Add parser coverage for valid and invalid `info` events.                                                                                                    | \~45       |
| `src/lib/hermes-intelligence-events.ts`                | Map `info` events as diagnostics without adding them to assistant transcript text.                                                                          | \~30       |
| `src/lib/__tests__/hermes-intelligence-events.test.ts` | Cover `info` event activity mapping and transcript exclusion.                                                                                               | \~45       |
| `scripts/lib/hermes-admin-bridge.ts`                   | Add override validation, argv construction, runtime stream safeguards, heartbeat, timer cleanup, disconnect cleanup, and sanitized `info` SSE emission.     | \~200      |
| `scripts/lib/__tests__/hermes-admin-bridge.test.ts`    | Cover override argv, invalid values, graph/yolo compatibility, runtime timers, disconnect cleanup, and `info` redaction.                                    | \~220      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] A selected ordinary model can be sent for one chat request without mutating `~/.hermes/config.yaml`.
* [ ] A selected MoA preset sends provider `moa` and the preset name as the model override.
* [ ] Invalid model/provider values return controlled errors and cannot affect shell parsing or argv splitting.
* [ ] Existing session resume, graph, yolo, image prompt, and toolset behavior remains compatible with override sends.
* [ ] A pre-output hang fails with a timeout error, while a post-answer cleanup hang after output is treated as a successful turn.
* [ ] Sanitized `info` SSE events are parsed and retained as diagnostics but do not appear as assistant message text.

### Testing Requirements

* [ ] Focused Hermes admin bridge tests cover valid overrides, invalid values, arg ordering, graph/yolo compatibility, timeout behavior, disconnect cleanup, timer cleanup, and sanitized `info` events.
* [ ] Hook tests cover payload serialization, early invalid option rejection, duplicate-trigger prevention, and `info` event handling.
* [ ] Parser and Intelligence tests cover the `info` event contract and transcript exclusion.

### Non-Functional Requirements

* [ ] Browser-visible diagnostics remain redacted by the shared bridge-output helper.
* [ ] Local control-plane gates remain unchanged for loopback, token, admin, body-size, schema, timeout, and safe-error handling.
* [ ] Chat runtime timers and child processes are cleaned up on all terminal paths.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] UI-facing surfaces contain product-facing copy only; diagnostics remain in events, tests, or notes instead of normal assistant bubbles

***

## 8. Implementation Notes

### Working Assumptions

* Override values should use conservative identifier allowlists rather than catalog membership checks in this session: Session 04 explicitly asks for bounded regex validation, Session 02 already exposes browser-safe provider and MoA identifiers, and server-side rejection plus non-shell argv arrays keep planning safe without a live provider catalog.
* Runtime safeguards should stay in `scripts/lib/hermes-admin-bridge.ts`: the current `handleChatRequest()` already owns SSE headers, spawned Hermes child process lifetime, stderr handling, timeout behavior, and browser disconnect cleanup.

### Conflict Resolutions

* The session requires model/provider override plumbing while deferring the visual model selector. The chosen interpretation is to add type, hook, bridge, parser, and tests only; no new selector UI is planned until Session 11.
* The session asks for browser `info` SSE events while keeping diagnostics out of normal assistant text. The chosen interpretation is to parse and retain `info` events in the event stream, map them as diagnostics, and accumulate assistant text only from `chunk` events.

### Key Considerations

* Keep AI OS naming and local-only privacy boundaries; do not introduce new global `findtrend` identifiers or new browser-visible secret material.
* Keep graph grounding behavior compatible because Knowledge Graph chat sends `toolsets`, `yolo`, and `graph` options through the same hook path.
* Avoid claiming live provider proof; mocked bridge tests prove contracts, argv, and cleanup behavior for this session.

### Potential Challenges

* Override flag spelling may differ from an installed Hermes CLI: Mitigate by isolating override argv construction in a small helper and pinning expected ordering in focused tests.
* Runtime timers can race with child close or browser disconnect: Mitigate by centralizing finish/cleanup paths and asserting only one terminal SSE event is emitted.
* `info` events can accidentally leak into assistant text: Mitigate with parser, hook, message output, and Intelligence transcript tests.

### Relevant Considerations

* \[P38] **Local control-plane gates are defense in depth**: Preserve socket loopback, Host-header, token/admin, method, body-size, schema, timeout, and safe-error checks for the chat bridge.
* \[P38] **Upstream ports are semantic, not wholesale**: Map runtime safeguards into the existing AI OS bridge and hook owners instead of copying upstream middleware files.
* \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Route new diagnostics through the shared redaction helper before browser-visible SSE events.
* \[P26] **Knowledge Graph contract alignment**: Preserve graphify toolset and yolo behavior because Knowledge Graph grounded chat uses this send path.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* External input handling can accept unsafe model/provider strings unless validation exists on both the client and server.
* Streaming lifecycle changes can leak timers or child processes unless every terminal path runs cleanup exactly once.
* Diagnostics can pollute product-facing assistant messages unless `info` events are kept separate from `chunk` output.

***

## 9. Testing Strategy

### Unit Tests

* Add parser tests for valid, malformed, missing-field, and unsupported Hermes chat `info` events in `src/lib/__tests__/hermes-admin-types.test.ts`.
* Add Intelligence mapping tests proving `info` events create diagnostic activity without assistant transcript text in `src/lib/__tests__/hermes-intelligence-events.test.ts`.

### Integration Tests

* Add Hermes admin bridge tests for valid ordinary override argv, valid MoA override argv, invalid model/provider values, graph/yolo/toolset ordering, pre-output timeout, post-output idle success, heartbeat output, disconnect cleanup, spawn failure, and sanitized `info` events.
* Add hook tests for model/provider serialization, invalid option rejection, in-flight duplicate prevention, and `info` event retention.

### Runtime Verification

* Run the focused Phase 40 chat override suite with Vitest.
* Run script typecheck and app typecheck because this session touches both script-side bridge code and browser TypeScript.

### Edge Cases

* Empty, whitespace, overlong, control-character, shell-shaped, or path-shaped model/provider values are rejected.
* Provider `moa` with a safe preset model is accepted.
* Stderr output that contains private paths or token-shaped strings is redacted before `info` emission.
* A stream with no stdout before the pre-output timer expires fails; a stream with stdout followed by a hanging child succeeds after the post-output idle window.
* Browser disconnect kills the child and clears every active timer.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session01-baseline-and-port-invariants`, `phase40-session02-models-and-provider-readiness`, `phase40-session03-shared-redaction-foundation`
* Depended by: `phase40-session05-command-endpoint`, `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session12-compact-and-chat-polish`, `phase40-session13-command-ux-and-slash-actions`

***

## 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-session04-chat-overrides-and-runtime/spec.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.