@belonguniverseai/react-sdk 0.4.2 → 0.4.3

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

@@ -1,56 +1,4 @@
-/**
- * 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;
@@ -65,6 +13,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
@@ -209,14 +229,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/i18n/messages/en.d.ts

@@ -53,17 +53,22 @@ export declare const en: {
         readonly browserResolveResource: "Looked up a resource";
         readonly browserAwaitProcessed: "Waited for processing";
         readonly browserAssertCreated: "Checked for an existing resource";
+        readonly browserRefreshView: "Refreshed the page";
         readonly failedBadge: "failed";
         readonly executingTasks: "Working on it…";
         readonly workedSteps_one: "Worked · {{count}} step";
         readonly workedSteps_other: "Worked · {{count}} steps";
+        readonly cliAuthStop: {
+            readonly noGrant: "Connect to Simetrik to continue";
+            readonly reconnectFailed: "Couldn't connect to Simetrik";
+            readonly cliAuthRequired: "Reconnecting to Simetrik…";
+            readonly reconnecting: "Reconnecting to Simetrik…";
+        };
+        readonly reconnectingBadge: "reconnecting";
         readonly resumingAfterPause: "Taking longer than expected — picking it back up…";
         readonly open: "Open";
-        readonly reconnectNeeded: "The {{provider}} session needs reconnecting to continue.";
-        readonly reconnect: "Reconnect";
-        readonly reconnecting: "Reconnecting…";
-        readonly reconnected: "Reconnected";
-        readonly retry: "Retry";
+        readonly reconnectRateLimited: "{{provider}} is busy — trying again automatically in {{seconds}}s.";
+        readonly reconnectRateLimitedStill: "{{provider}} is still busy. We'll keep trying on our own.";
     };
     readonly stats: {
         readonly title: "Session stats";
@@ -128,6 +133,9 @@ export declare const en: {
         readonly customEmailLabel: "Custom email enabled";
         readonly customEmailDescription: "Each run reads the latest version of this template and sends an email only when its condition matches.";
         readonly customEmailTemplate: "HTML template";
+        readonly emailNotificationLabel: "Completion email enabled";
+        readonly emailRecipients: "Recipients";
+        readonly emailAccountRecipient: "Schedule owner's account email";
         readonly summaryOnce: "Once on {{time}}";
         readonly summaryDaily: "Daily at {{time}}";
         readonly summaryWeekdays: "Weekdays at {{time}}";
@@ -372,6 +380,7 @@ export declare const en: {
         readonly copy: "Copy";
         readonly copied: "Copied";
         readonly openExternalLink: "Open external link?";
+        readonly openInAppLink: "Open this page?";
         readonly openLinkDescriptionPrefix: "This will open";
         readonly openLinkDescriptionSuffix: "in a new tab.";
         readonly cancel: "Cancel";
@@ -527,6 +536,8 @@ export declare const en: {
         readonly notDelivered: "Not delivered — please resend";
         readonly runFailed: "Run failed";
         readonly uploadFailed: "Attachment upload failed — remove it or try again.";
+        readonly uploadRejectedType: "“{{filename}}” isn’t a file type the assistant can read — remove it. Text, data, config, code, document and image files work; archives and compiled binaries don’t.";
+        readonly uploadRejectedSecret: "“{{filename}}” looks like an environment/secrets file — it can’t be attached. Remove it and paste only the values you need.";
         readonly authExpired: "Your session expired — please sign in to {{name}} again, then retry.";
         readonly backendUnavailable: "Can't reach the assistant service — check your connection.";
         readonly streamError: "Stream error — {{message}}";

package/dist/i18n/messages/surfaces/aiElements.d.ts

@@ -33,6 +33,7 @@ export declare const aiElementsEn: {
         readonly copy: "Copy";
         readonly copied: "Copied";
         readonly openExternalLink: "Open external link?";
+        readonly openInAppLink: "Open this page?";
         readonly openLinkDescriptionPrefix: "This will open";
         readonly openLinkDescriptionSuffix: "in a new tab.";
         readonly cancel: "Cancel";
@@ -84,6 +85,7 @@ export declare const aiElementsEs: {
         copy: string;
         copied: string;
         openExternalLink: string;
+        openInAppLink: string;
         openLinkDescriptionPrefix: string;
         openLinkDescriptionSuffix: string;
         cancel: string;
@@ -135,6 +137,7 @@ export declare const aiElementsPt: {
         copy: string;
         copied: string;
         openExternalLink: string;
+        openInAppLink: string;
         openLinkDescriptionPrefix: string;
         openLinkDescriptionSuffix: string;
         cancel: string;

package/dist/i18n/messages/surfaces/scheduled.d.ts

@@ -26,6 +26,9 @@ export declare const scheduledEn: {
         readonly customEmailLabel: "Custom email enabled";
         readonly customEmailDescription: "Each run reads the latest version of this template and sends an email only when its condition matches.";
         readonly customEmailTemplate: "HTML template";
+        readonly emailNotificationLabel: "Completion email enabled";
+        readonly emailRecipients: "Recipients";
+        readonly emailAccountRecipient: "Schedule owner's account email";
         readonly summaryOnce: "Once on {{time}}";
         readonly summaryDaily: "Daily at {{time}}";
         readonly summaryWeekdays: "Weekdays at {{time}}";
@@ -120,6 +123,9 @@ export declare const scheduledEs: {
         customEmailLabel: string;
         customEmailDescription: string;
         customEmailTemplate: string;
+        emailNotificationLabel: string;
+        emailRecipients: string;
+        emailAccountRecipient: string;
         summaryOnce: string;
         summaryDaily: string;
         summaryWeekdays: string;
@@ -214,6 +220,9 @@ export declare const scheduledPt: {
         customEmailLabel: string;
         customEmailDescription: string;
         customEmailTemplate: string;
+        emailNotificationLabel: string;
+        emailRecipients: string;
+        emailAccountRecipient: string;
         summaryOnce: string;
         summaryDaily: string;
         summaryWeekdays: string;

package/dist/i18n/messages/surfaces/stream.d.ts

@@ -2,7 +2,7 @@
  * Stream part-renderer strings (`src/stream/ai-sdk-part-renderers.tsx`): the
  * cards the assistant's live stream renders — approval + choice widgets, tool
  * activity tasks, browser step labels, consolidated terminal groups, artifact
- * cards, and the CLI reconnect chip. Status-code badges (`ok` / `no_handler` /
+ * cards, and the CLI reconnect note. Status-code badges (`ok` / `no_handler` /
  * wire `data.status`) are technical chrome and stay verbatim, per the same
  * rule as `embed/copy.ts`.
  */
