@belonguniverseai/react-sdk 0.4.2 → 0.5.0

package/dist/embed/voice/agent-queue.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Per-line FIFO for work an operator asks an agent to do WHILE that agent is
+ * already busy — the structure behind "queue two things on Agent 2, then
+ * drop one" (Slice 3 of the voice-operator plan). File-scope-singleton
+ * idiom, same as `line-slots.ts` / `voice-call-lines.ts` beside it: one
+ * module-level `Map<number, QueuedRequest[]>`, no class, no React.
+ *
+ * WHAT THIS REPLACES: today, sending work to a busy agent POSTs it
+ * immediately — the message lands in Postgres and the server's own drain
+ * loop (SAD §5.1 / CLAUDE.md §37) gets to it whenever the agent frees up.
+ * That queue is invisible (no way to ask "what's waiting for Agent 2?"),
+ * unorderable (no way to promote the third ask over the second), and
+ * undroppable (no way to take one back). This module is the queue moved
+ * into the browser, so a caller can read it back, drop an entry, or reorder
+ * it before anything is sent. (Wiring `dispatchToLine`'s busy-line path
+ * through this queue, and adding the voice-facing `manage_queue` tool, are
+ * later tasks — see NOT WIRED IN YET below.)
+ *
+ * WHY CALL-SCOPED AND NOT DURABLE — the trade-off, spelled out:
+ *
+ *   - A held `QueuedRequest` lives ONLY in this in-memory Map. Today's
+ *     behavior is strictly more durable: a queued follow-up is already
+ *     POSTed and sitting in Postgres the instant the operator says it, so it
+ *     survives a tab crash, a network blip, anything short of the session
+ *     itself being deleted. Moving the queue into the browser gives up that
+ *     durability in exchange for the operator being able to see and steer
+ *     it — that is the entire point, and the trade needs to be made with
+ *     open eyes, not by accident.
+ *   - `drainAllQueues()` is what keeps that loss narrow. It is the hang-up
+ *     flush: called as part of ending a call normally, it empties every
+ *     line's queue and hands back everything that was waiting so it can be
+ *     POSTed to the server exactly as if this module had never sat in front
+ *     of it. A normal end-of-call therefore loses nothing — the queue is
+ *     just a staging area the operator got to look inside before the same
+ *     dispatch that would have happened anyway.
+ *   - The durability genuinely AT RISK is narrower still than it first
+ *     sounds: a live voice call is not something a page reload survives
+ *     regardless of this module — there is no reload-resume contract for
+ *     the call itself (unlike the §41 guarantee for an already-dispatched
+ *     agent turn, which is a Postgres/Redis-backed run, not the call). So
+ *     "a reload loses the queue" is not a NEW failure this module
+ *     introduces; the call was already gone. What is genuinely new is the
+ *     sliver between "something got queued" and "the call ends" during
+ *     which the tab could crash before `drainAllQueues()` ever runs — a
+ *     real but narrow window, and the one honest cost of this design.
+ *
+ * NOT WIRED IN YET: this ships as a standalone module with its own tests
+ * and no production caller. A later task connects `enqueueForLine` /
+ * `dequeueForLine` to `dispatchToLine`'s busy-line path and `drainAllQueues`
+ * to the hang-up handler; another adds the voice-facing `manage_queue` tool
+ * on top of `peekQueue` / `dropQueuedAt` / `moveQueued`.
+ */
+export type QueuedRequest = {
+    readonly id: string;
+    readonly request: string;
+};
+/** Append `request` to the back of `line`'s queue, minting a fresh id
+ * (`nanoid()`, the same generator `line-dispatch.ts` uses for
+ * `clientMessageId`). Always succeeds — there is no bound on queue depth. */
+export declare const enqueueForLine: (line: number, request: string) => QueuedRequest;
+/** Pop and return the FRONT of `line`'s queue, or `null` when it's empty. */
+export declare const dequeueForLine: (line: number) => QueuedRequest | null;
+/** A read-only snapshot of `line`'s queue, front to back. Never mutates. */
+export declare const peekQueue: (line: number) => readonly QueuedRequest[];
+/** How many requests are waiting on `line`. */
+export declare const queueDepth: (line: number) => number;
+/** Remove and return the item at `index` in `line`'s queue, or `null` when
+ * `index` is out of range — an explicit `< 0 || >= length` bound (§10: never
+ * truthiness on a length or index), so a bad index is an honest miss rather
+ * than a silent no-op that could be mistaken for success. */
+export declare const dropQueuedAt: (line: number, index: number) => QueuedRequest | null;
+/** Move the item at `from` to position `to` in `line`'s queue (both bounds
+ * explicit, same discipline as `dropQueuedAt`). Returns `false` — leaving
+ * the queue completely untouched — when either index is out of range;
+ * `true` on success, including the no-op case `from === to` (a valid index
+ * moved to itself: nothing changes, but the request was satisfied, not
+ * refused). `to` is a position in the queue AFTER `from` is removed — the
+ * standard "move to position N" reading: moving the last item to `to: 0`
+ * makes it the new front. */
+export declare const moveQueued: (line: number, from: number, to: number) => boolean;
+/** The hang-up flush: empty EVERY line's queue and return everything that
+ * was waiting, in line-then-position order (line ascending, FIFO within a
+ * line) — the order a normal end-of-call should hand work to the server in.
+ * Exhaustive by construction: every line the map holds is visited and
+ * cleared, so nothing can be left behind. See the module doc for why this
+ * is what makes the queue's in-memory-only durability trade-off safe for a
+ * normal call end. */
+export declare const drainAllQueues: () => readonly {
+    readonly line: number;
+    readonly request: string;
+}[];
+/** The call-teardown clear: drop every line's queue without returning
+ * anything. Unlike `drainAllQueues`, this is for the paths that must not
+ * re-POST stale work — e.g. resetting state at the START of a fresh call. */
+export declare const resetQueues: () => void;
+/** Drop `line`'s held queue and report how many items were discarded — the
+ * ONE-line counterpart to `resetQueues()` (every line). For the paths that
+ * must not re-POST or re-dispatch one line's stale work without touching any
+ * other line's: `stop_agent` (voice-call.ts) clearing exactly the queue it
+ * just told the user was dropped, and `closeAgentLine` (voice-call-lines.ts)
+ * releasing a line whose held work must not resurrect onto the next
+ * occupant of the same number. An explicit `=== 0` check rather than
+ * truthiness (§10), same discipline as `dropQueuedAt`/`moveQueued`: a
+ * nothing-to-drop line reports `0` honestly instead of writing an empty
+ * array through `setQueue` for no reason. */
+export declare const clearQueueForLine: (line: number) => number;

