@gotcos/glasses-server 6.34.0 → 6.36.0

package/server/lib/session-stream-bus.ts

@@ -0,0 +1,150 @@
+// Per-session pub/sub for the live session stream.
+//
+// WHY THIS IS NOT `display-bus.ts`, given the instruction to reuse the SSE machinery.
+// The SSE machinery being reused is the TRANSPORT: `text/event-stream`, the header
+// block, `retry:`, the close-on-`req.close` teardown. That pattern is copied from
+// `routes/display.ts` verbatim and no second transport is introduced.
+//
+// The display BUS is a different object with two properties that are wrong here, and
+// both would be regressions rather than style disagreements:
+//
+//   1. It is a GLOBAL BROADCAST. Every `/display-stream` subscriber, which is to say
+//      every connected pair of glasses, receives every event published to it. Session
+//      events belong to one session detail view; broadcasting them would put another
+//      thread's tool trail on the lens, and the plan is explicit that the stream must
+//      never write the lens directly.
+//   2. It has a 200-EVENT SHARED REPLAY BUFFER. A tool-heavy turn emits hundreds of
+//      events in seconds. Pushing those through `emitDisplay` would evict the real
+//      display events a reconnecting client replays from, and that client would then
+//      be told `buffer_overflow` — a silent loss of query results caused entirely by
+//      a feature that only wanted to show a file being read.
+//
+// So: same transport, own keyspace. This module is deliberately small.
+//
+// NO REPLAY BUFFER HERE EITHER, and that is a decision rather than an omission. A
+// reconnecting client resumes LIVE and its 5s/15s/60s poll is what fills the gap it
+// missed; the contract gives it `seq` precisely so it can SEE the gap. Retaining a
+// per-session ring would add memory that grows with the number of sessions ever
+// opened, to duplicate a fallback that already exists and already works.
+
+import type { SessionStreamDraft } from './session-stream-events.js'
+
+/** A draft with the publish instant stamped. `seq` stays per connection. */
+export type PublishedSessionEvent = SessionStreamDraft & { at: number }
+
+export type SessionStreamListener = (event: PublishedSessionEvent) => void
+
+/**
+ * Concurrent subscribers to ONE session.
+ *
+ * Small on purpose. The realistic count is one pair of glasses plus, briefly, a
+ * reconnecting duplicate of it. A ceiling means a client stuck in a reconnect loop
+ * costs a bounded number of file watchers rather than an unbounded one.
+ */
+export const MAX_SUBSCRIBERS_PER_SESSION = 8
+
+/** Sessions streamed at once. Each carries at most one poller. */
+export const MAX_STREAMED_SESSIONS = 16
+
+const listeners = new Map<string, Set<SessionStreamListener>>()
+
+/**
+ * Sessions with a COS-spawned turn writing to them right now.
+ *
+ * A counter, not a boolean: it is set and cleared by the turn's own lifecycle and a
+ * counter cannot be left stuck true by an unbalanced pair the way a boolean can, since
+ * an extra clear floors at zero instead of silently disabling the gate.
+ */
+const attachedTurns = new Map<string, number>()
+
+export function sessionStreamKey(provider: string, sessionId: string): string {
+  return `${String(provider).trim().toLowerCase()}:${String(sessionId).trim().toLowerCase()}`
+}
+
+export function subscriberCount(key: string): number {
+  return listeners.get(key)?.size ?? 0
+}
+
+export function streamedSessionCount(): number {
+  return listeners.size
+}
+
+/** Null when a ceiling is reached; the caller answers 503 and the client polls. */
+export function subscribeSessionStream(key: string, listener: SessionStreamListener): (() => void) | null {
+  const existing = listeners.get(key)
+  if (existing && existing.size >= MAX_SUBSCRIBERS_PER_SESSION) return null
+  if (!existing && listeners.size >= MAX_STREAMED_SESSIONS) return null
+
+  const set = existing ?? new Set<SessionStreamListener>()
+  set.add(listener)
+  listeners.set(key, set)
+
+  let released = false
+  return () => {
+    // Idempotent. A double release from a close handler that fires twice must not
+    // delete a key another subscriber still holds.
+    if (released) return
+    released = true
+    const current = listeners.get(key)
+    if (!current) return
+    current.delete(listener)
+    if (current.size === 0) listeners.delete(key)
+  }
+}
+
+/**
+ * Fan out one draft.
+ *
+ * A throwing listener is isolated: one dead socket must not stop the others from being
+ * written, and must not propagate back into the provider stdout handler that called
+ * this. Iterating a COPY additionally means a listener that unsubscribes itself while
+ * being notified cannot corrupt the iteration.
+ */
+export function publishSessionStream(key: string, draft: SessionStreamDraft, at: number = Date.now()): number {
+  const set = listeners.get(key)
+  if (!set || set.size === 0) return 0
+  const event: PublishedSessionEvent = { ...draft, at }
+  let delivered = 0
+  for (const listener of [...set]) {
+    try {
+      listener(event)
+      delivered++
+    } catch {
+      /* a broken subscriber costs itself, never the publisher or its peers */
+    }
+  }
+  return delivered
+}
+
+/**
+ * Mark a COS-spawned turn as the live writer for this session.
+ *
+ * THE DUPLICATE-SUPPRESSION GATE. A Continue turn appears TWICE: once as the stdout
+ * this server tees in Phase 1, and again as the transcript records the provider writes
+ * to the very file Phase 2 is tailing. Without a gate the reader sees every tool call
+ * and every reply twice.
+ *
+ * stdout wins while it exists, because it is live rather than post-hoc. The watcher
+ * keeps advancing its offset through the suppressed region, so when the turn ends the
+ * cursor is already past those records and nothing is replayed.
+ */
+export function beginAttachedTurn(key: string): () => void {
+  attachedTurns.set(key, (attachedTurns.get(key) ?? 0) + 1)
+  let ended = false
+  return () => {
+    if (ended) return
+    ended = true
+    const next = (attachedTurns.get(key) ?? 0) - 1
+    if (next > 0) attachedTurns.set(key, next)
+    else attachedTurns.delete(key)
+  }
+}
+
+export function isAttachedTurnActive(key: string): boolean {
+  return (attachedTurns.get(key) ?? 0) > 0
+}
+
+export function __resetSessionStreamBusForTests(): void {
+  listeners.clear()
+  attachedTurns.clear()
+}