@@ -53,17 +53,22 @@ export declare const streamEn: {
         readonly browserResolveResource: "Looked up a resource";
         readonly browserAwaitProcessed: "Waited for processing";
         readonly browserAssertCreated: "Checked for an existing resource";
+        readonly browserRefreshView: "Refreshed the page";
         readonly failedBadge: "failed";
         readonly executingTasks: "Working on it…";
         readonly workedSteps_one: "Worked · {{count}} step";
         readonly workedSteps_other: "Worked · {{count}} steps";
+        readonly cliAuthStop: {
+            readonly noGrant: "Connect to Simetrik to continue";
+            readonly reconnectFailed: "Couldn't connect to Simetrik";
+            readonly cliAuthRequired: "Reconnecting to Simetrik…";
+            readonly reconnecting: "Reconnecting to Simetrik…";
+        };
+        readonly reconnectingBadge: "reconnecting";
         readonly resumingAfterPause: "Taking longer than expected — picking it back up…";
         readonly open: "Open";
-        readonly reconnectNeeded: "The {{provider}} session needs reconnecting to continue.";
-        readonly reconnect: "Reconnect";
-        readonly reconnecting: "Reconnecting…";
-        readonly reconnected: "Reconnected";
-        readonly retry: "Retry";
+        readonly reconnectRateLimited: "{{provider}} is busy — trying again automatically in {{seconds}}s.";
+        readonly reconnectRateLimitedStill: "{{provider}} is still busy. We'll keep trying on our own.";
     };
 };
 export declare const streamEs: {
@@ -113,17 +118,22 @@ export declare const streamEs: {
         browserResolveResource: string;
         browserAwaitProcessed: string;
         browserAssertCreated: string;
+        browserRefreshView: string;
         failedBadge: string;
         executingTasks: string;
         workedSteps_one: string;
         workedSteps_other: string;
+        cliAuthStop: {
+            noGrant: string;
+            reconnectFailed: string;
+            cliAuthRequired: string;
+            reconnecting: string;
+        };
+        reconnectingBadge: string;
         resumingAfterPause: string;
         open: string;
-        reconnectNeeded: string;
-        reconnect: string;
-        reconnecting: string;
-        reconnected: string;
-        retry: string;
+        reconnectRateLimited: string;
+        reconnectRateLimitedStill: string;
     };
 };
 export declare const streamPt: {
@@ -173,16 +183,21 @@ export declare const streamPt: {
         browserResolveResource: string;
         browserAwaitProcessed: string;
         browserAssertCreated: string;
+        browserRefreshView: string;
         failedBadge: string;
         executingTasks: string;
         workedSteps_one: string;
         workedSteps_other: string;
+        cliAuthStop: {
+            noGrant: string;
+            reconnectFailed: string;
+            cliAuthRequired: string;
+            reconnecting: string;
+        };
+        reconnectingBadge: string;
         resumingAfterPause: string;
         open: string;
-        reconnectNeeded: string;
-        reconnect: string;
-        reconnecting: string;
-        reconnected: string;
-        retry: string;
+        reconnectRateLimited: string;
+        reconnectRateLimitedStill: string;
     };
 };

