npm - @belonguniverseai/react-sdk - Versions diffs - 0.3.6 → 0.4.1 - Mend

@belonguniverseai/react-sdk 0.3.6 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (97) hide show

package/dist/embed/host-push-controller.d.ts ADDED Viewed

@@ -0,0 +1,67 @@
+/**
+ * BEL-112 / push layout: keeps HOST `position: fixed` surfaces out from under
+ * the dock.
+ *
+ * `<body>` padding reserves the dock's width for everything in the normal
+ * flow. Fixed host UI escapes that flow — a right-anchored Simetrik drawer,
+ * a portal-mounted popout, a drawer scrim, a centered modal — so this
+ * controller finds those surfaces and writes ONE inline margin per element to
+ * shift or shrink them into the free viewport. The geometry lives in
+ * embed/host-surface.ts; this file is the DOM adapter around it.
+ *
+ * Two escape hatches for the failure modes a host can put us in:
+ *
+ *   fight detection  a host that repositions its own surface against our
+ *                    margin never converges (customer report: rename dialog
+ *                    shaking left↔right). Writes are budgeted per element
+ *                    within a stable footprint+viewport epoch; past the cap
+ *                    the element is left alone forever.
+ *   yield            a surface too wide to fit beside the dock can't be
+ *                    corrected at all, so the DOCK gives way instead — the
+ *                    owner collapses it to the rail via `onYieldNeeded` and
+ *                    restores on `onYieldCleared`.
+ *
+ * No React: the owner injects the two callbacks and pushes layout changes in.
+ */
+/** Per-element inline-margin writes allowed inside one stable epoch. */
+export declare const MAX_HOST_SURFACE_SHIFT_WRITES = 4;
+export type HostPushLayout = {
+    readonly side: "left" | "right";
+    /** Total width the dock reserves: chat dock + plan panel + preview panel. */
+    readonly reservePx: number;
+};
+export type HostPushControllerDeps = {
+    /**
+     * A surface can't fit beside the dock — the owner should collapse. Called
+     * once per yield episode, never while a yield is already pending.
+     */
+    readonly onYieldNeeded: () => void;
+    /** Every surface that forced the yield is gone — the owner may restore. */
+    readonly onYieldCleared: () => void;
+};
+export type HostPushController = {
+    /** Push new layout inputs and re-evaluate (dock resized, side flipped). */
+    readonly setLayout: (layout: HostPushLayout) => void;
+    /** Request an evaluation on the next frame (coalesced). */
+    readonly schedule: () => void;
+    /** Disconnect observers and restore every margin this controller wrote. */
+    readonly stop: () => void;
+};
+/**
+ * Candidate host surfaces, from three complementary sources:
+ *
+ *   1. dialog-ish elements anywhere (Radix and friends set one of these);
+ *   2. DIRECT CHILDREN of <body> that compute to `position: fixed` — where
+ *      React and Radix portals land, hit-testable or not;
+ *   3. anything currently under the dock, found by hit-testing the reserve
+ *      band — this is what catches a fixed drawer rendered INLINE deep in the
+ *      host's own tree, which is how plenty of hosts (Simetrik included) build
+ *      them.
+ *
+ * Probing every element's computed style would be far too expensive for a
+ * MutationObserver callback; between them these three cost a bounded number of
+ * style reads per evaluation. `position: sticky` is deliberately excluded —
+ * sticky lives in the normal flow, so the body padding already moves it.
+ */
+export declare const collectHostSurfaces: (side: "left" | "right", reservePx: number) => readonly HTMLElement[];
+export declare const startHostPushController: (initialLayout: HostPushLayout, deps: HostPushControllerDeps) => HostPushController;