package/server/lib/session-stream-events.ts

@@ -0,0 +1,351 @@
+// The event grammar for a live agent session.
+//
+// ONE grammar, TWO sources. Phase 1 feeds it the NDJSON a COS-spawned `claude -p
+// --output-format stream-json` writes to stdout; Phase 2 feeds it the JSONL records
+// a desktop session appends to its transcript. For Claude those are the SAME record
+// shape — `{type:'assistant', message:{content:[...]}}` — which is why the two phases
+// can share one mapper instead of two that drift.
+//
+// PURE ON PURPOSE. No clock, no filesystem, no bus, no I/O. `seq` and `at` are
+// stamped by the transport, so every function here is a total function of its input
+// and can be tested by execution rather than by reading the source. That is the whole
+// reason the grammar is a separate module from the wiring: source-shape tests cannot
+// observe a mapping being wrong, and this is the part that CAN be wrong.
+//
+// THE CLOSED SETS ARE THE CONTRACT. `kind`, `state` and `verb` are fixed vocabularies
+// the client renders against. An unrecognised tool is NEVER a new verb: it is `other`
+// carrying its real name in `target`, so a provider adding a tool tomorrow degrades to
+// a readable line instead of an unrenderable one.
+
+/** Closed set. A provider tool name that is not in the table maps to `other`. */
+export type SessionStreamVerb = 'read' | 'edit' | 'write' | 'bash' | 'search' | 'task' | 'other'
+
+/** Closed set. */
+export type SessionStreamState = 'working' | 'idle' | 'done'
+
+export type SessionStreamDraft =
+  | { kind: 'tool'; verb: SessionStreamVerb; target: string; detail: string }
+  | { kind: 'prose'; text: string }
+  | { kind: 'status'; state: SessionStreamState }
+  | { kind: 'heartbeat' }
+
+/** A draft plus the transport's stamps. This is the JSON on the wire. */
+export type SessionStreamEvent = SessionStreamDraft & { seq: number; at: number }
+
+/** Providers whose records this grammar understands. */
+export type SessionStreamProvider = 'claude' | 'codex' | 'cursor'
+
+/**
+ * Prose ceiling.
+ *
+ * Matches `LATEST_REPLY_MAX` in agent-session-store.ts, which is what the polled
+ * detail payload already carries, so the streamed view and the polled view agree on
+ * how much of a reply a client ever sees. It also stops a single 587 KB transcript
+ * record — four of them exist in this Mac's largest transcript — from being written
+ * down an SSE pipe in one frame.
+ */
+export const PROSE_MAX_CHARS = 4_000
+
+/** A tool target is one glanceable line on a 576x288 lens, never a paragraph. */
+export const TARGET_MAX_CHARS = 80
+
+/** `+14 -2`, `120 lines`. Anything longer is not a detail. */
+export const DETAIL_MAX_CHARS = 40
+
+/**
+ * Marker appended when a value was cut.
+ *
+ * Three ASCII periods, not the single-character ellipsis: the G2 font has a limited
+ * glyph table and an unmapped character renders as tofu, which is worse than the
+ * truncation it is announcing.
+ */
+export const TRUNCATION_MARK = '...'
+
+/**
+ * Tool name to verb.
+ *
+ * Exact names, not prefixes or fuzzy matching. `BashOutput` is not `bash`: it is a
+ * different action, and collapsing it would make the HUD claim a command ran when it
+ * was only being read. Anything absent here is deliberately `other`.
+ */
+const VERB_BY_TOOL: Readonly<Record<string, SessionStreamVerb>> = {
+  read: 'read',
+  notebookread: 'read',
+  strreplace: 'edit',
+  edit: 'edit',
+  multiedit: 'edit',
+  notebookedit: 'edit',
+  write: 'write',
+  bash: 'bash',
+  shell: 'bash',
+  exec: 'bash',
+  exec_command: 'bash',
+  local_shell_call: 'bash',
+  grep: 'search',
+  glob: 'search',
+  search: 'search',
+  websearch: 'search',
+  webfetch: 'search',
+  toolsearch: 'search',
+  task: 'task',
+  agent: 'task',
+  skill: 'task',
+}
+
+export function verbForToolName(name: unknown): SessionStreamVerb {
+  if (typeof name !== 'string') return 'other'
+  return VERB_BY_TOOL[name.trim().toLowerCase()] ?? 'other'
+}
+
+/** Collapse to one line and cap. Every client-visible string passes through here. */
+export function oneLine(value: unknown, max: number): string {
+  if (typeof value !== 'string') return ''
+  const flat = value.replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim()
+  if (flat.length <= max) return flat
+  return flat.slice(0, Math.max(0, max - TRUNCATION_MARK.length)) + TRUNCATION_MARK
+}
+
+/** Last path segment. A full path is unreadable on the lens and leaks the tree. */
+export function basename(path: unknown): string {
+  if (typeof path !== 'string' || path.length === 0) return ''
+  const trimmed = path.replace(/\/+$/, '')
+  const cut = trimmed.lastIndexOf('/')
+  return cut < 0 ? trimmed : trimmed.slice(cut + 1)
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null
+}
+
+function countLines(value: unknown): number {
+  if (typeof value !== 'string' || value.length === 0) return 0
+  return value.split('\n').length
+}
+
+/**
+ * What this tool acted ON.
+ *
+ * A basename for file tools, the command for a shell, the pattern for a search, the
+ * description for a delegated task. For `other` the caller substitutes the real tool
+ * name, because a verb of `other` with an empty target says nothing at all.
+ */
+export function targetForTool(name: unknown, input: unknown): string {
+  const toolName = typeof name === 'string' ? name.trim() : ''
+  const args = asRecord(input)
+  if (!args) return ''
+  const lower = toolName.toLowerCase()
+
+  const filePath = args.file_path ?? args.path ?? args.notebook_path
+  if (typeof filePath === 'string' && filePath.length > 0) return oneLine(basename(filePath), TARGET_MAX_CHARS)
+
+  if (lower === 'bash' || lower === 'shell' || lower === 'exec' || lower === 'exec_command') {
+    const command = args.command ?? args.cmd
+    if (typeof command === 'string' && command.length > 0) return oneLine(command, TARGET_MAX_CHARS)
+  }
+
+  for (const key of ['pattern', 'query', 'skill', 'description', 'subject', 'prompt']) {
+    const value = args[key]
+    if (typeof value === 'string' && value.length > 0) return oneLine(value, TARGET_MAX_CHARS)
+  }
+  return ''
+}
+
+/**
+ * The small quantitative aside, or nothing.
+ *
+ * Only where it is derivable from the call itself. An Edit carries both strings, so
+ * the line delta is arithmetic rather than a guess; a Read does not carry the file, so
+ * it gets nothing rather than an invented number.
+ */
+export function detailForTool(name: unknown, input: unknown): string {
+  const args = asRecord(input)
+  if (!args) return ''
+  const lower = typeof name === 'string' ? name.trim().toLowerCase() : ''
+  if (lower === 'edit' || lower === 'strreplace' || lower === 'multiedit') {
+    const removed = countLines(args.old_string)
+    const added = countLines(args.new_string)
+    if (removed === 0 && added === 0) return ''
+    return oneLine(`+${added} -${removed}`, DETAIL_MAX_CHARS)
+  }
+  if (lower === 'write') {
+    const lines = countLines(args.content)
+    return lines === 0 ? '' : oneLine(`${lines} lines`, DETAIL_MAX_CHARS)
+  }
+  return ''
+}
+
+function toolDraft(name: unknown, input: unknown): SessionStreamDraft {
+  const verb = verbForToolName(name)
+  const target = targetForTool(name, input)
+  const readable = typeof name === 'string' ? oneLine(name, TARGET_MAX_CHARS) : ''
+  return {
+    kind: 'tool',
+    verb,
+    // An `other` verb names the tool, because the verb no longer does. A known verb
+    // that could not resolve a target also falls back to the name rather than to an
+    // empty line the reader cannot interpret.
+    target: verb === 'other' || target === '' ? (readable || target) : target,
+    detail: detailForTool(name, input),
+  }
+}
+
+function proseDraft(text: unknown): SessionStreamDraft | null {
+  if (typeof text !== 'string') return null
+  const trimmed = text.trim()
+  if (trimmed.length === 0) return null
+  const capped = trimmed.length <= PROSE_MAX_CHARS
+    ? trimmed
+    : trimmed.slice(0, PROSE_MAX_CHARS - TRUNCATION_MARK.length) + TRUNCATION_MARK
+  return { kind: 'prose', text: capped }
+}
+
+/**
+ * Anthropic-shaped content blocks, used by BOTH Claude and Cursor.
+ *
+ * Cursor writes `{role:'assistant', message:{content:[...]}}` with no top-level
+ * `type`; Claude writes `{type:'assistant', message:{content:[...]}}`. The blocks
+ * inside are identical, so they share this.
+ *
+ * `thinking` blocks are dropped. They are the model's private reasoning, they are
+ * long, and putting them on a six-line lens buries the tool trail the reader is
+ * actually following.
+ */
+function draftsFromContentBlocks(message: Record<string, unknown>): SessionStreamDraft[] {
+  const content = message.content
+  if (typeof content === 'string') {
+    const prose = proseDraft(content)
+    return prose ? [prose] : []
+  }
+  if (!Array.isArray(content)) return []
+  const out: SessionStreamDraft[] = []
+  for (const raw of content) {
+    const block = asRecord(raw)
+    if (!block) continue
+    if (block.type === 'text') {
+      const prose = proseDraft(block.text)
+      if (prose) out.push(prose)
+    } else if (block.type === 'tool_use') {
+      out.push(toolDraft(block.name, block.input))
+    }
+  }
+  return out
+}
+
+function draftsFromClaudeRecord(record: Record<string, unknown>): SessionStreamDraft[] {
+  const type = typeof record.type === 'string' ? record.type : ''
+
+  // The stream-json envelope's own lifecycle rows. `result` is the last line of a
+  // `claude -p` run and is the only place the turn's END is stated outright.
+  if (type === 'system' && record.subtype === 'init') return [{ kind: 'status', state: 'working' }]
+  if (type === 'result') return [{ kind: 'status', state: 'done' }]
+
+  // A user row is a tool RESULT or the prompt we just sent. Neither is news: the tool
+  // call was already announced, and the prompt came from this device.
+  if (type === 'user') return []
+
+  const role = typeof record.role === 'string' ? record.role : ''
+  if (type !== 'assistant' && role !== 'assistant') return []
+  const message = asRecord(record.message)
+  if (!message) return []
+  return draftsFromContentBlocks(message)
+}
+
+/**
+ * Codex, with ONE CHANNEL PER KIND, which is the point.
+ *
+ * Codex writes the same assistant text twice, as `event_msg/agent_message` AND as
+ * `response_item/message` with `role:'assistant'` (measured on this Mac: 6 of each in
+ * one rollout, plus 8 `response_item/agent_message`). Mapping both would double every
+ * reply on the lens. So prose comes from the event channel only and tools from the
+ * response-item channel only, and the duplication is unrepresentable rather than
+ * deduplicated after the fact.
+ *
+ * The honest cost: if a Codex build stops emitting `event_msg/agent_message`, prose
+ * goes quiet and the poll fallback carries the text. Quiet is the safe direction;
+ * doubled text is not.
+ *
+ * `codex exec --json` has also historically wrapped events as `{id, msg:{type,...}}`
+ * rather than `{type:'event_msg', payload:{...}}`. Both are accepted.
+ */
+function draftsFromCodexRecord(record: Record<string, unknown>): SessionStreamDraft[] {
+  const msg = asRecord(record.msg)
+  if (msg && typeof msg.type === 'string') return draftsFromCodexEvent(msg)
+
+  const type = typeof record.type === 'string' ? record.type : ''
+  const payload = asRecord(record.payload)
+  if (!payload) return []
+  if (type === 'event_msg') return draftsFromCodexEvent(payload)
+  if (type !== 'response_item') return []
+
+  const kind = typeof payload.type === 'string' ? payload.type : ''
+  if (kind === 'function_call' || kind === 'custom_tool_call' || kind === 'local_shell_call') {
+    // `arguments` is a JSON STRING on function_call; `input` is a raw string on
+    // custom_tool_call. Only the parseable one can yield a structured target.
+    let input: unknown = payload.input
+    if (typeof payload.arguments === 'string') {
+      try {
+        input = JSON.parse(payload.arguments)
+      } catch {
+        input = { command: payload.arguments }
+      }
+    } else if (typeof input === 'string') {
+      input = { command: input }
+    }
+    return [toolDraft(payload.name, input)]
+  }
+  return []
+}
+
+function draftsFromCodexEvent(payload: Record<string, unknown>): SessionStreamDraft[] {
+  const kind = typeof payload.type === 'string' ? payload.type : ''
+  if (kind === 'task_started') return [{ kind: 'status', state: 'working' }]
+  if (kind === 'task_complete' || kind === 'turn_complete') return [{ kind: 'status', state: 'done' }]
+  if (kind === 'agent_message') {
+    const prose = proseDraft(payload.message ?? payload.text)
+    return prose ? [prose] : []
+  }
+  return []
+}
+
+/**
+ * One parsed provider record to zero or more events.
+ *
+ * Zero is a normal answer and the common one: token counts, reasoning, world state,
+ * tool results, mode rows and attachments all map to nothing. A record this grammar
+ * does not recognise is silently dropped rather than rendered as a mystery line.
+ */
+export function draftsFromRecord(
+  provider: SessionStreamProvider,
+  record: unknown,
+): SessionStreamDraft[] {
+  const obj = asRecord(record)
+  if (!obj) return []
+  try {
+    if (provider === 'codex') return draftsFromCodexRecord(obj)
+    // Cursor shares Claude's content-block shape, keyed off `role` instead of `type`.
+    return draftsFromClaudeRecord(obj)
+  } catch {
+    // A malformed record costs one line of the trail. It must never cost the stream.
+    return []
+  }
+}
+
+/** One raw NDJSON line to events. Garbage in yields an empty array, never a throw. */
+export function draftsFromLine(provider: SessionStreamProvider, line: string): SessionStreamDraft[] {
+  const trimmed = typeof line === 'string' ? line.trim() : ''
+  if (trimmed.length === 0 || trimmed[0] !== '{') return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch {
+    return []
+  }
+  return draftsFromRecord(provider, parsed)
+}
+
+/** Draft plus transport stamps, in the field order the contract shows. */
+export function stampSessionEvent(draft: SessionStreamDraft, seq: number, at: number): SessionStreamEvent {
+  return { seq, at, ...draft }
+}