package/dist/stream/chat-upload.d.ts

@@ -1,8 +1,34 @@
 import { FileUIPart } from 'ai';
-/** Normalise to the server's allow-list by extension (browsers report .md/.csv inconsistently). */
+/**
+ * Normalise to the server's allow-list by extension (browsers report .md/.csv/
+ * .yaml inconsistently). An unknown extension keeps whatever the browser said,
+ * and an unknown extension with NO browser type reports `application/octet-
+ * stream` — deliberately NOT `text/plain`, which used to smuggle `.pyc`/`.pkl`
+ * and other typeless binaries onto the text allow-list where they were inlined
+ * to the model as mojibake. The server refuses those with a named reason.
+ */
 export declare const resolveMimeType: (file: File) => string;
-/** Upload one file to the server, returning its fileId (or null on failure). */
-export declare const uploadOneFile: (apiBaseUrl: string, file: File) => Promise<string | null>;
+/** Why an attachment upload failed — a named reason, not a bare null (§19/§20). */
+export type AttachmentUploadReason = "workspace_scope_missing" | "secrets_by_convention" | "unsupported_file_type" | "upload_failed";
+/**
+ * A failed attachment upload, carrying the filename + reason so the composer can
+ * tell the user WHICH file was refused and WHY instead of a generic banner
+ * (007-plan C6 — a silent/anonymous upload failure is the known defect class).
+ */
+export declare class AttachmentUploadError extends Error {
+    readonly filename: string;
+    readonly reason: AttachmentUploadReason;
+    constructor(filename: string, reason: AttachmentUploadReason);
+}
+export type UploadOneFileResult = {
+    readonly ok: true;
+    readonly fileId: string;
+} | {
+    readonly ok: false;
+    readonly reason: AttachmentUploadReason;
+};
+/** Upload one file to the server, returning its fileId or a named refusal. */
+export declare const uploadOneFile: (apiBaseUrl: string, file: File) => Promise<UploadOneFileResult>;
 /**
  * Bridge the PromptInput's `file` parts (data-url FileUIParts) to the
  * upload-first wire: upload each, in order, and return the server fileIds.

package/dist/stream/run-line-progress.d.ts

@@ -0,0 +1,62 @@
+import { RunStatusKind } from './belong-data-parts.ts';
+/**
+ * What a run reported, reduced to the only four things a rail chip can show.
+ *
+ * `activity` is the tool-LESS turn's path to a truthful "working" badge: a
+ * turn that only writes text calls no tools, so `tool_started` never fires and
+ * the chip would otherwise sit at "idle" through the whole answer.
+ *
+ * There is deliberately NO `text` variant. An accumulator feeding
+ * `AgentLine.lastText` was specified and dropped: nothing in the dock renders
+ * `lastText`, and because this seam no-ops while the session is on screen the
+ * accumulator could only ever have collected the post-switch TAIL of an
+ * answer. Re-add it when something renders it.
+ *
+ * `terminal` carries the run's OWN id, and it is not decoration: the durable
+ * slot runId this seam clears is shared with the voice dispatch, and a line can
+ * hold a live voice run at the same moment a DIFFERENT (typed) run on the same
+ * session finishes. Clearing by session alone unbinds `stop_agent`'s target for
+ * a run that is still going. `status` is spelled from the wire union rather
+ * than by hand so a new `RunStatusKind` fails CI here (§21).
+ */
+export type RunLineProgressEvent = {
+    readonly kind: "activity";
+} | {
+    readonly kind: "tool_started";
+    readonly toolName: string;
+} | {
+    readonly kind: "approval_pending";
+} | {
+    readonly kind: "terminal";
+    readonly runId: string;
+    readonly status: Exclude<RunStatusKind, "continuing">;
+};
+/**
+ * Report one run event for `sessionId`. Silently does nothing when no agent
+ * line owns that session.
+ *
+ * Two writes with two different scopes, in this order:
+ *
+ *  1. A TERMINAL clears the line's durable slot runId — including for the
+ *     session on screen — but ONLY when the slot still names the run that just
+ *     ended. `attachLineReader`'s terminal callbacks used to be the only code
+ *     in the tree that ever cleared it, so a background line's run that
+ *     finished while the user was LOOKING at that line left a stale runId
+ *     behind, and every later reload rehydrated the chip as a permanently
+ *     stuck "working" (§41 violation). The id check is what keeps that fix
+ *     from becoming its own bug: the slot is also `stop_agent`'s target, and a
+ *     line can hold a LIVE voice run at the moment an older typed run on the
+ *     same session terminates. Clearing that would leave a running agent
+ *     unstoppable and its chip claiming "done" mid-run.
+ *  2. The BADGE writes are skipped for the session on screen. That line's
+ *     status is chat.tsx's exclusive business — it is mounted, it has the real
+ *     stream status, and it drives the call narration. Leaving the foreground
+ *     byte-for-byte unchanged is what makes this seam safe to add.
+ *
+ * Applied to EVERY line bound to the session, not the first match — same
+ * reasoning as `markSessionSeen` / `releaseLinesForSession`, which have always
+ * iterated: line 1 aliases whatever the chat is showing, so a background line
+ * the user opened is held by both, and a legacy slots bag can rehydrate two
+ * lines onto one session. Writing only the first left the other frozen.
+ */
+export declare const reportRunLineProgress: (sessionId: string, event: RunLineProgressEvent) => void;