package/dist/embed/voice/call-roster-store.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The voice call's agent ROSTER — the browser-side twin of the tenant
+ * roster minted server-side (`buildCallRoster` in
+ * apps/belong-cloud/src/features/voice/call-roster.ts) and threaded through
+ * `POST /v1/voice/call-token`'s `agents` field (`callAgentSpecSchema`,
+ * voice.schemas.ts). This is what lets the dock's rail, the call screen's
+ * agent board, and every spoken announcement address an agent by ROLE
+ * ("cli", "consulting") instead of a bare line number — and do so from the
+ * moment the dock boots, before any call has ever been started: the rail
+ * renders dock-wide with no call active, so it needs the LAST-KNOWN roster,
+ * not only one handed to it live off a fresh mint.
+ *
+ * Persisted per workspace, exactly like `line-slots.ts` beside it
+ * (`belong:voice-call-roster`, suffixed `:ws:<id>` when a workspace is in
+ * effect via `peekWorkspaceId()`) — a host workspace switch must not hand
+ * tenant A's roster (its titles, its CLI agent) to a rail rendering for
+ * tenant B.
+ *
+ * localStorage is a perimeter: the persisted roster is zod-validated on read
+ * and any junk (corrupted JSON, wrong shape, storage disabled) degrades to
+ * an EMPTY roster — same as "no call minted yet". The schema below is a
+ * deliberately independent, by-hand copy of the server's
+ * `callAgentSpecSchema`: the two packages ship separately and share no type
+ * module, so this is what keeps them honest (mirrors the existing
+ * `CallAgentSpec`/`callAgentSpecSchema` split already living server-side in
+ * `call-roster.ts` / `voice.schemas.ts`).
+ *
+ * Two fallback rules, and they are NOT the same rule:
+ *
+ *   - `lineForRole` / `roleForLine` on an EMPTY roster (nothing ever minted,
+ *     or a mint whose body failed to parse) fall back to the POSITIONAL
+ *     default that's been true since roles didn't exist: main=1, cli=2,
+ *     consulting=3. This is what stops a parse failure from bricking role
+ *     addressing mid-call — the switchboard still answers to
+ *     main/cli/consulting by position.
+ *   - On a NON-empty roster that simply doesn't have that role/line (a
+ *     tenant with no CLI), the same lookups return `null` instead — the
+ *     honest signal that THIS workspace has no such agent, which is what
+ *     later produces an `unknown_role` tool response rather than silently
+ *     addressing the wrong agent.
+ *
+ * `titleForRole` / `titleForLine` never return `null` — a title is always
+ * needed for display/announcement, so THEIR fallback is a string, applied
+ * uniformly regardless of whether the roster is empty or merely missing
+ * that entry. The two fallbacks are deliberately DIFFERENT shapes, not the
+ * same rule twice:
+ *
+ *   - `titleForRole` falls back to a ROLE-derived phrase ("the main agent" /
+ *     "the data agent" / "the analyst") — never a switchboard
+ *     number. Every voice tool call carries a role (it is the operator's
+ *     entire addressing vocabulary — see `voice-call.ts`'s
+ *     `resolveRoleLine`), so this fallback is always reachable from a role
+ *     the model already said out loud, and it feeds prose the model
+ *     SPEAKS: an empty roster (nothing minted yet, or a pre-roster backend
+ *     mid rolling deploy — `callTokenResponseSchema`'s `agents` field
+ *     legitimately defaults to `[]`) must not leak a bare "Agent 2" into
+ *     that prose.
+ *   - `titleForLine` falls back to `"the main agent"` for line 1 and
+ *     `` `Agent ${line}` `` otherwise — the "Agent N" convention the
+ *     switchboard used before roles existed. This one serves the UI's
+ *     numbered rail, which genuinely displays a switchboard slot number, so
+ *     a line-derived fallback is correct there and stays as-is.
+ */
+export type CallAgentRole = "main" | "cli" | "consulting";
+export type CallAgentSpec = {
+    readonly role: CallAgentRole;
+    /** The durable switchboard line underneath (`line-slots.ts`). */
+    readonly line: number;
+    /** What the voice calls this agent out loud. */
+    readonly title: string;
+    /** One sentence describing what this agent is for. */
+    readonly purpose: string;
+};
+/** Persist the roster minted for the current call. A whole-roster replace —
+ * never a per-entry patch — of whatever this workspace held before. */
+export declare const setCallRoster: (roster: readonly CallAgentSpec[]) => void;
+/** The current workspace's roster, or an empty array when nothing has been
+ * minted yet (or storage held junk). */
+export declare const peekCallRoster: () => readonly CallAgentSpec[];
+/** Persist the tenant's product name minted alongside the roster (U2) — a
+ * whole-value replace, same discipline as `setCallRoster`. */
+export declare const setProductName: (productName: string | null) => void;
+/** The current workspace's product name, or `null` when nothing has been
+ * minted yet, the tenant has none, or storage held junk. Used ONLY to
+ * localize the SDK's own UI copy (CallScreen's agent board, U2) — never fed
+ * into any string the model speaks or receives. */
+export declare const peekProductName: () => string | null;
+/** Resolve a role to its switchboard line. See the module doc: `null` only
+ * ever means "this NON-empty roster doesn't have that role" — an EMPTY
+ * roster falls back to the positional default instead. */
+export declare const lineForRole: (role: CallAgentRole) => number | null;
+/** Resolve a switchboard line to its role — the inverse of `lineForRole`,
+ * with the same two-rule fallback (EMPTY roster → positional; non-empty and
+ * missing → `null`). */
+export declare const roleForLine: (line: number) => CallAgentRole | null;
+/** What the voice calls this role out loud. Always a string — falls back to
+ * a ROLE-derived title (never a switchboard number, never `null`) when the
+ * roster has no entry for this role, whether the roster is empty or just
+ * missing it. */
+export declare const titleForRole: (role: CallAgentRole) => string;
+/** What the voice calls this line out loud. Always a string — falls back to
+ * `"the main agent"` (line 1) or `` `Agent ${line}` `` otherwise when the
+ * roster has no entry for this line, whether the roster is empty or just
+ * missing it. */
+export declare const titleForLine: (line: number) => string;
+/** Test-only: drop the persisted roster AND product name for the current
+ * workspace scope — they are minted together (the same call-token mint), so
+ * a test resetting one without the other would leak a stale product name
+ * (or roster) into the next case. */
+export declare const __clearCallRosterForTest: () => void;