package/server/lib/session-stream-producer.ts

@@ -0,0 +1,138 @@
+// Phase 1: a Continue turn's own stdout, teed onto the session stream.
+//
+// `buildClaudeAttachedArgs` already spawns with `--output-format stream-json
+// --verbose`, and `attached-provider-adapter.ts` already holds that stdout. It reads
+// it for one purpose — proving the returned session id matches the target — and
+// discards everything else. This module is the second reader.
+//
+// THE ID SCAN IS UNTOUCHABLE. It is what aborts a turn whose child cannot be
+// identified, and it is mutation-tested. So the tee is wired as a SEPARATE `data`
+// listener, registered AFTER the scanner, holding no state the scanner can see, and
+// wrapped so it cannot throw into `emit()`. The scanner therefore runs first on every
+// chunk and its behaviour is unchanged whether or not this module exists. When no
+// observer is supplied the adapter registers no second listener at all, which is the
+// path every existing test already exercises.
+//
+// This module owns line assembly and publication. It does NOT own the grammar (that
+// is `session-stream-events.ts`, pure) or the transport (that is the SSE route).
+
+import {
+  draftsFromLine,
+  type SessionStreamDraft,
+  type SessionStreamProvider,
+} from './session-stream-events.js'
+import { beginAttachedTurn, publishSessionStream, sessionStreamKey } from './session-stream-bus.js'
+
+/**
+ * Ceiling on the incomplete trailing line held between chunks.
+ *
+ * A provider emitting one enormous line must not grow this without bound. Mirrors the
+ * 1 MB carry cap the adapter's own scanner already applies to the same stream, so the
+ * two readers cannot disagree about what is pathological.
+ */
+export const MAX_LINE_CARRY_CHARS = 1_000_000
+
+export interface LineAssembler {
+  /** Complete lines contained in everything pushed so far. */
+  push(chunk: string): string[]
+  /** The trailing partial line, if a caller wants it at end of stream. */
+  flush(): string[]
+}
+
+/**
+ * Split a byte stream into lines across chunk boundaries.
+ *
+ * Separate from the adapter's identical-looking logic on purpose: sharing it would
+ * mean the tee and the id scanner touch one piece of mutable state, which is exactly
+ * the coupling that would let a tee bug reach the scan.
+ */
+export function createLineAssembler(maxCarry: number = MAX_LINE_CARRY_CHARS): LineAssembler {
+  let carry = ''
+  return {
+    push(chunk: string): string[] {
+      if (typeof chunk !== 'string' || chunk.length === 0) return []
+      carry += chunk
+      const parts = carry.split('\n')
+      carry = parts.pop() ?? ''
+      if (carry.length > maxCarry) carry = ''
+      return parts
+    },
+    flush(): string[] {
+      const rest = carry
+      carry = ''
+      return rest.trim().length > 0 ? [rest] : []
+    },
+  }
+}
+
+export interface AttachedTurnStream {
+  /** Wire this as the adapter's `observeStdout`. Never throws. */
+  observeStdout(chunk: string): void
+  /** Call exactly once when the turn settles, whatever its outcome. Never throws. */
+  finish(outcome: 'done' | 'idle'): void
+}
+
+export interface AttachedTurnStreamOptions {
+  provider: SessionStreamProvider
+  sessionId: string
+  /** Injected for tests. Production uses the module bus. */
+  publish?: (key: string, draft: SessionStreamDraft) => void
+}
+
+/**
+ * Open a stream for one attached turn.
+ *
+ * Publishes `status: working` immediately, so a client that subscribes mid-turn is not
+ * left guessing, then one event per grammar-recognised stdout record, then exactly one
+ * terminal `status` on `finish`.
+ *
+ * `finish` is idempotent and MUST be called on every exit path including failure. It
+ * is what lifts the duplicate-suppression gate; leaving it held would make the session
+ * permanently silent for Phase 2, which is a far worse failure than a duplicated line.
+ */
+export function createAttachedTurnStream(options: AttachedTurnStreamOptions): AttachedTurnStream {
+  const key = sessionStreamKey(options.provider, options.sessionId)
+  const publish = options.publish ?? ((k, draft) => { publishSessionStream(k, draft) })
+  const assembler = createLineAssembler()
+  const endTurn = beginAttachedTurn(key)
+  let finished = false
+
+  const emit = (draft: SessionStreamDraft) => {
+    try {
+      publish(key, draft)
+    } catch {
+      /* publication is observation; it never affects the turn that produced it */
+    }
+  }
+
+  emit({ kind: 'status', state: 'working' })
+
+  return {
+    observeStdout(chunk: string): void {
+      try {
+        for (const line of assembler.push(chunk)) {
+          for (const draft of draftsFromLine(options.provider, line)) emit(draft)
+        }
+      } catch {
+        /* a malformed chunk costs its own events and nothing else */
+      }
+    },
+    finish(outcome: 'done' | 'idle'): void {
+      if (finished) return
+      finished = true
+      try {
+        for (const line of assembler.flush()) {
+          for (const draft of draftsFromLine(options.provider, line)) emit(draft)
+        }
+      } catch {
+        /* fall through: the terminal status and the gate release matter more */
+      }
+      emit({ kind: 'status', state: outcome })
+      try {
+        endTurn()
+      } catch {
+        /* the gate is a Map delete; there is no failure mode to report */
+      }
+    },
+  }
+}