package/dist/stream/sandbox-output.d.ts

@@ -1,7 +1,23 @@
-import { SandboxCommandData, ToolCallData } from './belong-data-parts.ts';
+import { SandboxCommandData, ToolCallData, ToolErrorSeverity } from './belong-data-parts.ts';
 /** The shell tools across runtimes; both carry `input.command` + `output.exitCode`. */
 export declare const SHELL_TOOL_NAMES: ReadonlySet<string>;
 export declare const isShellToolName: (toolName: string) => boolean;
+/**
+ * The ONE place that decides whether a wire severity means "SURFACES on the
+ * collapsed activity line".
+ *
+ * It used to mean "red". BEL-96 dropped red from the execution surfaces
+ * entirely — every failure now reads orange, stopping or not — so severity no
+ * longer picks a colour. What it still picks is whether the user is shown the
+ * failure at all: an ordinary one stays folded inside "Worked · N steps", a
+ * stopping one is lifted onto the collapsed line.
+ *
+ * Every consumer used to be a bare `=== "stop"`, so a third member added to
+ * `ToolErrorSeverity` would have compiled clean everywhere and silently
+ * rendered as non-stop. `.exhaustive()` turns that into a CI failure at this
+ * single site.
+ */
+export declare const isStoppingSeverity: (severity: ToolErrorSeverity | undefined) => boolean;
 /**
  * BEL-97 — how a finished shell command's outcome should be coloured.
  *
@@ -9,12 +25,24 @@ export declare const isShellToolName: (toolName: string) => boolean;
  *                  failed with exit 0 (successful execution despite wrapper error),
  *                  or timed out (still running in the sandbox).
  *   - `"notice"` — an ORDINARY failure (non-zero exit, or a tool error with no
- *                  stop-severity). Orange, NOT red: the agent kept going.
+ *                  stop-severity). Orange, and folded away.
  *   - `"stop"`   — an agent-execution-STOPPING failure (a denied permission, an
- *                  aborting error: `error.severity === "stop"`). Red.
+ *                  aborting error: `error.severity === "stop"`). Also orange
+ *                  since BEL-96 — what sets it apart is that it SURFACES on
+ *                  the collapsed line, not that it is a different colour.
  *
  * One source of truth shared by `TerminalTask` (its status badge) and
  * `ActivityGroup` (its aggregate failure badge).
+ *
+ * BEL-96 — ORDER MATTERS, and the two observable-outcome guards go FIRST.
+ * §42 words both as absolutes ("`exit 0` is ALWAYS a success regardless of wire
+ * state"; a timed-out command "reads 'still running', not 'failed'"), and a
+ * `severity` check ahead of them defeated both: `exit0 + stop` measured "stop",
+ * `timeout + stop` measured "stop". That was unreachable while nothing on the
+ * server emitted a stop severity, but `tool-executor.ts` now forwards
+ * `error.severity` for ANY registry tool including `run_shell`. Observable
+ * outcome beats declared state — the same rule the exit-0 guard already
+ * encoded, now applied consistently.
  */
 export type TerminalSeverity = "none" | "notice" | "stop";
 export declare const terminalCommandSeverity: (command: ToolCallData) => TerminalSeverity;

