@belonguniverseai/react-sdk 0.3.5 → 0.4.0

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

@@ -0,0 +1,38 @@
+/**
+ * Rail "+": spawn a brand-new agent slot. Reuses the exact seams the voice
+ * background-line dispatch already established rather than hand-rolling a
+ * second "mint a session" flow — `createVoiceSession` (session-create.ts) is
+ * the ONE place that mints a Belong session over plain HTTP, and
+ * `persistSlotBinding` (voice-call-lines.ts) is the ONE seam that keeps the
+ * in-memory registry and the durable slot moving together (see that module's
+ * ADOPTION doc). This is the rail-initiated counterpart to
+ * `line-dispatch.ts`'s find-or-create — but a spawn has no message to send
+ * yet, so it stops once the session exists instead of posting anything.
+ *
+ * No label prompt in v1 (product ask): the new line's label stays "" and its
+ * rail tooltip falls back to "Agent N" — a labeled spawn is a followup.
+ *
+ * `openAgentLine` starts a fresh line at status "working" (its usual meaning
+ * elsewhere: a voice request is about to dispatch to it). A rail spawn has no
+ * work pending, so a successful mint clears the line back to "idle" instead of
+ * leaving a misleading spinner badge on an agent that isn't actually doing
+ * anything yet — and a FAILED mint releases the line outright
+ * (`closeAgentLine`), because a slot with no session behind it is not an agent.
+ */
+export type SpawnAgentLineResult = {
+    readonly ok: true;
+    readonly line: number;
+    readonly sessionId: string;
+}
+/**
+ * `line_released` is the QUIET outcome — the user closed the freshly-spawned
+ * chip (or a workspace switch re-read the slots) while the mint was still in
+ * flight. It is not an error: the user asked for that agent to go away, and
+ * they got exactly that. The caller must not navigate and must not surface a
+ * message. Distinct from `create_failed` precisely so it can be told apart.
+ */
+ | {
+    readonly ok: false;
+    readonly reason: "cap_reached" | "create_failed" | "line_released";
+};
+export declare const spawnAgentLine: (fetchFn?: typeof fetch) => Promise<SpawnAgentLineResult>;

package/dist/embed/voice/audio-utils.d.ts

@@ -36,3 +36,9 @@ export declare function arrayBufferToBase64(buf: ArrayBuffer): string;
  * @returns An ArrayBuffer containing the decoded bytes.
  */
 export declare function base64ToArrayBuffer(b64: string): ArrayBuffer;
+/**
+ * Join captured little-endian PCM16 frames and wrap them in a mono WAV file.
+ * The microphone capture engine emits 16 kHz frames; a WAV container lets the
+ * belong-cloud STT proxy forward one provider-compatible audio file.
+ */
+export declare function pcm16FramesToWav(frames: readonly ArrayBuffer[], sampleRate: number): ArrayBuffer;