package/dist/embed/host-surface.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+/**
+ * Pure classification + correction geometry for HOST viewport-anchored
+ * surfaces (drawers, popouts, side panels, modal backdrops, centered modals).
+ *
+ * The dock reserves its width with `<body>` padding, which reflows everything
+ * in the normal flow. `position: fixed` host UI escapes that flow and would
+ * render underneath the dock, so the dock corrects it with one inline margin.
+ * Which margin, and how far, is decided here — no DOM, no React.
+ *
+ * Three correctable shapes:
+ *
+ *   full_bleed  an overlay spanning the viewport (a drawer's backdrop, an
+ *               `inset: 0` scrim). Shifting it would just move it off screen;
+ *               a margin on the dock side SHRINKS it, which is the fix.
+ *   anchored    a drawer/panel pinned to the dock's own viewport edge.
+ *   floating    a centered modal that merely overlaps the reserve band.
+ *
+ * `anchored` and `floating` share the legacy `resolveHostModalShiftPx`
+ * magnitude; they are distinguished so the classification is explicit and
+ * testable, and so a future rule can treat them differently.
+ */
+export type HostSurfaceRect = {
+    readonly left: number;
+    readonly right: number;
+};
+export type HostSurfaceKind = "clear" | "full_bleed" | "anchored" | "floating";
+/**
+ * How far a surface edge may sit from the viewport edge and still count as
+ * pinned to it. Generous on purpose: hosts inset drawers and scrims by a few
+ * pixels (`right: 8px`, a 1px border, scrollbar-gutter compensation) and those
+ * are still edge-anchored — misreading one as a free-floating modal would send
+ * it a margin the browser cannot act on.
+ */
+export declare const EDGE_ANCHOR_TOLERANCE_PX = 24;
+/**
+ * The inline property a correction writes, the signed DELTA to add to whatever
+ * margin the host already set there, and the shape it was derived from — the
+ * caller needs the kind to back the correction out of a later measurement (a
+ * shift moves the box; a shrink moves one edge).
+ */
+export type HostSurfaceCorrection = {
+    readonly property: "margin-left" | "margin-right";
+    readonly px: number;
+    readonly kind: HostSurfaceKind;
+};
+export declare const classifyHostSurface: (rect: HostSurfaceRect, viewportWidthPx: number, side: "left" | "right", reservePx: number) => HostSurfaceKind;
+/**
+ * The inline correction that moves `rect` (its UNSHIFTED position) out from
+ * under a dock reserving `reservePx` on `side`. `px: 0` means leave it alone.
+ */
+export declare const resolveHostSurfaceCorrection: (rect: HostSurfaceRect, viewportWidthPx: number, side: "left" | "right", reservePx: number) => HostSurfaceCorrection;
+/**
+ * Can this surface be corrected and still sit fully on screen? A full-bleed
+ * overlay always can (shrinking it never pushes it off). Shifted surfaces are
+ * judged by the legacy fit test. False means the dock must yield instead.
+ */
+export declare const canHostSurfaceFitBesideDock: (rect: HostSurfaceRect, viewportWidthPx: number, side: "left" | "right", reservePx: number) => boolean;

package/dist/embed/presets.d.ts CHANGED Viewed

@@ -17,6 +17,16 @@ export declare const DEFAULT_PRESET: PresetName;
 export declare const isSimetrikHost: (hostname: string) => boolean;
 /** The default preset for a host: `simetrik` on a Simetrik domain, else belong. */
 export declare const defaultPresetForHost: (hostname: string) => PresetName;