package/dist/stream/stream-state-store.d.ts

@@ -92,6 +92,62 @@ export declare const clearStreamState: (workspaceId?: string | null) => void;
  * message overwrites the cursor via {@link writeStreamState}.
  */
 export declare const readResumableStreamState: (workspaceId?: string | null) => PersistedStreamState | null;
+/**
+ * Was a run still in flight for `sessionId` when this page last looked — the
+ * ONE query behind "a reload must not lie about a backgrounded agent"
+ * (BEL-90 / §41). The parked-cursor map already carries exactly this truth
+ * for every session this tab drove: it lives in `sessionStorage`, so it
+ * survives a genuine reload and is correctly absent in a brand-new tab, which
+ * owns no reader for the run.
+ *
+ * Gated on the same {@link RESUME_MAX_AGE_MS} window {@link setActiveSessionId}
+ * and {@link readResumableStreamState} use, so a run abandoned by a worker
+ * restart ages out into `null` instead of pinning a badge at "working"
+ * forever. Non-throwing and null-returning like its neighbours.
+ *
+ * That gate is only honest while SOMETHING re-stamps the cursor for a live but
+ * silent run — see {@link touchParkedRun}. The transport does it from its
+ * `: keepalive` handler; a reader that adopts a run WITHOUT a transport (the
+ * boot re-attach in `line-dispatch.ts`) must do it too, or a genuinely
+ * streaming run reads "idle" on the next reload.
+ *
+ * NOTE the boundary this does NOT cover: a line's DURABLE slot runId
+ * (`line-slots.ts`) is written by voice dispatch and is not consulted here,
+ * so a slot runId left behind by a reader torn down mid-flight
+ * (`abortAllLineReaders`) bypasses this freshness gate entirely — that path is
+ * `resetForCallStart`'s to clean up, not this one's.
+ */
+export declare const peekLiveParkedRun: (sessionId: string) => string | null;
+/**
+ * Prove `runId` is still alive: re-stamp `sessionId`'s parked cursor's
+ * `updatedAt` so the {@link RESUME_MAX_AGE_MS} gate in
+ * {@link peekLiveParkedRun} keeps returning it (BEL-90 / §41).
+ *
+ * This is the SAME job the transport's `onKeepalive` → `#persist()` does, made
+ * callable by the one reader that has no transport behind it: after a reload
+ * `line-dispatch.ts`'s progress reader is the only listener on a backgrounded
+ * typed run's stream, so without this a run doing 2 minutes of silent tool work
+ * ages out of the cursor map and the next reload paints its chip "idle" while
+ * it is still streaming.
+ *
+ * Deliberately touches ONLY the parked map, never the selected pointer: the
+ * caller attaches exclusively to sessions that are NOT on screen, and moving
+ * the selection would hijack the user's chat. No-op unless the cursor still
+ * names `runId` — a cursor that moved on belongs to a newer run, and the
+ * caller has no claim on it.
+ */
+export declare const touchParkedRun: (sessionId: string, runId: string) => void;
+/**
+ * `runId` reached a terminal state — drop `sessionId`'s parked cursor so
+ * nothing rehydrates the line as "working" for a run that is already done
+ * (BEL-90 / §41, the mirror of {@link touchParkedRun}).
+ *
+ * The transport gets this for free from `onStreamTerminal` → `#persist()` with
+ * a null `#runId`; the progress reader has no transport, so it calls this. Same
+ * ownership guard: a cursor naming a DIFFERENT run is someone else's live run
+ * and is left alone.
+ */
+export declare const releaseParkedRun: (sessionId: string, runId: string) => void;
 /**
  * Select one Session (sessions menu switch / new). A Session with a live cursor
  * parked by this tab restores that cursor so the next ChatRoute mount resumes

package/dist/stream/tool-error-copy.d.ts

@@ -0,0 +1,4 @@
+import { TFunction } from 'i18next';
+import { ToolCallData } from './belong-data-parts.ts';
+/** Localised copy for a tool error, or the server's message when unmapped. */
+export declare const toolErrorText: (t: TFunction, error: ToolCallData["error"]) => string | undefined;

package/dist/test/fetch-stubs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared fetch-stub bodies for the preview surfaces.
+ *
+ * `usePreviewBytes` reads a text preview as BYTES (`res.arrayBuffer()`) rather
+ * than `res.text()`, so it can fall back to windows-1252 when a file isn't
+ * valid UTF-8 — a stub that only implements `text()` therefore no longer models
+ * a Response the hook can consume. `textResponseStub` implements both, so a
+ * test can stay agnostic about which one the code under test reaches for.
+ */
+export type TextResponseStub = {
+    readonly ok: true;
+    readonly status: 200;
+    readonly text: () => Promise<string>;
+    readonly arrayBuffer: () => Promise<ArrayBuffer>;
+};
+export declare const textResponseStub: (text: string) => TextResponseStub;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belonguniverseai/react-sdk",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Belong — embeddable React AI assistant dock. Mount <BelongWidget> in your app tree with getToken dependency-injection auth.",
   "license": "UNLICENSED",
   "type": "module",