package/dist/embed/voice/call-active-marker.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+declare const callActiveMarkerSchema: z.ZodObject<{
+    active: z.ZodLiteral<true>;
+    startedAtMs: z.ZodNumber;
+    /** Recap of the call so far, same shape/cap as `buildCallContextDigest()`.
+     * Empty until the first user/agent timeline row lands. */
+    contextDigest: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    active: true;
+    startedAtMs: number;
+    contextDigest: string;
+}, {
+    active: true;
+    startedAtMs: number;
+    contextDigest: string;
+}>;
+export type CallActiveMarker = z.infer<typeof callActiveMarkerSchema>;
+/** The tab's persisted call marker, or null when absent/malformed — a
+ * corrupted or pre-this-feature record just means "nothing to redial". */
+export declare const readCallActiveMarker: () => CallActiveMarker | null;
+/** Mark the call live — called on the `in_call` transition. Starts with an
+ * empty digest; {@link refreshCallActiveMarkerContext} fills it in as the
+ * call progresses. */
+export declare const writeCallActiveMarker: () => void;
+/** Update the persisted digest of an already-active marker. No-op when no
+ * marker is active — a digest has nothing to attach itself to once the call
+ * has ended. */
+export declare const refreshCallActiveMarkerContext: (contextDigest: string) => void;
+/** Call ended (explicit hangup or terminal error) — no reload should redial. */
+export declare const clearCallActiveMarker: () => void;
+export type ReconnectOfferDecision = "offer" | "skip";
+/**
+ * How long after the interrupted call started we still OFFER to reconnect. A
+ * reload lands in seconds; a tab the browser restored from a much older session
+ * should come back to a plain idle dock, not a stale "Reconnect" affordance
+ * pointing at a conversation the user has long since moved on from.
+ */
+export declare const RECONNECT_OFFER_MAX_AGE_MS = 600000;
+/**
+ * Whether the dock's boot effect should OFFER to reconnect an interrupted call.
+ *
+ * This deliberately decides an offer, never a dial. Auto-dialing on load opens
+ * the MICROPHONE with no user gesture: the origin already holds mic permission
+ * (a call was live moments ago), so the browser does not re-prompt and the mic
+ * would come back silently on the next page load — on hosts that receive the
+ * SDK through an unpinnable bundle, with no opt-in of their own. Requiring one
+ * click to redial is both the honest consent story and what browsers' autoplay/
+ * gesture rules expect; the marker is kept either way so the redial can still
+ * carry the interrupted call's `contextDigest`.
+ *
+ * Pure so the branching is unit-testable without React or WebRTC: a marker
+ * means a call was live when the page went away; `tokenReady` mirrors the same
+ * auth-readiness gate the login screen polls; `alreadyOffered` is the one-shot
+ * guard (the offer is raised at most once per page load); and `startedAtMs` is
+ * consumed against `nowMs` so a stale marker cannot offer forever.
+ */
+export declare const decideReconnectOffer: (input: {
+    readonly marker: CallActiveMarker | null;
+    readonly tokenReady: boolean;
+    readonly alreadyOffered: boolean;
+    readonly nowMs: number;
+}) => ReconnectOfferDecision;
+export declare const peekReconnectOffered: () => boolean;
+export declare const markReconnectOffered: () => void;
+/** Test-only: forget the one-shot guard between test cases. */
+export declare const __resetReconnectOfferedForTest: () => void;
+export {};

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