+/**
+ * The preset the dock boots with, given the user's stored choice and the host
+ * it's embedded on. **Brand-as-floor:** on a host that defaults to a tenant
+ * brand (a Simetrik domain), a stored *generic* built-in preset (`belong`) must
+ * not silently downgrade the brand — a stale `localStorage` preset from QA/dev
+ * once wiped Simetrik's brand on the real site. Only the user's explicit Custom
+ * theme (or a matching brand choice) overrides the host brand. On a non-branded
+ * host there's no floor to enforce, so the stored preference always wins.
+ */
+export declare const resolveInitialPreset: (storedPreset: PresetName | undefined, hostname: string) => PresetName;
 export declare const getPreset: (name: PresetName) => PartialBelongTheme;
 export declare const listPresets: () => readonly {
     name: PresetName;

package/dist/embed/theme.d.ts CHANGED Viewed

@@ -8,6 +8,19 @@ export declare const setTheme: (partial: PartialBelongTheme) => void;
  *  the Custom style overlays the user's accent/cssVars stash. */
 export declare const applyPreset: (name: PresetName) => void;
 export declare const peekPreset: () => PresetName;
+/**
+ * One-line diagnostic of how the boot theme resolved, logged once at init
+ * (see `applyInitConfig`). Pairs with the build-provenance line (plan 007 §B4)
+ * so a "the dock isn't showing our brand" report is answerable from the host
+ * console alone: it names the winning preset + brand, the host that drove the
+ * default, and whether the tenant's *published* theme overrode it on top.
+ */
+export declare const describeThemeResolution: (input: {
+    hostname: string;
+    preset: PresetName;
+    brandName: string;
+    remoteThemeApplied: boolean;
+}) => string;
 /**
  * Set (or clear, with `null`) the Custom-style accent. Updates the stash and
  * switches to the Custom style so the change is immediately visible.

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

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,18 +1,48 @@
 /**
- * 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
  * 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.
+ *
+ * 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.
  */
 /** 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;
+/**
+ * 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.
+ */
+export declare const reattachPendingLineRuns: (fetchFn?: typeof fetch) => void;
 export declare const dispatchToLine: (req: {
     readonly line: number;
     readonly request: string;

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

@@ -16,12 +16,36 @@
  *   - `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
@@ -31,12 +55,16 @@ 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;
         mimeType: string;
     }) => void;
     readonly onFinish: (finalText: string) => void;
-    readonly onError: (message: string) => void;
+    readonly onError: (message: string, kind: "terminal" | "transport") => void;
 };
 export declare const watchLineRun: (input: WatchLineRunInput, fetchFn?: typeof fetch) => (() => void);

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

@@ -0,0 +1,99 @@
+/**
+ * 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`.
+ *
+ * `runId` (F3/R4 — reload must not lie about a still-running background
+ * line): the durable half of `bindLineRun`'s in-memory tracking, written by
+ * `persistSlotRun` (`voice-call-lines.ts`) alongside every `bindLineRun` call
+ * a background dispatch makes. Without it, a page reload has no way to know
+ * a line was mid-run — `runId` lives only in JS memory otherwise, and the
+ * boot rehydrate would show a lying "idle" line while the run keeps
+ * 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).
+ */
+/** 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;
+    readonly runId: string | null;
+};
+/** Input to `writeLineSlot` — `runId` is OPTIONAL here (unlike the stored
+ * `LineSlot`) and defaults to `null` when omitted: every existing adoption
+ * call site (`persistSlotBinding`) writes a session/label pair without ever
+ * having an opinion on `runId`, and a fresh binding correctly has no run of
+ * its own yet (any run tracked against the PREVIOUS session at this slot is
+ * moot once the binding itself changes identity). `persistSlotRun` is the
+ * only writer that ever sets `runId` to a non-null value, via the narrower
+ * `writeLineSlotRun` below. */
+export type LineSlotInput = {
+    readonly sessionId: string;
+    readonly label: string;
+    readonly runId?: string | null;
+};
+/** 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, runId }` — callers (e.g.
+ * chat.tsx's per-render bind effect) call this on every render, so an
+ * unchanged binding must not touch storage. `runId` defaults to `null` when
+ * omitted (see `LineSlotInput`'s doc) — a fresh binding via this function
+ * always represents a NEW session identity, so any run tracked against
+ * whatever this slot held before is stale by construction. */
+export declare const writeLineSlot: (line: number, slot: LineSlotInput) => void;
+/** Update ONLY the persisted `runId` for a line's slot, leaving `sessionId`/
+ * `label` untouched — the durable half of `bindLineRun` (called together as
+ * `persistSlotRun` in voice-call-lines.ts), so a background line's in-flight
+ * run survives a reload (F3/R4). No-op for a line number that isn't 1/2/3,
+ * when the slot doesn't exist yet (nothing to attach a run to — the session
+ * itself hasn't been adopted), or when the runId is already what's
+ * persisted (bindLineRun's own no-op-on-unchanged tolerance, mirrored here so
+ * the two halves stay in lockstep). */
+export declare const writeLineSlotRun: (line: number, runId: string | null) => 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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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