openchamber/packages/web/server/lib/session-assist/DOCUMENTATION.md

# Session Assist

Server-side watcher that generates a short recap of the agent's last reply
and one suggested user follow-up with the small model
(`lib/small-model`), storing both on the session's metadata under
`metadata.openchamber.assist`.

## Flow

1. `createSessionAssistRuntime` is a consumer of the server's global SSE
   fan-out (`index.js` → `onPayload`), riding the same upstream connection as
   notifications. Purely event-driven — dormant sessions never generate
   anything, there is no backfill and no session scanning.
2. `session.status: idle` arms a 60-second per-session timer; any `busy`/
   `retry` status or a user `message.updated` clears it (the "1 minute of
   quiet" rule).
3. On fire: fetch the session (skip sub-agent sessions with `parentID`),
   take the LAST exchange only — the final assistant reply plus the user
   message it answered (assistant `parentID` → user id) — and call
   `generateSmallModelText` with the
   session's own provider/model taken from the last assistant message — so
   the utility call spends the same subscription as the conversation.
   `restrictToPreferredProvider` forbids the resolver's global fallback:
   conversation content never goes to a provider the user didn't pick for
   the session, unless the small model was chosen explicitly (settings
   override or opencode config). A resolver 404 is silently skipped.
4. The requested JSON fields (`recap`, `suggestion`, or both) are clamped and
   PATCHed onto the session metadata together with `forMessageID` (the last
   assistant message id) and `generatedAt`. Before writing, the session tail is
   re-checked (a stale result is dropped) and the metadata is merged from a
   fresh session read so concurrent metadata writes made during generation are
   preserved.

## Settings gate

`sessionRecapEnabled` and `sessionSuggestionEnabled` in OpenChamber settings
(Settings → Chat, default on) are hard generation switches checked at fire
time. When both are off, no small-model calls run and nothing is written. When
one is on, the runtime still makes at most one small-model call and asks only
for that field. The UI also hides disabled payload types immediately.

## Freshness contract (no clearing writes)

Clients do not need the payload to be deleted: they render it only while
`assist.forMessageID` still equals the session's last assistant message id
(and the session is idle). Any new message invalidates the payload
everywhere instantly and offline; the next idle cycle overwrites it.

## UI consumers (packages/ui)

- `lib/sessionAssistMetadata.ts` — payload parsing.
- `hooks/useSessionAssist.ts` — freshness gating + the 1-minute quiet window
  for the recap (single timeout to the boundary, no polling).
- `components/chat/SessionRecapSpacer.tsx` — renders the recap inside the
  fixed-height reserved gap under the last message (height never changes).
- `components/chat/SessionSuggestionChip.tsx` — one tappable suggestion chip
  near the composer (desktop chips row + above the mobile pill); hidden as
  soon as the composer has any content. Tap fills the input, never sends.

## Limitations

- The watcher lives in the web server, so VS Code (extension-only, no web
  server) does not generate assists; it still renders payloads produced by a
  web/desktop instance of the same OpenCode server via `session.updated`.
- Metadata payloads ride every `session.updated` event — keep the clamps
  (`RECAP_CHAR_LIMIT`, `SUGGESTION_CHAR_LIMIT`) small.