@@ -1,8 +1,17 @@
 /**
- * Background-line dispatch: create the line's session on first use (plain
- * HTTP — the same endpoints the chat transport uses), post the message, and
- * attach the line-run reader so results/failures/phases/approvals flow back
- * into the call. Line 1 (the foreground chat) never comes through here.
+ * Background-line dispatch: find-or-create the line's session (plain HTTP —
+ * the same endpoints the chat transport uses), post the message, and attach
+ * the line-run reader so results/failures/phases/approvals flow back into the
+ * call. Line 1 (the foreground chat) never comes through here.
+ *
+ * Persistent slots: a line's session, once created, is adopted via
+ * `persistSlotBinding` (`voice-call-lines.ts`), which persists it to
+ * `line-slots.ts` so the NEXT call's `resetAgentLines()` rehydrates onto the
+ * SAME session — "Agent 2" keeps its identity across calls instead of
+ * starting a fresh conversation every time. A persisted session can go stale
+ * between calls (deleted from another surface, tenant reset, …): the message
+ * POST below treats 404/410 as "the bound session is gone", recreates one,
+ * updates the binding, and retries once.
  *
  * 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

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

@@ -16,6 +16,15 @@
  *   - `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 —
@@ -31,6 +40,10 @@ export type WatchLineRunInput = {
     readonly runId: string;
     readonly onPhase: (toolName: string) => void;
     readonly onApprovalNeeded: () => void;
+    readonly onNavigate: (data: {
+        readonly routeName: string;
+        readonly params: Readonly<Record<string, string>>;
+    }) => void;
     readonly onArtifact: (artifact: {
         artifactId: string;
         title: string;

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

@@ -0,0 +1,61 @@
+/**
+ * Persisted agent-line slot bindings — the durable identity behind
+ * "Agent 1" / "Agent 2" / "Agent 3" across DIFFERENT calls (and, for line 1,
+ * across page reloads with no call at all). The in-memory switchboard
+ * (`voice-call-lines.ts`) is wiped and rebuilt on every call start/end
+ * (`resetAgentLines`); this module is what lets that rebuild REHYDRATE every
+ * line onto the same session it pointed to last time, instead of starting
+ * from a blank switchboard.
+ *
+ * Line 1 is no longer special-cased: the ADOPTION rule (see
+ * `persistSlotBinding` in `voice-call-lines.ts`) is that whichever session
+ * last became a slot's ACTIVE session — including the foreground chat — gets
+ * written here, so "Agent 1" means the same session across reloads and
+ * calls, same as 2/3 always have.
+ *
+ * Workspace isolation (§28): keyed the same way `stream-state-store.ts`
+ * namespaces the session pointer (`belong:voice-line-slots:ws:<id>`, the
+ * legacy un-suffixed key when no workspace is in effect) — a host workspace
+ * switch must not hand a slot from workspace A to a session that actually
+ * belongs to workspace B.
+ *
+ * localStorage is a perimeter: the persisted bag is zod-validated on read and
+ * any junk (corrupted JSON, wrong shape, storage disabled) degrades to "no
+ * slots" — the switchboard just starts fresh, same as a first-ever call. The
+ * schema is back-compatible with the pre-line-1 bag: a persisted object with
+ * only `line2`/`line3` still parses fine, `line1` just defaults to `null`.
+ */
+/** Every line number that gets a persisted slot — all three agent lines. */
+declare const SLOT_LINES: readonly [1, 2, 3];
+type SlotLine = (typeof SLOT_LINES)[number];
+export type LineSlot = {
+    readonly sessionId: string;
+    readonly label: string;
+};
+/** The persisted binding for line 1/2/3, or `null` when never set (or `line`
+ * isn't a valid agent line at all). */
+export declare const readLineSlot: (line: number) => LineSlot | null;
+/** Persist a line's current `{ sessionId, label }` so the NEXT rehydration
+ * (`resetAgentLines()`, or a plain reload for line 1) rebinds onto the same
+ * session. No-op for a line number that isn't 1/2/3, and no-op when the slot
+ * already holds this exact `{ sessionId, label }` — callers (e.g. chat.tsx's
+ * per-render bind effect) call this on every render, so an unchanged binding
+ * must not touch storage. */
+export declare const writeLineSlot: (line: number, slot: LineSlot) => void;
+/** Drop a line's persisted binding — the durable half of `closeAgentLine`
+ * (voice-call-lines.ts). Called when a slot is RELEASED rather than rebound: a
+ * spawn whose session mint failed, or a session the user deleted. Without this
+ * the slot would rehydrate on the next boot onto a session that no longer
+ * exists (a dangling agent the rail keeps offering). No-op for a line number
+ * that isn't 1/2/3, and no-op when the slot is already empty. */
+export declare const clearLineSlot: (line: number) => void;
+/** Every persisted line slot, in ascending line order (1, then 2, then 3),
+ * skipping lines that were never bound. What `resetAgentLines()` reads to
+ * rebuild the switchboard. */
+export declare const readAllLineSlots: () => readonly {
+    readonly line: SlotLine;
+    readonly slot: LineSlot;
+}[];
+/** Test-only: drop every persisted slot for the current workspace scope. */
+export declare const __clearLineSlotsForTest: () => void;
+export {};

