@belonguniverseai/react-sdk 0.3.6 → 0.4.1

package/dist/stream/belong-chat-transport.d.ts

@@ -198,36 +198,36 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<"type", [z.Zo
     }, "strip", z.ZodTypeAny, {
         toolName: string;
         state: "completed" | "failed" | "started";
-        input?: Record<string, unknown> | undefined;
-        output?: Record<string, unknown> | null | undefined;
         error?: {
             message: string;
             code: string;
             severity?: "error" | "stop" | undefined;
         } | undefined;
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
     }, {
         toolName: string;
         state: "completed" | "failed" | "started";
-        input?: Record<string, unknown> | undefined;
-        output?: Record<string, unknown> | null | undefined;
         error?: {
             message: string;
             code: string;
             severity?: "error" | "stop" | undefined;
         } | undefined;
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     data: {
         toolName: string;
         state: "completed" | "failed" | "started";
-        input?: Record<string, unknown> | undefined;
-        output?: Record<string, unknown> | null | undefined;
         error?: {
             message: string;
             code: string;
             severity?: "error" | "stop" | undefined;
         } | undefined;
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
     };
     type: "data-tool-call";
 }, {
@@ -235,13 +235,13 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<"type", [z.Zo
     data: {
         toolName: string;
         state: "completed" | "failed" | "started";
-        input?: Record<string, unknown> | undefined;
-        output?: Record<string, unknown> | null | undefined;
         error?: {
             message: string;
             code: string;
             severity?: "error" | "stop" | undefined;
         } | undefined;
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
     };
     type: "data-tool-call";
 }>, z.ZodObject<{
@@ -410,18 +410,22 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<"type", [z.Zo
     data: z.ZodObject<{
         status: z.ZodEnum<["continuing", "completed", "cancelled", "failed", "throttled"]>;
         message: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
         message?: string | undefined;
+        retryable?: boolean | undefined;
     }, {
         status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
         message?: string | undefined;
+        retryable?: boolean | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     data: {
         status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
         message?: string | undefined;
+        retryable?: boolean | undefined;
     };
     type: "data-status";
 }, {
@@ -429,6 +433,7 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<"type", [z.Zo
     data: {
         status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
         message?: string | undefined;
+        retryable?: boolean | undefined;
     };
     type: "data-status";
 }>, z.ZodObject<{
@@ -667,6 +672,25 @@ export declare const RECONNECT_MAX_CONSECUTIVE_FAILURES = 10;
  * instead — the same discipline browser/control-channel.ts already applies.
  */
 export declare const STALL_TIMEOUT_MS = 30000;
+/**
+ * How long a retryable terminal (`data-status {status:"failed",
+ * retryable:true}` — a turn-deadline abort whose task WILL be reactivated on
+ * the same run/stream) may sit with no subsequent delivered event before the
+ * transport stops waiting and promotes it to a real failure. Reactivation is
+ * normally near-instant (the post-drain outbox recheck fires as the aborted
+ * drain settles) but the resumed turn can take a while to emit its first
+ * event (sandbox boot, transcript hydrate); the fleet-wide outbox sweep is
+ * the slowest legitimate path (≤60s period + ~30s first event). Without this
+ * bound a run that never resumes would hold the connection open forever —
+ * the server's 15s keepalives feed the stall watchdog, so no drop ever
+ * occurs and the composer stays wedged. Kept ≤ the persisted-cursor
+ * freshness window (stream-state-store RESUME_MAX_AGE_MS, 120s) so a reload
+ * anywhere inside an armed grace can still resume the run cursor.
+ */
+export declare const RESUME_GRACE_MS = 120000;
+/** Test-only: forget every claimed live-stream entry (module state persists
+ * across tests in the same file otherwise). */
+export declare const __resetLiveStreamRegistryForTest: () => void;
 export type BelongChatTransportOptions = {
     /** Belong cloud base URL, e.g. `http://localhost:8787`. */
     readonly apiBaseUrl: string;
@@ -680,6 +704,11 @@ export type BelongChatTransportOptions = {
      * production uses `STALL_TIMEOUT_MS`.
      */
     readonly stallTimeoutMs?: number;
+    /**
+     * Retryable-terminal grace override (§25). Tests shrink it to tens of ms;
+     * production uses `RESUME_GRACE_MS`.
+     */
+    readonly resumeGraceMs?: number;
     /**
      * Workspace isolation: the host workspace this transport's session belongs
      * to. Defaults to the CURRENT scope at construction — captured once, so a
@@ -688,6 +717,14 @@ export type BelongChatTransportOptions = {
      * Tests may pin it explicitly.
      */
     readonly workspaceExternalId?: string | null;
+    /**
+     * Foreground-mount generation (R2 — order-aware selection). Defaults to the
+     * CURRENT generation at construction — captured once, so a transport whose
+     * `select_if_empty` persist resolves AFTER a newer ChatRoute remount (a
+     * fresher chat already superseded it) never steals the selection pointer
+     * from that newer transport. Tests may pin it explicitly.
+     */
+    readonly foregroundGeneration?: number;
 };
 export type StreamContext = {
     /** Stable id we emit on every `text-delta`. Null when no text run is open. */

package/dist/stream/belong-data-parts.d.ts

@@ -147,6 +147,14 @@ export type ArtifactData = {
 export type StatusData = {
     readonly status: RunStatusKind;
     readonly message?: string | undefined;
+    /**
+     * Resume promise on a "failed" status: the backend verified the session
+     * still has pending work, so outbox recovery will reactivate the task and
+     * keep streaming into the SAME run/stream. The transport keeps its cursor
+     * open on it (no finalize) and the renderer shows a quiet "picking it back
+     * up" pill instead of a scary failure badge.
+     */
+    readonly retryable?: boolean | undefined;
 };
 /**
  * F3 — per-turn token usage + compaction context. Emitted once per turn at

package/dist/stream/chat-export-store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Chat-export state — module-level, so a pending export SURVIVES switching
+ * chats/views: the dock header (BelongDock) reads per-session state via
+ * `useSyncExternalStore`, while the poller lives here, independent of any
+ * mounted route. When the backend job turns `ready`, the file downloads
+ * AUTOMATICALLY — even if the user is viewing another chat at that moment —
+ * and the session's button reverts.
+ *
+ * Flow (see belong-cloud session-export.routes.ts):
+ *   startChatExport → POST /v1/sessions/:id/exports → 202 { exportId }
+ *   poller (~2s)    → GET  …/exports/:exportId → queued|running|ready|failed
+ *   ready           → GET  …/exports/:exportId/file → browser download
+ *
+ * Persistence (best-effort `localStorage`, Zod-parsed on read §4):
+ *   • pending exports — a page reload resumes polling and still auto-downloads
+ *   • per-session "last export" timestamps — the hover affordance. UI-ONLY by
+ *     design: the backend intentionally does not persist this.
+ */
+export type ChatExportSessionState = {
+    readonly status: "idle" | "generating";
+    /** Epoch ms of this session's last successful export download (UI-only). */
+    readonly lastExportAtMs: number | null;
+};
+export type StartChatExportResult = "started" | "already_generating" | "failed";
+/**
+ * Request a fresh export for the session and start (or join) the poller.
+ * Idempotent per session while one is in flight — the header button is also
+ * disabled while generating, but the store is the authority (§28).
+ */
+export declare const startChatExport: (apiBaseUrl: string, sessionId: string) => Promise<StartChatExportResult>;
+/** Per-session snapshot for the header button (identity-stable across reads). */
+export declare const peekChatExportState: (sessionId: string) => ChatExportSessionState;
+export declare const subscribeChatExport: (listener: () => void) => (() => void);
+/** Test-only: drop all state, listeners, storage, and the poll timer. */
+export declare const resetChatExportStoreForTests: () => void;

package/dist/stream/route-dispatch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The ONE seam that turns a `data-navigation` part into a host route-handler
+ * call — shared by the foreground renderer (`ai-sdk-part-renderers.tsx`'s
+ * `NavigationRenderer`) and a BACKGROUND line's run reader
+ * (`voice/line-run-reader.ts`), so a navigation the model dispatches on a
+ * background agent actually reaches the host instead of being silently
+ * dropped (a background line has no renderer to pick it up).
+ *
+ * Every failure mode (no handler registered, the handler throwing, the
+ * handler resolving `{ ok: false }`) collapses to one of three outcomes —
+ * never a throw — so both call sites can treat this as a plain result.
+ */
+export type RouteDispatchOutcome = "ok" | "failed" | "no_handler";
+export declare const dispatchRouteNavigation: (data: {
+    readonly routeName: string;
+    readonly params: Readonly<Record<string, string>>;
+}) => Promise<RouteDispatchOutcome>;

package/dist/stream/session-stats-csv.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Session-stats CSV builders (plan 2026-07-24). Pure string builders (no DOM)
+ * so they are unit-tested; `downloadCsv` is the only impure part.
+ *
+ * Types mirror the belong-cloud `SessionStatsDetail` / `SessionStatsSummaryRow`
+ * DTOs. Kept as an explicit local mirror (not inferred from AppType) so the CSV
+ * column contract is readable in one place.
+ *
+ * RFC-4180: CRLF line breaks, header first, a field is quoted when it contains
+ * `"`, `,`, CR or LF; interior quotes are doubled. CSV-injection guard: a text
+ * field starting with = + - @ is prefixed with a single quote before quoting.
+ */
+export type SessionStatsTurn = {
+    readonly turn: number;
+    readonly at: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+};
+export type SessionStatsDetail = {
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly turns: number;
+    readonly runningMs: number;
+    readonly toolCalls: number;
+    readonly runtimes: readonly string[];
+    readonly turnRows: readonly SessionStatsTurn[];
+};
+export type SessionStatsSummaryRow = {
+    readonly sessionId: string;
+    readonly title: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly turns: number;
+    readonly runningMs: number;
+    readonly toolCalls: number;
+    readonly runtimes: readonly string[];
+};
+/** Human duration: `m:ss` under an hour, `h:mm:ss` at/over an hour. */
+export declare const formatDurationMs: (ms: number) => string;
+export declare const toPerTurnCsv: (detail: SessionStatsDetail) => string;
+export declare const toSummaryCsv: (rows: readonly SessionStatsSummaryRow[]) => string;
+/**
+ * Trigger a browser download of `csv` as `filename`. Appends a transient anchor
+ * to document.body (NOT the shadow root) so the click reaches the top document —
+ * required for the download to fire from inside the dock's closed Shadow DOM.
+ */
+export declare const downloadCsv: (filename: string, csv: string) => void;

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

@@ -30,6 +30,23 @@ declare const streamStateSchema: z.ZodObject<{
     lastEventId: string | null;
 }>;
 export type PersistedStreamState = z.infer<typeof streamStateSchema>;
+/** Bump the foreground-mount generation. Call exactly once per ChatRoute
+ * remount (BelongDock's `chatMount.key` writers), synchronously alongside
+ * the pointer change that triggers the remount. */
+export declare const nextForegroundGeneration: () => number;
+/** Read the current foreground-mount generation without bumping it. A
+ * transport captures this at construction to stamp its later persists. */
+export declare const peekForegroundGeneration: () => number;
+/** Peek the most recent generation-loss orphan (see above), or null. A single
+ * most-recent slot, not a queue: this is a belt-and-braces safety net for the
+ * self-referential bind, not the primary recovery mechanism, and the race it
+ * guards against produces at most one loser per window in practice. */
+export declare const peekGenerationLostSession: () => string | null;
+/** Consume the orphan once a reconciler has adopted it onto a line. A no-op
+ * when `sessionId` does not match the currently-tracked loser (already
+ * consumed, or superseded by a newer loss) — a stale reconciler can never
+ * clear a loss it did not actually adopt. */
+export declare const consumeGenerationLostSession: (sessionId: string) => void;
 /**
  * The tab's active stream state.
  *
@@ -45,7 +62,20 @@ export type PersistedStreamState = z.infer<typeof streamStateSchema>;
  * is demoted off the live run cursor.
  */
 export declare const readStreamState: (workspaceId?: string | null) => PersistedStreamState | null;
-export declare const writeStreamState: (state: Omit<PersistedStreamState, "updatedAt">, workspaceId?: string | null) => void;
+/**
+ * Forget a DELETED session from the shared seed — narrowly, only when the
+ * seed still names it. `clearStreamState` (New chat) deliberately leaves the
+ * shared seed alone so an unrelated tab's most-recent conversation survives;
+ * that assumption breaks when the session in the seed was just deleted, since
+ * any brand-new tab (e.g. a spawned browser-automation preview tab — see
+ * `readStreamState`'s adoption path) would otherwise adopt a session that
+ * 404s/409s on every request. Session delete is the only caller: an ordinary
+ * "New chat" must not reach this, which is why it is a separate function
+ * rather than a flag on `clearStreamState`.
+ */
+export declare const forgetDeletedSessionSeed: (sessionId: string, workspaceId?: string | null) => void;
+export type StreamStateWriteMode = "select" | "select_if_empty" | "preserve_selection";
+export declare const writeStreamState: (state: Omit<PersistedStreamState, "updatedAt">, workspaceId?: string | null, mode?: StreamStateWriteMode, generation?: number) => void;
 /**
  * Clear THIS TAB's pointer (New chat). Removes only the per-tab sessionStorage
  * record and marks the tab "seeded" so a reload stays blank instead of
@@ -63,11 +93,11 @@ export declare const clearStreamState: (workspaceId?: string | null) => void;
  */
 export declare const readResumableStreamState: (workspaceId?: string | null) => PersistedStreamState | null;
 /**
- * Persist the chosen session as the active stream session (sessions menu
- * switch / new). Passing a session id points the next ChatRoute mount at that
- * conversation with NO live run cursor (`runId`/`lastEventId` null) — so it
- * restores from history rather than resuming a stale run. Passing null clears
- * the pointer entirely, so a fresh `belong-chat-<id>` is generated (New chat).
+ * 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
+ * its working run. Historical/terminal Sessions restore from history with no
+ * run cursor. Passing null clears only the selected pointer; parked live runs
+ * remain available when the user comes back to them.
  */
 export declare const setActiveSessionId: (sessionId: string | null) => void;
 /**

package/dist/types/public.d.ts

@@ -259,8 +259,10 @@ export type BelongGlobal = {
     readonly __forceAgentLines?: (lines: readonly {
         line: number;
         label: string;
-        status: "working" | "ready" | "failed" | "needs_approval";
+        status: "idle" | "working" | "ready" | "failed" | "needs_approval";
         sessionId?: string;
+        currentStepLabel?: string;
+        currentPhase?: "coding" | "files" | "actions";
     }[]) => void;
 };
 declare global {

package/package.json

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