package/dist/embed/voice/line-dispatch.d.ts

@@ -16,31 +16,70 @@
  * Workspace isolation (§28): a background line opened while the host is inside
  * a workspace must land in THAT workspace, not the shared legacy root — so the
  * create body carries the effective `workspaceExternalId` (absent when the host
- * runs unscoped). The line's registry label seeds the session title, so the
- * sessions list names the background conversation.
+ * runs unscoped). The line's registry label seeds the session title when one
+ * exists; otherwise (U4 — the common case for a freshly materialized line,
+ * since `dispatchToBackgroundLine` no longer seeds the registry label with the
+ * agent's own name) the REQUEST itself does, so the sessions list still names
+ * the background conversation by what it's actually about ("Reconcile the
+ * July invoices"), not the agent that happened to run it.
  *
  * BOOT RE-ATTACH (F3/R4): `attachLineReader` below is the ONE seam that wires
- * a line-run reader onto a line, shared by a fresh dispatch (this module,
- * right after a POST accepts a run) and `reattachPendingLineRuns` (called
- * once at boot, after `initAgentLines()` rehydrates the registry) resuming a
- * run that was still going when the page reloaded. Both paths persist the
- * binding (`persistSlotRun`) and wire the identical phase/approval/navigate/
- * artifact/finish/error callbacks — a reload must behave exactly like the
- * live dispatch it is standing in for, not a parallel, easier-to-drift copy.
+ * a VOICE-dispatched line-run reader onto a line, shared by a fresh dispatch
+ * (this module, right after a POST accepts a run) and `reattachPendingLineRuns`
+ * (called once at boot, after `initAgentLines()` rehydrates the registry)
+ * resuming a run that was still going when the page reloaded. Both paths
+ * persist the binding (`persistSlotRun`) and wire the identical phase/approval/
+ * navigate/artifact/finish/error callbacks — a reload must behave exactly like
+ * the live dispatch it is standing in for, not a parallel, easier-to-drift copy.
+ *
+ * TWO READER KINDS (BEL-90). This module now attaches two, and which callback
+ * set a caller gets is a correctness question, not a style one:
+ *
+ *   - `attachLineReader` — the voice-NARRATION reader. Its callbacks are not
+ *     plain setters: `deliverLineReply`/`deliverLineFailure` push
+ *     `conversation.item.create` events into an active voice call and ask the
+ *     model to respond, `notifyLinePhase` appends timeline rows and nudges
+ *     spoken progress, `deliverLineArtifact` opens a preview panel. Correct
+ *     for a run the operator dispatched BY VOICE.
+ *   - `attachLineProgressReader` — the plain-progress reader, for a run the
+ *     user started by TYPING that was still in flight at reload. It goes
+ *     through `reportRunLineProgress` and touches only the registry, so a
+ *     typed run can never make the agent start talking about background
+ *     progress mid-call.
  */
 /** Abort every live line reader and invalidate their callbacks (call teardown).
  * Subscribed below to fire whenever a call leaves in_call/connecting. */
 export declare const abortAllLineReaders: () => void;
+/** Test-only: drop every plain-progress reader (and the active-session latch)
+ * so a case never inherits either from the previous case. The narration
+ * readers have `abortAllLineReaders`; these deliberately do NOT ride on it — a
+ * voice call ending has nothing to do with a typed run still streaming. */
+export declare const __detachLineProgressReadersForTest: () => void;
 /**
- * BOOT RE-ATTACH (F3/R4): call this once, right after `initAgentLines()`
- * rehydrates the registry from persisted slots. Every background line (2/3)
- * whose slot carried a non-null `runId` already shows `status: "working"`
- * (`rehydratedLines()` in voice-call-lines.ts) — this re-attaches its reader
- * so the line actually converges to ready/failed via the SAME
- * `attachLineReader` a live dispatch uses, instead of sitting at an
- * honest-looking but permanently stuck "working". Line 1 never carries a
- * registry `runId` (see `AgentLine.runId`'s doc) and is skipped here — its
- * own reload-resume path is the stream-state store's, not this one.
+ * BOOT RE-ATTACH: call this once, right after `initAgentLines()` rehydrates
+ * the registry. A line rehydrated as `status: "working"` has a run that was
+ * still going when the page went away (`rehydratedLines()` in
+ * voice-call-lines.ts) — this attaches the reader that actually converges it
+ * to ready/failed, instead of leaving an honest-looking but permanently stuck
+ * "working".
+ *
+ * TWO paths, because the two dispatch kinds have genuinely different
+ * contracts (BEL-90 / B1 — see `attachLineProgressReader`'s doc):
+ *
+ *  - F3/R4, UNCHANGED — a line whose durable SLOT carries a runId was
+ *    dispatched by voice. It gets the narration reader, on every line that has
+ *    one, INCLUDING when its session is the one on screen. That last part is
+ *    load-bearing: `persistSlotRun(line, null)` in that reader's terminal
+ *    callbacks is the durable slot's clearer, and skipping the on-screen line
+ *    would leave a stale slot runId that rehydrates as "working" on every
+ *    future reload (§41). The transport's terminal now clears the slot too, so
+ *    both routes converge.
+ *  - BEL-90 — a line with NO slot runId but a fresh parked run cursor was
+ *    started by typing. It gets the plain-progress reader, and it is SKIPPED
+ *    when its session is the active one: ChatRoute is about to mount for that
+ *    session and its transport will claim the single reader. Skipping is safe
+ *    here precisely because a typed run writes no durable slot runId — there
+ *    is nothing that could get stuck.
  */
 export declare const reattachPendingLineRuns: (fetchFn?: typeof fetch) => void;
 export declare const dispatchToLine: (req: {

package/dist/embed/voice/line-run-reader.d.ts

@@ -1,60 +1,10 @@
-/**
- * Minimal SSE consumer for a BACKGROUND line's run stream — the Operator's
- * ear on lines the chat surface isn't showing. Reads the AI-SDK data-stream
- * protocol from `GET /v1/runs/:runId/stream` and surfaces only what the call
- * needs: tool phases, approval-needed, the final text, errors. No `useChat`,
- * no rendering, no reconnect/resume (that's `BelongChatTransport`'s job for
- * the foreground chat surface — a background line reader just watches once).
- * Fetch is injected for tests.
- *
- * Wire shapes mirror the real protocol pinned in `belong-chat-transport.ts` /
- * `belong-data-parts.ts` — NOT the placeholder `text-delta` / `finish` shapes
- * from the original task brief:
- *   - text is a DELTA part: `{ type: "text", id, text }` — accumulate `.text`.
- *   - `data-tool-call` carries a `state` ("started" | "completed" | "failed");
- *     only "started" is a phase change worth reporting.
- *   - `data-approval-request` carries a `state` ("pending" | "approved" |
- *     "rejected" | "amend_requested" | "expired"); only "pending" means an
- *     approval is newly needed.
- *   - `data-navigation` carries `{ routeName, params }` — a background agent
- *     asking the HOST to navigate. The foreground renderer executes these via
- *     `peekRouteHandler` (see `route-dispatch.ts`, the shared seam); a
- *     background line has no renderer to pick it up, so `onNavigate` here
- *     dispatches through that SAME seam instead. Unlike the foreground's
- *     reload-replay (guarded by its `historical` flag + `useFireOnce`), this
- *     reader has no reconnect/replay at all (see the module doc above) — each
- *     SSE line is parsed and applied exactly once by the read loop below, so
- *     no separate dedupe is needed here to keep a navigation from re-firing.
- *   - there is no `finish` / `error` part. The terminal signal is
- *     `data-status` with `status` ∈ "continuing" | "completed" | "cancelled" |
- *     "failed" | "throttled". "continuing" is the max-turns auto-continue —
- *     NOT terminal, keep reading the same stream. "completed" finishes with
- *     the accumulated text; "cancelled" | "failed" | "throttled" are errors.
- *
- * BOOT RE-ATTACH (F3/R4): this reader is also opened for a run that already
- * finished before the read starts (a persisted `runId` re-attached after a
- * reload — see `attachLineReader` in line-dispatch.ts). Two ways that shows
- * up on the wire, both a CLEAN convergence rather than a failure:
- *   - the run is still known server-side and just replays its full history
- *     (§36 — `GET .../stream` with no cursor replays from the start): the
- *     already-written terminal `data-status` event arrives like any other
- *     part and is handled by the SAME "completed"/"cancelled"/"failed"
- *     branch below — no special-casing needed, this is the ordinary path.
- *   - the run (or its task) is truly gone server-side — 404/410 — which
- *     reads identically to "nothing left to report", not an error: `onFinish`
- *     fires with empty text instead of `onError`, so a boot re-attach never
- *     paints a stale run as failed just because its record has since expired
- *     or the session behind it was deleted.
- *
- * SSE parsing here is LINE-BY-LINE (split on "\n", not "\n\n") — the server
- * sends exactly one `data:` line per event. `id:` lines carry the event
- * cursor (ignored — v1 has no reconnect/resume) and `:`-prefixed lines are
- * keepalive comments.
- */
+import { RunStatusKind } from '../../stream/belong-data-parts.ts';
 export type WatchLineRunInput = {
     readonly runId: string;
     readonly onPhase: (toolName: string) => void;
-    readonly onApprovalNeeded: () => void;
+    /** `reason` is the wire part's own `data.reason` — "" when the part omitted
+     * it (never `undefined`; the caller decides the fallback wording). */
+    readonly onApprovalNeeded: (reason: string) => void;
     readonly onNavigate: (data: {
         readonly routeName: string;
         readonly params: Readonly<Record<string, string>>;
@@ -65,6 +15,36 @@ export type WatchLineRunInput = {
         mimeType: string;
     }) => void;
     readonly onFinish: (finalText: string) => void;
-    readonly onError: (message: string, kind: "terminal" | "transport") => void;
+    /**
+     * The run did not finish cleanly. `cause` is a discriminated shape rather
+     * than a bare `"terminal" | "transport"` string because the two carry
+     * genuinely different data (§21): a TERMINAL knows exactly which non-success
+     * status the wire reported, and callers must be able to tell a user-pressed
+     * Stop (`cancelled`) from a real breakage (`failed`) — the transport already
+     * renders the first as an ordinary finish and only the second as an error,
+     * and a rail badge that disagrees is the §42 mistake. A TRANSPORT failure
+     * knows nothing about the run's state at all: the server task may well still
+     * be running.
+     */
+    readonly onError: (message: string, cause: {
+        readonly kind: "terminal";
+        readonly status: Exclude<RunStatusKind, "continuing">;
+    } | {
+        readonly kind: "transport";
+    }) => void;
+    /**
+     * "The stream just delivered something" — fired once per chunk read off the
+     * socket, INCLUDING the server's `: keepalive` comment every 15s (which
+     * `parseSseLine` otherwise drops). It carries no payload because its only
+     * job is liveness: BEL-90's progress reader is the sole listener on a
+     * backgrounded typed run after a reload, and the parked run cursor's
+     * age-out gate (`peekLiveParkedRun`) needs a re-stamp from SOMEONE or a run
+     * doing two minutes of silent tool work reads as dead (§41).
+     *
+     * OPTIONAL because only that one caller owns a cursor. The narration reader
+     * (`attachLineReader`) rehydrates from the durable slot runId, which has no
+     * age gate, so there is nothing for it to keep fresh.
+     */
+    readonly onTick?: () => void;
 };
 export declare const watchLineRun: (input: WatchLineRunInput, fetchFn?: typeof fetch) => (() => void);

package/dist/embed/voice/line-slots.d.ts

@@ -34,8 +34,12 @@
  * streaming server-side. Back-compatible the same way `line1` is: a bag
  * written before this field existed has no `runId` key at all, and the
  * schema defaults it to `null` (nothing was in flight when that bag was
- * written). Line 1 never carries a meaningful value here — its `runId` is
- * always `null` (see `AgentLine.runId`'s doc in voice-call-lines.ts).
+ * written). Line 1's slot `runId` stays `null` in practice — nothing dispatches
+ * to line 1 and `persistSlotRun` is the only writer — but do not read that as
+ * "line 1 has no run": the IN-MEMORY `AgentLine.runId` is no longer always null
+ * for line 1, since a reload seeds it from the parked run cursor (BEL-90 — see
+ * `AgentLine.runId`'s doc in voice-call-lines.ts). This field is the VOICE
+ * dispatch's durable binding specifically, not "the line's run".
  */
 /** Every line number that gets a persisted slot — all three agent lines. */
 declare const SLOT_LINES: readonly [1, 2, 3];

package/dist/embed/voice-call-lines.d.ts

@@ -31,10 +31,16 @@ export type AgentLine = {
     readonly lastText: string;
     /** The line's current run, for `stop_agent` to target — bound by the
      * line-run reader once a background dispatch's POST returns a runId, and
-     * cleared back to `null` when that run reaches a terminal state. Line 1
-     * (foreground) never gets this written: its runId is resolved at stop-time
-     * from the stream-state store instead (the same source the on-screen Stop
-     * button reads), so this stays `null` for line 1 always. */
+     * cleared back to `null` when that run reaches a terminal state.
+     *
+     * Line 1 never has this WRITTEN by a dispatch (line-dispatch.ts never
+     * dispatches to it), and its stop-time runId is still resolved from the
+     * stream-state store — the same source the on-screen Stop button reads. It
+     * is no longer always `null` for line 1, though: a REHYDRATE seeds it from
+     * the parked run cursor on every line alike (BEL-90 — see
+     * `inFlightRehydration`), because a run started by typing keeps streaming
+     * across a reload and a chip that reads "idle" for it is a lie. Nothing
+     * about the stop path changed; only the reload seed did. */
     readonly runId: string | null;
     /** The live "what is it doing right now" label (e.g. "writing code"),
      * written by `setLineStep` as phase notifications arrive while `status`
@@ -114,6 +120,20 @@ export declare const lineBoundToSession: (sessionId: string) => AgentLine | unde
  * already holds must SWITCH to Agent 1, not adopt (duplicate) it onto whatever
  * background line the user happens to be viewing. */
 export declare const lineOwningSession: (sessionId: string) => AgentLine | undefined;
+/**
+ * EVERY line bound to `sessionId` — the plural form `markSessionSeen` and
+ * `releaseLinesForSession` below already work in, for the same reason they do:
+ * more than one line can hold one session (line 1 aliases whatever the chat is
+ * showing, so a background line the user opened is held by both), and a legacy
+ * `belong:voice-line-slots` bag written before the `isBoundToAnotherLine`
+ * guards landed can rehydrate two background lines onto one session.
+ *
+ * `lineOwningSession` answers a different question — "which ONE agent should a
+ * History reopen switch to" — and stays singular. Anything that WRITES per-line
+ * state for a session (BEL-90's `reportRunLineProgress`) must use this one, or
+ * the second holder freezes at whatever it last said.
+ */
+export declare const linesOwningSession: (sessionId: string) => readonly AgentLine[];
 /** True when `sessionId` is already the session of some line OTHER than line
  * 1 — chat.tsx's line-1 aliasing guard uses this to skip rebinding line 1
  * onto a background line's session while the user is viewing it via
@@ -138,6 +158,26 @@ export declare const isBoundToAnotherLine: (sessionId: string) => boolean;
  */
 export declare const foregroundLineNumber: (sessionId: string | null) => number;
 export declare const openAgentLine: (label: string) => AgentLine | null;
+/**
+ * Materialize a line AT A GIVEN NUMBER, unlike `openAgentLine`'s lowest-FREE
+ * allocation. F1: role→line is fixed and positional (main=1, cli=2,
+ * consulting=3 — `call-roster-store.ts`), so a background dispatch to a role
+ * whose line has never been touched must land EXACTLY on that role's number,
+ * never wherever happens to be free. `dispatchToBackgroundLine`
+ * (voice-call.ts) is the one production caller: "asking the CLI agent for
+ * something IS bringing it on" (design doc) means the line materializes on
+ * first use instead of reporting `unknown_line` for a line that simply
+ * hasn't been dispatched to yet.
+ *
+ * Returns `null` when `line` is outside the switchboard's
+ * 1..MAX_AGENT_LINES range, or when it is already occupied — the caller's
+ * own `getLine(line) === undefined` check is expected to make the second
+ * case unreachable in practice (this function is only ever called after
+ * that check fails), but the guard keeps the contract sound on its own
+ * terms rather than trusting every future caller to get the check right
+ * (§28).
+ */
+export declare const openAgentLineAt: (line: number, label: string) => AgentLine | null;
 /**
  * RELEASE a line — the mirror of `persistSlotBinding`'s adoption: clears the
  * in-memory entry AND its durable slot together, so the freed number is
@@ -209,14 +249,21 @@ export declare const bindLineRun: (line: number, runId: string | null) => void;
  * persisted slot together, so the ONE thing a page reload cannot observe by
  * itself — "is this line's run still going?" — survives the reload instead
  * of silently reverting to a lying "idle". `line-dispatch.ts`'s
- * `attachLineReader` is the ONE seam that calls this, shared by a live
- * dispatch and the boot re-attach (`reattachPendingLineRuns`) alike — same
- * discipline as `persistSlotBinding`'s ADOPTION seam.
+ * `attachLineReader` is the seam that SETS it, shared by a live dispatch and
+ * the boot re-attach (`reattachPendingLineRuns`) alike — same discipline as
+ * `persistSlotBinding`'s ADOPTION seam.
+ *
+ * There is a SECOND clearer (BEL-90): `run-line-progress.ts` calls this with
+ * `null` on every terminal, including for the session currently on screen.
+ * Without it, a background line whose run finished while the user was LOOKING
+ * at that line never reached `attachLineReader`'s terminal callbacks, so the
+ * slot kept a stale runId and every later reload rehydrated the chip as a
+ * permanently stuck "working" (§41).
  *
- * Line 1 never goes through this (line-dispatch.ts never dispatches to line
- * 1 — see its module doc): its `runId` stays the always-`null` value
- * `bindLineRun` already tolerates, and its own run is resolved at stop-time
- * from the stream-state store instead (`AgentLine.runId`'s doc).
+ * Line 1 never has this SET (line-dispatch.ts never dispatches to line 1 —
+ * see its module doc); its own run is resolved at stop-time from the
+ * stream-state store instead (`AgentLine.runId`'s doc). Clearing it for line 1
+ * is a harmless no-op, which is what keeps the terminal path above uniform.
  */
 export declare const persistSlotRun: (line: number, runId: string | null) => void;
 export declare const setLineStatus: (line: number, status: AgentLineStatus, lastText?: string) => void;

package/dist/embed/voice-call-pacing.d.ts

@@ -8,9 +8,10 @@
  *
  * Agent-initiated utterances (function acks, result relays, progress nudges,
  * the greeting) are paced from AUDIO PLAYOUT END, not generation end: the next
- * one may only dispatch once both generation (`responseActive`) and playback
- * (`audioPlaying`) are idle, plus a breath (`UTTERANCE_GAP_MS`). User turns go
- * through server VAD directly and never touch this logic.
+ * one may only dispatch once generation (`responseActive`), playback
+ * (`audioPlaying`), and the USER FLOOR (`userFloor` — the user is speaking, or
+ * only just stopped) are all idle, plus a breath (`UTTERANCE_GAP_MS`). User
+ * turns go through server VAD directly and never touch this logic.
  */
 /**
  * Breath between agent-initiated utterances, measured from AUDIO PLAYOUT END
@@ -29,13 +30,45 @@ export declare const UTTERANCE_GAP_MS = 700;
  */
 export declare const AUDIO_IDLE_SAFETY_MS = 30000;
 /**
- * Hold a follow-up `response.create` while a response is still generating OR
- * its audio is still playing out. Both must be idle before the pause timer may
- * run and the create may be sent.
+ * How long the user keeps the floor after `input_audio_buffer.speech_stopped`
+ * before an agent-initiated utterance may be released. Covers the case
+ * semantic VAD is deliberately patient about: a breath drawn mid-sentence,
+ * where the user has not actually finished. At 600ms (plus
+ * {@link UTTERANCE_GAP_MS}'s 700ms breath), an agent-initiated relay could
+ * start barely 1.3s after the user stopped — while semantic VAD is still
+ * deciding whether they are actually done. 1200ms buys the classifier more
+ * room before an agent-initiated utterance is allowed to land. This ONLY
+ * delays agent-*initiated* speech (progress nudges, result relays); the
+ * model's own response to the user's turn is untouched — that path never
+ * goes through this floor.
+ */
+export declare const USER_FLOOR_GRACE_MS = 1200;
+/**
+ * Ceiling on how long the user floor may hold an utterance, measured from the
+ * moment the floor was TAKEN (`speech_started`). This is an ANTI-WEDGE
+ * fallback, not a tuning knob: {@link USER_FLOOR_GRACE_MS}'s grace timer
+ * already releases the floor shortly after every `speech_stopped`, so in
+ * ordinary speech the floor never survives to see this ceiling at all. Its
+ * only job is the case grace can't cover — a `speech_stopped` that never
+ * arrives (a genuinely stuck VAD) — which is why it must stay far above any
+ * real utterance: a tight ceiling here doesn't add safety, it just yanks the
+ * floor out from under a user who is still mid-sentence and dispatches a
+ * held relay over their voice, which is the exact bug this feature exists to
+ * prevent. Set at 45s — well above semantic VAD's own ceiling (8s at `low`
+ * eagerness, 4s at `medium`) — so it is reachable only when something has
+ * actually gone wrong, never in the course of normal speech. Same discipline
+ * as {@link AUDIO_IDLE_SAFETY_MS} — the pacer must never wedge.
+ */
+export declare const USER_FLOOR_MAX_HOLD_MS = 45000;
+/**
+ * Hold a follow-up `response.create` while a response is still generating, its
+ * audio is still playing out, OR the user holds the floor. All three must be
+ * clear before the pause timer may run and the create may be sent.
  */
 export declare const shouldHoldDispatch: (input: {
     readonly responseActive: boolean;
     readonly audioPlaying: boolean;
+    readonly userFloor: boolean;
 }) => boolean;
 /**
  * On `response.done`, decide whether to release a queued follow-up immediately.
@@ -63,10 +96,15 @@ export type UtterancePacer = {
     /** Audio playout ended (`output_audio_buffer.stopped`) — the anchor the next
      * agent-initiated breath is measured from. */
     readonly onAudioStopped: () => void;
-    /** The user took the floor (`input_audio_buffer.speech_started`). Clears the
-     * playout gate and timers; a follow-up already counting down its breath is
-     * DEFERRED behind the user's turn (re-queued as pending), never dropped. */
+    /** The user took the floor (`input_audio_buffer.speech_started`). TAKES the
+     * user floor (arming the max-hold ceiling) and clears the playout gate and
+     * timers; a follow-up already counting down its breath is DEFERRED behind
+     * the user's turn (re-queued as pending), never dropped. */
     readonly onBargeIn: () => void;
+    /** The user stopped talking (`input_audio_buffer.speech_stopped`). Starts
+     * the grace countdown; the floor is not released until it expires (or the
+     * model takes the turn, or the max-hold ceiling trips). */
+    readonly onUserSpeechStopped: () => void;
     /** Call teardown: clear all flags and timers so nothing leaks forward. */
     readonly reset: () => void;
 };