package/dist/embed/voice/reconnect-offer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * "A call was interrupted — tap to reconnect" — the one-bit store that turns a
+ * surviving call marker (`call-active-marker.ts`) into a USER-DRIVEN redial.
+ *
+ * The dock's boot effect raises the offer; the rail's CallButton reads it and,
+ * while it stands, dials with `{ isReconnect: true }` (carrying the interrupted
+ * call's context digest) and labels itself "Reconnect" instead of "Start voice
+ * call". That is the whole mechanism: ONE user click, on a control that is
+ * already always visible in the rail — no new surface, and crucially no
+ * microphone access without a gesture.
+ *
+ * Why a separate store rather than a field on `CallState`: the call state is
+ * rebuilt from `IDLE` on every dial and every terminal error, which would wipe
+ * a pending offer mid-flight. This flag's lifetime is the page load, not the
+ * call's, so it lives on its own — and stays trivially testable without WebRTC.
+ *
+ * External-store singleton, same idiom as `voice-bus.ts` / `voice-call-lines.ts`.
+ */
+export declare const peekReconnectOffer: () => boolean;
+export declare const subscribeReconnectOffer: (listener: () => void) => (() => void);
+/** Raise the offer (dock boot, when `decideReconnectOffer` says so). */
+export declare const offerReconnect: () => void;
+/**
+ * Take the offer down. Called when the user acts on it (the reconnect click),
+ * and on any other dial or hang-up — once a call is being started or has been
+ * deliberately ended, "reconnect the previous one" is no longer the thing to
+ * show. No-op when no offer stands.
+ */
+export declare const consumeReconnectOffer: () => void;

package/dist/embed/voice/session-create.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The ONE place that mints a Belong session over plain HTTP for the voice
+ * call surface — shared by `line-dispatch.ts` (background lines 2/3, which
+ * additionally persist the slot) and `voice-call.ts` (the foreground line 1
+ * eager-bind at call start). Both need "create a session, same endpoint the
+ * chat transport uses" with no message attached yet; this is that seam, so
+ * neither call site hand-rolls its own `POST /v1/sessions` fetch.
+ *
+ * Workspace isolation (§28) mirrors `line-dispatch.ts`'s existing behavior:
+ * the create body carries the effective `workspaceExternalId` (absent when
+ * the host runs unscoped) so a background OR foreground line opened while the
+ * host is inside a workspace lands in THAT workspace.
+ */
+export type CreateSessionOutcome = {
+    readonly status: "created";
+    readonly sessionId: string;
+} | {
+    readonly status: "failed";
+    readonly httpStatus: number;
+};
+/**
+ * `title` seeds the session's row in the Chats switcher (e.g. an agent
+ * line's label) — pass `null` (or `""`) to omit it, matching
+ * `createSessionSchema`'s optional title.
+ */
+export declare const createVoiceSession: (title: string | null, fetchFn?: typeof fetch) => Promise<CreateSessionOutcome>;

package/dist/embed/voice/voice-http.d.ts

@@ -6,3 +6,15 @@
 export declare function voiceJsonHeaders(): Promise<Record<string, string>>;
 /** Absolute URL for a voice endpoint path (e.g. "/v1/voice/tts"). */
 export declare function voiceUrl(path: string): string;
+export type VoiceTranscriptionResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: "unconfigured" | "error";
+};
+/**
+ * Send one captured WAV clip to belong-cloud's authenticated STT proxy.
+ * Gemini/OpenAI keys stay server-side; the SDK receives only transcript text.
+ */
+export declare function transcribeVoiceAudio(audio: ArrayBuffer, contentType: string): Promise<VoiceTranscriptionResult>;

package/dist/embed/voice-bus.d.ts

@@ -1,6 +1,7 @@
 import { fetchVoiceTokens } from './voice/voice-token.ts';
 import { createDeepgramStt } from './voice/deepgram-stt.ts';
 import { createMicCapture } from './voice/mic-capture.ts';
+import { transcribeVoiceAudio } from './voice/voice-http.ts';
 export type VoiceStatus = "idle" | "requesting" | "listening" | "transcribing" | "error";
 /**
  * Capture state. `status` is the single source of truth; `interim` is the live
@@ -32,6 +33,7 @@ type VoiceEngineFactories = {
     fetchTokens: typeof fetchVoiceTokens;
     createStt: typeof createDeepgramStt;
     createMic: typeof createMicCapture;
+    transcribeAudio: typeof transcribeVoiceAudio;
 };
 /**
  * Test-only: override one or more engine factories. Pass `null` to restore the

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

@@ -1,31 +1,228 @@
+import { WorkPhase } from './voice-narration.ts';
+export declare const MAX_AGENT_LINES = 3;
 /**
- * Agent lines registry — the Operator's switchboard. Line 1 is the
- * FOREGROUND chat (existing single-line behavior, unchanged); lines 2+ are
- * background sessions dispatched over plain HTTP and monitored by the
- * line-run reader. External-store singleton, same idiom as voice-bus.ts.
+ * "idle" is the not-busy resting state — no work in flight, and nothing
+ * completed/failed yet worth reporting (a fresh call, or a line rebound onto
+ * a persisted session with no activity this call). "ready" is the DISTINCT
+ * terminal state after a run actually finished successfully — it carries a
+ * result (`lastText`) worth showing, unlike "idle" which never conflates the
+ * two anymore (pre-CallScreen-board, both were folded into "ready").
  */
