@belonguniverseai/react-sdk 0.4.0 → 0.4.2

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

@@ -107,6 +107,13 @@ export declare const isLineReservation: (line: number, epoch: number) => boolean
  * (the boolean chat.tsx's aliasing guard needs) and `markLineSeen`'s callers
  * (which need the actual line number to mark seen). */
 export declare const lineBoundToSession: (sessionId: string) => AgentLine | undefined;
+/** The line — INCLUDING line 1 — currently bound to `sessionId`, or `undefined`
+ * when no agent holds it. Unlike `lineBoundToSession` (deliberately line-1-blind
+ * for the aliasing guard), this is the honest "which agent already owns this
+ * conversation" lookup a History reopen needs: reopening a session that Agent 1
+ * 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;
 /** 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
@@ -185,10 +192,33 @@ export declare const __bindLineSessionForTest: (line: number, sessionId: string)
 export declare const persistSlotBinding: (line: number, sessionId: string, label: string) => void;
 /** `stop_agent`'s target: bound by the line-run reader once a background
  * dispatch's POST returns a runId, and cleared to `null` when that run
- * finishes/fails/errors — a stopped or finished run must not look stoppable
- * again. No-op on an unknown line or an unchanged value (mirrors
- * `setLineStatus`'s re-write-on-every-render tolerance). */
+ * reaches a confirmed terminal state — a stopped or finished run must not look
+ * stoppable again. Transport-only failures deliberately retain it for
+ * re-attachment. No-op on an unknown line or an unchanged value (mirrors
+ * `setLineStatus`'s re-write-on-every-render tolerance). In-memory only —
+ * production code wanting the binding to SURVIVE a reload calls
+ * `persistSlotRun` below instead; this stays exported for the `__force*` /
+ * `__bindLineSessionForTest` style test harnesses that intentionally want
+ * the memory-only half. */
 export declare const bindLineRun: (line: number, runId: string | null) => void;
+/**
+ * The durable half of `bindLineRun` (F3/R4): call this — not the bare
+ * `bindLineRun` — whenever a background dispatch's POST accepts a run, and
+ * again when that run reaches a terminal state (`onFinish`/`onError`
+ * clearing it back to `null`). Updates the in-memory registry AND the
+ * 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.
+ *
+ * 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).
+ */
+export declare const persistSlotRun: (line: number, runId: string | null) => void;
 export declare const setLineStatus: (line: number, status: AgentLineStatus, lastText?: string) => void;
 /** CallScreen's agent board reads this as the live "what is it doing right
  * now" line under a working line's status dot — written on every phase

package/dist/i18n/messages/en.d.ts

@@ -65,6 +65,22 @@ export declare const en: {
         readonly reconnected: "Reconnected";
         readonly retry: "Retry";
     };
+    readonly stats: {
+        readonly title: "Session stats";
+        readonly input: "Input";
+        readonly output: "Output";
+        readonly total: "Total";
+        readonly timeRunning: "Time running";
+        readonly turns: "Turns";
+        readonly toolCalls: "Tool calls";
+        readonly runtime: "Runtime";
+        readonly empty: "No activity yet";
+        readonly loading: "Loading…";
+        readonly loadError: "Could not load stats";
+        readonly retry: "Retry";
+        readonly exportThis: "Export this session (CSV)";
+        readonly exportAll: "Export all sessions (CSV)";
+    };
     readonly sessions: {
         readonly chats: "Chats";
         readonly newChat: "New chat";
@@ -84,6 +100,7 @@ export declare const en: {
         readonly untitledSession: "Untitled session";
         readonly updated: "updated";
         readonly loadedIntoAgent: "Loaded into Agent {{line}}";
+        readonly loadingChat: "Loading chat…";
     };
     readonly scheduled: {
         readonly viewTitle: "Scheduled";
@@ -214,7 +231,11 @@ export declare const en: {
         readonly expand: "Expand";
         readonly collapse: "Collapse";
         readonly spawnAgent: "New agent";
+        readonly closeChat: "Close this chat";
         readonly closeAgent: "Close {{label}}";
+        readonly exportChat: "Download chat (JSON)";
+        readonly exportChatGenerating: "Preparing chat export…";
+        readonly exportChatLast: "Download chat (JSON) — last export {{time}}";
     };
     readonly files: {
         readonly refreshFiles: "Refresh files";
@@ -388,6 +409,7 @@ export declare const en: {
     readonly conversation: {
         readonly thinking: "Thinking…";
         readonly followerBanner: "This conversation is open in another tab";
+        readonly historyUnavailable: "Couldn't load this conversation — try reopening it.";
     };
     readonly compaction: {
         readonly compacted: "Compacted {{count}} earlier messages into a summary.";

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

@@ -16,7 +16,11 @@ export declare const headerEn: {
         readonly expand: "Expand";
         readonly collapse: "Collapse";
         readonly spawnAgent: "New agent";
+        readonly closeChat: "Close this chat";
         readonly closeAgent: "Close {{label}}";
+        readonly exportChat: "Download chat (JSON)";
+        readonly exportChatGenerating: "Preparing chat export…";
+        readonly exportChatLast: "Download chat (JSON) — last export {{time}}";
     };
 };
 export declare const headerEs: {
@@ -36,7 +40,11 @@ export declare const headerEs: {
         expand: string;
         collapse: string;
         spawnAgent: string;
+        closeChat: string;
         closeAgent: string;
+        exportChat: string;
+        exportChatGenerating: string;
+        exportChatLast: string;
     };
 };
 export declare const headerPt: {
@@ -56,6 +64,10 @@ export declare const headerPt: {
         expand: string;
         collapse: string;
         spawnAgent: string;
+        closeChat: string;
         closeAgent: string;
+        exportChat: string;
+        exportChatGenerating: string;
+        exportChatLast: string;
     };
 };

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

@@ -19,6 +19,7 @@ export declare const sessionsEn: {
         readonly untitledSession: "Untitled session";
         readonly updated: "updated";
         readonly loadedIntoAgent: "Loaded into Agent {{line}}";
+        readonly loadingChat: "Loading chat…";
     };
 };
 export declare const sessionsEs: {
@@ -41,6 +42,7 @@ export declare const sessionsEs: {
         untitledSession: string;
         updated: string;
         loadedIntoAgent: string;
+        loadingChat: string;
     };
 };
 export declare const sessionsPt: {
@@ -63,5 +65,6 @@ export declare const sessionsPt: {
         untitledSession: string;
         updated: string;
         loadedIntoAgent: string;
+        loadingChat: string;
     };
 };

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

@@ -0,0 +1,55 @@
+/** Session stats panel strings. */
+export declare const statsEn: {
+    readonly stats: {
+        readonly title: "Session stats";
+        readonly input: "Input";
+        readonly output: "Output";
+        readonly total: "Total";
+        readonly timeRunning: "Time running";
+        readonly turns: "Turns";
+        readonly toolCalls: "Tool calls";
+        readonly runtime: "Runtime";
+        readonly empty: "No activity yet";
+        readonly loading: "Loading…";
+        readonly loadError: "Could not load stats";
+        readonly retry: "Retry";
+        readonly exportThis: "Export this session (CSV)";
+        readonly exportAll: "Export all sessions (CSV)";
+    };
+};
+export declare const statsEs: {
+    stats: {
+        title: string;
+        input: string;
+        output: string;
+        total: string;
+        timeRunning: string;
+        turns: string;
+        toolCalls: string;
+        runtime: string;
+        empty: string;
+        loading: string;
+        loadError: string;
+        retry: string;
+        exportThis: string;
+        exportAll: string;
+    };
+};
+export declare const statsPt: {
+    stats: {
+        title: string;
+        input: string;
+        output: string;
+        total: string;
+        timeRunning: string;
+        turns: string;
+        toolCalls: string;
+        runtime: string;
+        empty: string;
+        loading: string;
+        loadError: string;
+        retry: string;
+        exportThis: string;
+        exportAll: string;
+    };
+};

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<{
@@ -688,6 +688,9 @@ export declare const STALL_TIMEOUT_MS = 30000;
  * 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;
@@ -714,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/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/preview-panel-store.d.ts

@@ -21,6 +21,12 @@ export declare const DEFAULT_PREVIEW_PANEL_WIDTH_PX = 480;
  * What the panel is previewing. A published artifact is fetched by id; a
  * workspace file by its workspace-relative path. Both resolve to an auth'd
  * bytes URL in `PreviewPanel`.
+ *
+ * A workspace target PINS the workspace it was opened from. The path is
+ * relative to `ws-<id>/`, so it is only meaningful together with that id —
+ * reading the live scope later instead would silently repoint an open preview
+ * at a different workspace's file (or, when the scope goes `missing`, at the
+ * unscoped root) the next time the panel re-renders.
  */
 export type PreviewTarget = {
     readonly kind: "artifact";
@@ -32,6 +38,8 @@ export type PreviewTarget = {
     readonly path: string;
     readonly title: string;
     readonly mimeType: string;
+    /** The workspace this path belongs to; null when the host configures none. */
+    readonly workspaceExternalId: string | null;
 };
 export type PreviewPanelState = {
     readonly open: boolean;

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,8 +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;
+/**
+ * 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) => void;
+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

package/package.json

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