@belonguniverseai/react-sdk 0.4.2 → 0.5.0

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

@@ -12,8 +12,12 @@ export type CallTimelineEntry = {
     readonly atMs: number;
     readonly kind: "user" | "agent" | "step" | "success" | "error" | "skill" | "schedule";
     readonly text: string;
-    /** Agent tag for Operator-mode rows (e.g. "A2"); absent for foreground rows. */
-    readonly lineTag?: string;
+    /** The switchboard line this row concerns; `null` for a foreground (line 1)
+     * row. CallScreen's `labelFor` resolves `line ?? 1` to look up the agent's
+     * short board label for `step`/`success`/`error` rows (X2b) — the label
+     * column names the agent, so `text` itself never repeats a title prefix or
+     * an "A2"-style tag. */
+    readonly line: number | null;
 };
 export type CallState = {
     readonly status: CallStatus;
@@ -112,14 +116,55 @@ declare let lineDispatcher: ((req: {
     readonly isNewLine: boolean;
 }) => void) | null;
 export declare const registerCallLineDispatcher: (dispatcher: NonNullable<typeof lineDispatcher>) => (() => void);
+/**
+ * Last-resort delivery for `flushLineQueuesOnCallEnd` when no `lineDispatcher`
+ * is wired (the M7 gap — ChatRoute unmounted). Self-registered by
+ * line-dispatch.ts (see the bottom of that file) with the real
+ * `dispatchToLine` — deliberately NOT imported here directly. `line-dispatch.ts`
+ * already imports six functions FROM this module (buildCallContextDigest,
+ * the deliver/notify callbacks, peekCallState, subscribeCallState), so a
+ * static import the other way would close a two-way cycle between
+ * voice-call.ts and line-dispatch.ts — forbidden outright by
+ * `.dependency-cruiser.cjs`'s `no-circular` rule (severity: error, applies
+ * everywhere, not just the hexagonal backend layers). Registering FROM
+ * line-dispatch.ts, in the SAME direction its existing dependency already
+ * runs, avoids the cycle entirely; that file's own `subscribeCallState`
+ * self-subscribe (its module doc, right above `abortAllLineReaders`) is the
+ * identical idiom already established there.
+ *
+ * Investigated and confirmed SOUND as a fallback: chat.tsx's own
+ * `registerCallLineDispatcher` wrapper does nothing beyond routing line 1 to
+ * `sendCallText` and calling this exact function, unmodified, for any other
+ * line — see that effect in chat.tsx. Held/queued items only ever exist for
+ * background lines (line 1 never enqueues — see the busy-line branch above),
+ * so every item this fallback ever sees is exactly the shape ChatRoute's
+ * wrapper would have passed through unchanged. No ChatRoute-specific
+ * behavior is lost by calling it directly.
+ *
+ * Deliberately SEPARATE from `lineDispatcher` — not folded into
+ * `releaseHeldRequest` itself — so `pumpLineQueue`'s live-queue draining is
+ * UNAFFECTED: it must keep checking `lineDispatcher` and leaving an item
+ * queued (not popped) when nothing is wired, per its own doc. Only the
+ * end-of-call flush, which has nothing left to leave a drained item queued
+ * IN, reaches for this.
+ */
+declare let lineDispatchFallback: ((req: {
+    readonly line: number;
+    readonly request: string;
+    readonly isNewLine: boolean;
+}) => Promise<void>) | null;
+export declare const registerLineDispatchFallback: (dispatcher: NonNullable<typeof lineDispatchFallback>) => (() => 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
- * approve or reject out loud.
+ * approve or reject out loud. `reason` is the approval part's own `reason`
+ * field (via the approval bus's `PendingApproval.reason`) — on a phone call
+ * the user cannot see the card, so WHAT it wants to do has to travel in the
+ * prompt, not stay something only "open the chat view" could answer.
  */
-export declare const notifyCallApprovalRequired: (timelineText: string) => void;
+export declare const notifyCallApprovalRequired: (timelineText: string, reason: string) => void;
 /** Live speech level, 0..1 (max of agent voice + user mic). */
 export declare const peekCallAudioLevel: () => number;
 /** ChatRoute reports a tool-phase change on the delegated run — the strongest
@@ -129,7 +174,7 @@ export declare const notifyCallProgress: (hint: string) => void;
  * small work badge while the agent is busy. */
 export declare const setCallWorkPhase: (phase: CallState["workPhase"]) => void;
 /**
- * Click-path twin of `show_agent_line`: the lines strip chip on CallScreen
+ * Click-path twin of `show_agent`: the lines strip chip on CallScreen
  * calls this directly (no tool-call round trip, no ack). No-op when the line
  * is unknown, never bound to a session, or no view switcher is registered
  * (e.g. ChatRoute hasn't mounted).
@@ -173,7 +218,8 @@ export declare const deliverAgentReply: (text: string) => void;
  * must tell the user something went wrong and offer to retry.
  */
 export declare const deliverAgentFailure: (message: string) => void;
-/** A background line finished: relay its final text, naming the line. */
+/** A background line finished: relay its final text, naming the agent by
+ * role. */
 export declare const deliverLineReply: (line: number, text: string) => void;
 /**
  * A background line published an artifact: OPEN it on screen, mirroring
@@ -188,16 +234,26 @@ export declare const deliverLineArtifact: (line: number, artifact: {
     readonly title: string;
     readonly mimeType: string;
 }) => void;
-/** A background line failed: tell the user, naming the agent. */
+/** A background line failed: tell the user, naming the agent by role. */
 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 is blocked on a tool approval — steer the user to it,
+ * by role, and tell the model WHAT it wants to do. W3: the old text asked
+ * the user to say a magic phrase ("show <title>") and never said what was
+ * being approved — unanswerable on a phone call, where there is no screen to
+ * "go look at". `reason` is the approval part's own `reason` field, threaded
+ * from the run stream via `onApprovalNeeded` (line-run-reader.ts). */
+export declare const notifyLineApprovalNeeded: (line: number, timelineText: string, reason: 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`
+ * (CallScreen's agent board reads `currentStepLabel`/`currentPhase` off the
+ * registry) and nudge a spoken update. X2a: deliberately NO timeline row per
+ * phase change any more — the board's own card already shows the identical
+ * string live, and a 12-step run used to write 12 near-identical Activity
+ * rows that buried the actual results; the durable Activity-log row for a
+ * background line's work is the ONE `dispatchToBackgroundLine` appends up
+ * front. 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. */
+ * spoken nudge 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;
@@ -209,7 +265,7 @@ export declare const isCallActive: () => boolean;
  */
 export declare const __forceCallState: (patch: Partial<CallState>) => void;
 /** TEST-ONLY companion: append a timeline row while in a forced state. */
-export declare const __forceCallTimelineEntry: (kind: CallTimelineEntry["kind"], text: string, lineTag?: string) => void;
+export declare const __forceCallTimelineEntry: (kind: CallTimelineEntry["kind"], text: string, line?: number | null) => void;
 /** TEST-ONLY companion: drive the orb's audio level without Web Audio. */
 export declare const __forceCallAudioLevel: (level: number) => 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";
@@ -471,9 +480,6 @@ export declare const en: {
         readonly muted: "Mic muted";
         readonly youSaid: "You said";
         readonly agentSaid: "Agent";
-        readonly step: "Working";
-        readonly done: "Done";
-        readonly failed: "Failed";
         readonly speakHint: "Speak to the agent…";
         readonly readyHint: "I'm listening — speak when you're ready.";
         readonly thinkingHint: "Thinking…";
@@ -492,22 +498,24 @@ export declare const en: {
         readonly skillNotFound: "No exact skill match for “{{query}}”";
         readonly skillCatalogUnavailable: "Skill catalog unavailable — retrying";
         readonly noSkillsConfigured: "No skills configured in this workspace";
-        readonly phaseCoding: "Writing code";
-        readonly phaseFiles: "Working with files";
-        readonly phaseActions: "Taking actions";
+        readonly phaseCoding: "Putting the steps together";
+        readonly phaseFiles: "Going through your data";
+        readonly phaseActions: "Running the steps";
         readonly lines: "Agents";
         readonly lineLabel: "Agent {{line}}";
         readonly mainAgentLabel: "Main agent";
-        readonly lineNeedsApproval: "needs approval";
-        readonly lineWorking: "working";
-        readonly lineReady: "ready";
-        readonly lineFailed: "failed";
-        readonly lineIdle: "idle";
-        readonly lineNotStarted: "not started";
-        readonly lineNoChat: "no chat yet";
+        readonly roleLabelMain: "Main agent";
+        readonly roleLabelData: "{{product}} data agent";
+        readonly roleLabelDataGeneric: "Data agent";
+        readonly roleLabelAnalyst: "Analyst";
+        readonly lineNeedsApproval: "Needs your OK";
+        readonly lineWorking: "Working…";
+        readonly lineReady: "Done";
+        readonly lineFailed: "Couldn't finish";
+        readonly lineIdle: "Ready";
         readonly activity: "Activity";
-        readonly showConversationLog: "Show conversation log";
-        readonly hideConversationLog: "Hide conversation log";
+        readonly showConversationLog: "Show what was said";
+        readonly hideConversationLog: "Hide what was said";
         readonly ambientTypingCode: "Typing code…";
         readonly ambientReviewingDiff: "Reviewing the diff…";
         readonly ambientRunningChecks: "Running checks…";
@@ -527,6 +535,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/dist/types/public.d.ts

@@ -252,7 +252,7 @@ export type BelongGlobal = {
         errorMessage?: string;
     }) => void;
     /** TEST-ONLY: append a live-call timeline row. */
-    readonly __forceCallTimelineEntry?: (kind: "user" | "agent" | "step" | "success" | "error" | "skill" | "schedule", text: string, lineTag?: string) => void;
+    readonly __forceCallTimelineEntry?: (kind: "user" | "agent" | "step" | "success" | "error" | "skill" | "schedule", text: string, line?: number | null) => void;
     /** TEST-ONLY: drive the call orb's audio level (0..1) without Web Audio. */
     readonly __forceCallAudioLevel?: (level: number) => void;
     /** TEST-ONLY: force the agent-lines switchboard state without HTTP dispatch. */

package/package.json

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