-export declare const MAX_AGENT_LINES = 3;
-export type AgentLineStatus = "working" | "ready" | "failed" | "needs_approval";
+export type AgentLineStatus = "idle" | "working" | "ready" | "failed" | "needs_approval";
 export type AgentLine = {
     readonly line: number;
+    /**
+     * Monotonic stamp identifying THIS occupancy of the slot — bumped every time
+     * a line entry is CREATED (`openAgentLine`, a line-1 reset, a rehydrate), and
+     * carried unchanged through every later write (they all spread `...l`).
+     *
+     * The line NUMBER is not an identity: `closeAgentLine(2)` frees it and the
+     * very next `openAgentLine` hands the same number to a different reservation.
+     * Anything holding a line across an await (`spawnAgentLine`'s session mint,
+     * line-dispatch's find-or-create) must therefore re-check the epoch, not just
+     * that "line 2 exists" — otherwise a spawn whose chip the user closed
+     * mid-mint binds its session onto the NEXT spawn's line. Compare via
+     * `isLineReservation` below.
+     */
+    readonly epoch: number;
     readonly sessionId: string | null;
     readonly label: string;
     readonly status: AgentLineStatus;
     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. */
+    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`
+     * is `"working"`. Cleared back to `null` once the line reaches a terminal
+     * status (ready/failed) or starts a fresh dispatch — CallScreen's agent
+     * board reads this to show a step under the status dot instead of just a
+     * bare "working" chip. */
+    readonly currentStepLabel: string | null;
+    /** The step's phase classification — what KIND of work the line is doing
+     * right now (`classifyToolPhase`), so a working card wears the same phase
+     * icon the orb's work badge does (code / files / actions; spinner while
+     * unknown). Written and cleared together with `currentStepLabel` by
+     * `setLineStep`. */
+    readonly currentPhase: WorkPhase | null;
+    /** True when this line reached a terminal status (ready/failed) while its
+     * session was NOT the one on screen — a finished result the user hasn't
+     * looked at yet (product vision: the rail's green "unseen" dot). Written by
+     * `deliverLineReply`/`deliverLineFailure` (voice-call.ts) for background
+     * lines; line 1's own terminal writes never set it (the foreground chat IS
+     * what's on screen, so its own results are seen by definition). Cleared by
+     * `markLineSeen` once the user actually views that line's session. */
+    readonly unseenResult: boolean;
 };
 export declare const peekAgentLines: () => readonly AgentLine[];
 export declare const subscribeAgentLines: (listener: () => void) => (() => void);
+/** Hard reset: rebuilds every line from its persisted slot, ephemeral fields
+ * clean. Used by `initAgentLines()`, a host workspace switch, and the
+ * `__forceAgentLines` test/E2E harness —
+ * NOT on a call boundary any more (see the module doc's "CALL BOUNDARY"
+ * section); a live call uses `resetForCallStart()` below instead. */
 export declare const resetAgentLines: () => void;
+/**
+ * The registry's FIRST read of the durable slots, and the one that binds it to
+ * the host's workspace. The dock calls this once on mount — i.e. after
+ * `configureWorkspaceScope` / `setWorkspace` have run — so the boot rehydrate
+ * uses the workspace-suffixed storage key that every later write also uses
+ * (a module-eval read would have used the legacy unsuffixed one).
+ *
+ * It also subscribes to the workspace-scope store: a host workspace switch
+ * hard-resets the registry and re-reads the slots under the NEW key, so the
+ * rail can never keep offering the previous workspace's sessions. Idempotent —
+ * a second call just re-reads; only one subscription is ever held.
+ */
+export declare const initAgentLines: () => void;
+/** Test-only: drop the workspace subscription so each case starts unsubscribed. */
+export declare const __resetAgentLinesInitForTest: () => void;
+/**
+ * Call-boundary reset — narrower than `resetAgentLines()`. A call ENDING no
+ * longer touches the registry at all (a finished result and its
+ * `unseenResult` flag must survive the hang-up). By the time the NEXT call
+ * starts, the only genuinely stale ephemera left behind is a line stuck at
+ * "working": its reader was torn down mid-flight when the previous call ended
+ * (`abortAllLineReaders` in line-dispatch.ts) without the run ever reaching a
+ * terminal status. Everything else — bindings, terminal statuses,
+ * `unseenResult` — is left exactly as it is. No-op (no emit) when nothing was
+ * actually "working".
+ */
+export declare const resetForCallStart: () => void;
 export declare const getLine: (line: number) => AgentLine | undefined;
 /**
- * The "foreground-routed alias": a background line (≥ 2) bound to the SAME
- * session line 1 currently shows (the user opened it in the chat via
- * `show_agent_line`). New work for that line is routed through the foreground
- * pipeline so the visible chat renders the run — but the background line's
- * strip status must still be kept truthful, and this finds the line to update.
- * Returns `undefined` when line 1 is unbound or no background line aliases it.
+ * Is the slot `line` STILL held by the reservation stamped `epoch`? The check
+ * every holder of a line across an await owes the registry before it adopts a
+ * session into that line (see `AgentLine.epoch`). False means the reservation
+ * is gone — released outright, or already replaced by a different one that
+ * happens to wear the same number.
+ */
+export declare const isLineReservation: (line: number, epoch: number) => boolean;
+/** The line (other than 1) currently bound to `sessionId`, or `undefined` when
+ * no background line holds it — the shared scan behind `isBoundToAnotherLine`
+ * (the boolean chat.tsx's aliasing guard needs) and `markLineSeen`'s callers
+ * (which need the actual line number to mark seen). */
+export declare const lineBoundToSession: (sessionId: string) => AgentLine | undefined;
+/** 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
+ * `show_agent_line` (rebinding would overwrite line 1's own identity). */
+export declare const isBoundToAnotherLine: (sessionId: string) => boolean;
+/**
+ * The line number the FOREGROUND chat's registry writes belong to. The visible
+ * chat is NOT always line 1: the rail's spawn flow and `show_agent_line` both
+ * put a BACKGROUND line's session on screen, and work done there must light
+ * that line's badge — not line 1's, which would leave the agent the user is
+ * actually watching sitting idle. Falls back to line 1 when the on-screen
+ * session is line 1's own (or unknown), which is the common case.
+ *
+ * This SUPERSEDED the old `findAliasedLine()` helper, which served the INVERSE
+ * premise: line 1 having ADOPTED a background line's session, so a line-1 write
+ * had to be mirrored onto the aliased background line. The aliasing guards
+ * (`isBoundToAnotherLine`, in chat.tsx's line-1 bind effect and voice-call.ts's
+ * eager foreground mint) now stop line 1 from ever adopting another line's
+ * session, so that premise can no longer hold in production — the helper was
+ * permanently `undefined`, i.e. dead code that read as live, and was deleted.
+ * Every foreground write resolves its ONE target through this function instead.
  */
-export declare const findAliasedLine: () => AgentLine | undefined;
+export declare const foregroundLineNumber: (sessionId: string | null) => number;
 export declare const openAgentLine: (label: string) => AgentLine | null;
-export declare const bindLineSession: (line: number, sessionId: string) => void;
+/**
+ * RELEASE a line — the mirror of `persistSlotBinding`'s adoption: clears the
+ * in-memory entry AND its durable slot together, so the freed number is
+ * immediately re-mintable by `openAgentLine` and does not rehydrate on the next
+ * boot. Called when a spawn's session mint fails (otherwise the slot is burned
+ * until reload) and when the user deletes a session a line was bound to
+ * (otherwise the rail keeps offering a chip that opens a session that is gone).
+ *
+ * Line 1 is the foreground chat and is never REMOVED — releasing it resets it
+ * to the familiar fresh/unbound line 1 instead. No-op on an unknown line.
+ */
+export declare const closeAgentLine: (line: number) => void;
+/**
+ * TEST/HARNESS-ONLY memory-only bind — the `__` prefix is load-bearing. This
+ * writes the in-memory registry WITHOUT the durable slot, which is precisely
+ * the divergence `persistSlotBinding` exists to eliminate: a line bound only in
+ * memory looks right until the next rehydrate, then silently reverts (or, after
+ * a workspace switch, rehydrates onto the OTHER workspace's session). Production
+ * adoption has exactly one seam and it is `persistSlotBinding`.
+ *
+ * It stays exported solely so unit tests, the rail stories, and the
+ * `__forceAgentLines` E2E hook can construct a registry state without writing
+ * durable slots that would then leak across cases (and, for `__forceAgentLines`,
+ * survive an E2E reload as phantom agents). Renamed from the old public
+ * `bindLineSession` so no production writer can reach for it by accident.
+ */
+export declare const __bindLineSessionForTest: (line: number, sessionId: string) => void;
+/**
+ * The ADOPTION seam (the one rule for what "Agent N" means): call this
+ * whenever `sessionId` becomes the ACTIVE session for `line` — line 1's
+ * foreground bind effect, the eager foreground mint at call start, and a
+ * background line's find-or-create dispatch. Updates the in-memory registry
+ * and the durable slot together, so a slot's identity never drifts between
+ * the two. No-ops on an unchanged binding, so calling this on every render
+ * (chat.tsx's bind effect has no dep array) is cheap.
+ *
+ * The two halves must move TOGETHER — both of these were real divergences:
+ *
+ *  - An UNKNOWN line writes nothing. Every adoption site has an async gap
+ *    between reserving the line and minting its session (`spawnAgentLine`,
+ *    line-dispatch's find-or-create), and the line can be released inside that
+ *    gap — a failed sibling spawn, a deleted session, a workspace switch that
+ *    re-reads the slots. Writing the slot anyway left a durable binding for a
+ *    line the registry does not hold, which rehydrates on the next boot as a
+ *    phantom agent (and, after a workspace switch, one pointing at the OTHER
+ *    workspace's session).
+ *  - The `label` is written to memory too, not only to storage. Adopting under
+ *    a new label with an unchanged `sessionId` used to update the durable slot
+ *    while the in-memory line kept the old label, so the rail's chip and the
+ *    label that survives a reload disagreed until the next rehydration.
+ */
+export declare const persistSlotBinding: (line: number, sessionId: string, label: string) => void;
+/** `stop_agent`'s target: bound by the line-run reader once a background
+ * dispatch's POST returns a runId, and cleared to `null` when that run
+ * finishes/fails/errors — a stopped or finished run must not look stoppable
+ * again. No-op on an unknown line or an unchanged value (mirrors
+ * `setLineStatus`'s re-write-on-every-render tolerance). */
+export declare const bindLineRun: (line: number, runId: string | null) => void;
 export declare const setLineStatus: (line: number, status: AgentLineStatus, lastText?: string) => void;
+/** CallScreen's agent board reads this as the live "what is it doing right
+ * now" line under a working line's status dot — written on every phase
+ * notification (`notifyLinePhase`) and cleared (`null`) once the line's run
+ * reaches a terminal state. `phase` rides along so the working card can wear
+ * the matching phase icon (omitted/null = kind unknown → spinner); a `null`
+ * label always clears both. No-op on an unknown line or unchanged values
+ * (mirrors `setLineStatus`'s tolerance). */
+export declare const setLineStep: (line: number, label: string | null, phase?: WorkPhase | null) => void;
+/** Write a line's `unseenResult` flag directly — `deliverLineReply`/
+ * `deliverLineFailure` (voice-call.ts) call this alongside `setLineStatus` to
+ * mark a background line's finish/failure unseen when its session isn't the
+ * one on screen. No-op on an unknown line or an unchanged value (mirrors
+ * `setLineStatus`'s tolerance). Most callers want `markLineSeen` below rather
+ * than calling this with `false` directly. */
+export declare const setLineUnseenResult: (line: number, unseenResult: boolean) => void;
+/** The user is now looking at this line's session — clear its unseen-result
+ * flag. Called from BelongDock's `onSelectSession` (any surface that opens a
+ * session — the sessions list, `show_agent_line`, a notification click) once
+ * it resolves which line, if any, owns the opened session. */
+export declare const markLineSeen: (line: number) => void;
+/**
+ * The user opened `sessionId` — clear the unseen-result flag on EVERY line
+ * bound to it. More than one line can share a session: line 1 aliases whatever
+ * the chat is showing, so a background line the user opened is held by both.
+ * Marking only the FIRST match (line 1, which sorts first) left the background
+ * agent's green dot lit forever with no way to clear it. No-op when no line
+ * owns the session.
+ */
+export declare const markSessionSeen: (sessionId: string) => void;
+/**
+ * The session behind `sessionId` is gone (the user deleted it) — RELEASE every
+ * line bound to it, in memory and durably. Without this the registry and its
+ * reload-surviving slot keep pointing at a session that no longer exists, so
+ * the rail goes on offering a chip that opens nothing.
+ */
+export declare const releaseLinesForSession: (sessionId: string) => void;

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

@@ -1,4 +1,5 @@
 import { AgentLineStatus } from './voice-call-lines.ts';
+import { WorkPhase } from './voice-narration.ts';
 export type CallStatus = "idle" | "connecting" | "in_call" | "error";
 /**
  * One row of the call's execution timeline (the CallScreen activity card):
@@ -112,6 +113,7 @@ declare let lineDispatcher: ((req: {
 }) => void) | null;
 export declare const registerCallLineDispatcher: (dispatcher: NonNullable<typeof lineDispatcher>) => (() => void);
 export declare const registerCallLineViewSwitcher: (switcher: (sessionId: string) => void) => (() => void);
+export declare const registerCallClearNotifier: (notifier: (sessionId: string) => void) => (() => void);
 /**
  * ChatRoute calls this when a tool-approval card appears while a call is
  * live: the ask lands on the timeline and the voice model asks the user to
@@ -133,7 +135,24 @@ export declare const setCallWorkPhase: (phase: CallState["workPhase"]) => void;
  * (e.g. ChatRoute hasn't mounted).
  */
 export declare const showLineOnScreen: (line: number) => void;
-export declare const startCall: () => Promise<void>;
+/**
+ * `isReconnect`: set by the dock's boot-time auto-redial (BEL — call survives
+ * page reload) when a per-tab {@link readCallActiveMarker} marker says a call
+ * was live when the page went away. Everything else about starting the call
+ * is identical to a manual dial — a fresh page load already rehydrates every
+ * line straight from its persisted slot session at MODULE BOOT (the registry's
+ * own initializer, `voice-call-lines.ts`), and `ensureForegroundLineSession`
+ * reuses line 1's persisted session pointer (stream-state-store.ts), so no
+ * line state is lost either way; `resetForCallStart()` below only clears a
+ * line that was genuinely left stuck "working" by an earlier call's teardown.
+ * The ONE thing a fresh page load can't recover on its own is the call's
+ * spoken timeline (in-memory, wiped by definition) — `resumeDigest`, captured
+ * from the marker BEFORE this call's own lifecycle overwrites it, carries that
+ * recap into the reconnected realtime session (see `onOpen` below).
+ */
+export declare const startCall: (options?: {
+    readonly isReconnect?: boolean;
+}) => Promise<void>;
 export declare const endCall: () => void;
 export declare const toggleCallMuted: () => void;
 /** Dismiss a sticky error state (the overlay's ✕). */
@@ -173,10 +192,13 @@ export declare const deliverLineArtifact: (line: number, artifact: {
 export declare const deliverLineFailure: (line: number, message: string) => void;
 /** A background line is blocked on a tool approval — steer the user to it. */
 export declare const notifyLineApprovalNeeded: (line: number, timelineText: string) => void;
-/** A background line advanced a phase — land a tagged row + a spoken nudge.
- * Guarded like its delivery siblings: a stale phase from an ended call (there
- * is no registry write here) must not touch a new call's timeline. */
-export declare const notifyLinePhase: (line: number, phaseLabel: string) => void;
+/** A background line advanced a phase — record it as the line's live step
+ * (CallScreen's agent board), land a tagged timeline row, and nudge a spoken
+ * update. The registry write is unconditional (line-dispatch's own `isStale`
+ * guard already keeps a stale-call phase from ever reaching here); the
+ * timeline/spoken half stays guarded like its delivery siblings so a phase
+ * that DOES arrive with no live call just updates the board silently. */
+export declare const notifyLinePhase: (line: number, phaseLabel: string, phase?: WorkPhase | null) => void;
 /** True while a call holds the audio path — ChatRoute gates TTS autoplay on it. */
 export declare const isCallActive: () => boolean;
 /**
@@ -196,7 +218,7 @@ export declare const __forceCallAudioLevel: (level: number) => void;
  * CallScreen lines strip in E2E and sandboxed browsers. Resets the registry,
  * then replays the same store calls a live Operator run makes: `openAgentLine`
  * to create each background line (sequential, mirroring real dispatch),
- * `bindLineSession` + `setLineStatus` to fill it in. Line 1 is the existing
+ * `__bindLineSessionForTest` + `setLineStatus` to fill it in. Line 1 is the existing
  * foreground line and is updated in place rather than opened. Entries are
  * replayed in ascending `line` order regardless of input order, so lines 2/3
  * always land on their expected slots.
@@ -206,5 +228,11 @@ export declare const __forceAgentLines: (forced: readonly {
     label: string;
     status: AgentLineStatus;
     sessionId?: string;
+    /** Optional live step label (CallScreen's agent board) — mirrors what
+     * `notifyLinePhase` writes on a real background dispatch. */
+    currentStepLabel?: string;
+    /** Optional phase classification for the step — drives the working
+     * card's phase icon (omitted = spinner). */
+    currentPhase?: WorkPhase;
 }[]) => void;
 export {};