@belonguniverseai/react-sdk 0.6.24 → 0.6.25

package/dist/routes/chat/use-session-goal.d.ts

@@ -38,7 +38,12 @@ export type StartGoalInput = {
  * which is normally one the user already settled. Prefer an explicitly pending
  * card; otherwise take the last.
  */
-export declare const scrollAndFocusPendingCard: (kind: PendingCardKind) => void;
+export declare const scrollAndFocusPendingCard: (kind: PendingCardKind, 
+/**
+ * Where to look: the dock's root. In production that is a SHADOW root,
+ * which `document.querySelectorAll` cannot see into.
+ */
+root?: ParentNode) => void;
 /** Every prop `<GoalComposeSheet>` takes — named once so `composeSheet` and
  *  `goalDoor.composeSheet` below don't have to repeat the shape. */
 type GoalComposeSheetProps = {

package/dist/routes/chat.d.ts

@@ -1,30 +1,17 @@
-/**
- * ChatRoute — the embedded dock's chat surface, driven by Vercel AI
- * SDK's `useChat` over a custom `BelongChatTransport`.
- *
- *   useChat<BelongUIMessage>({ id, transport, resume })
- *     ↓ sendMessage({ text }, { body: { fileIds } })
- *   BelongChatTransport.sendMessages()
- *     ↓ POST /v1/sessions(/$id)?/messages → { runId }
- *     ↓ GET  /v1/runs/$runId/stream (SSE, Bearer JWT, Last-Event-Id)
- *   useChat appends to message.parts → <PartRenderer> dispatches.
- *
- * Features wired here:
- *   - Attachments: the AI-Elements <PromptInput> owns picking (click /
- *     drag-drop / paste) and renders inline chips. On submit we upload each
- *     picked file to POST /v1/files (upload-first) and thread the returned
- *     fileIds via the sendMessage body, while carrying the `file` parts on the
- *     user message so the attachments also render on the bubble in the stream.
- *   - Resume: a stable chat id + `resume` re-attach an in-flight run after a
- *     page reload (the transport persists the cursor to localStorage).
- *   - Voice: final transcripts from the dock Mic button submit as messages.
- */
+import { QueryClient } from '@tanstack/react-query';
+import { HistoryScope } from './chat/history-cache.ts';
 export type QueuedMessage = {
     readonly clientId: string;
     readonly text: string;
     readonly submittedAt: number;
     readonly state: "queued" | "failed";
 };
+/**
+ * Read a chat's newest page ahead of opening it (the Chats list's
+ * `SessionIntentContext`), so it opens painted from the cache. A chat kept
+ * live needs no read; a page read in the last 30 s is not read again.
+ */
+export declare const prefetchChatHistory: (queryClient: QueryClient, apiBaseUrl: string, scope: HistoryScope) => void;
 export declare const ChatRoute: ({ sessionId, draftId, reconcileBackgroundRun, onOpenGoalView, onOpenFilesView, }?: {
     readonly sessionId?: string;
     readonly draftId?: string;

package/dist/stream/activity-items.d.ts

@@ -3,6 +3,8 @@ import { SandboxCommandData, SubagentData, ToolCallData } from './belong-data-pa
 export type ToolActivityItem = {
     readonly tool: ToolCallData;
     readonly output: SandboxCommandData | null;
+    /** The call's part id — how a summarized history card fetches its full output. */
+    readonly toolCallId?: string;
 };
 /**
  * BEL-199 — a delegated subagent in an activity run. It sits INSIDE the one

package/dist/stream/ai-sdk-part-renderers.d.ts

@@ -2,10 +2,19 @@ import { MessageContinuation } from './message-continuation.ts';
 import { BelongDataParts, BelongUIMessage, GoalProposalData } from './belong-data-parts.ts';
 import { ActivityItem } from './activity-items.ts';
 import { SubagentLanesContext, SubagentMessageIndex } from './subagent-lanes-model.ts';
-export declare const ActivityGroup: ({ items, live, subagents, }: {
+export declare const ActivityGroup: ({ items, live, keepContentMounted, subagents, }: {
     readonly items: readonly ActivityItem[];
     /** The collapsed line's shimmer: true only for the LAST group of the streaming message. */
     readonly live?: boolean | undefined;
+    /**
+     * Keep the collapsed content mounted (hidden). A live group needs it: its
+     * terminal cards accumulate streamed output in component state
+     * (`useSandboxOutputText`) and `SkillLibraryToolSync` must see the call
+     * finish. A settled, restored group has neither, so `MessageParts` passes
+     * `false` and its content mounts on open — otherwise a long conversation
+     * mounts every tool card of every turn at once.
+     */
+    readonly keepContentMounted?: boolean | undefined;
     /**
      * Spec 2026-09-16 §4a — the message this group belongs to. The lanes nest
      * their calls (and a wave its lanes) from every group of it, and tick and
@@ -30,6 +39,10 @@ type TextSegment = {
  * `text.slice(start+1, end)` with its `\ ` escapes resolved, so a filename with
  * spaces renders as one pill. Text with no mention yields a single `text`
  * segment. Pure.
+ *
+ * An `@` inside markdown code (`@media` in CSS, `@Component`, `@belong/sdk` in
+ * a shell line) is code, never a reference: splitting there would cut the
+ * markdown mid-fence and render the rest of the block as live markup.
  */
 export declare const splitMentionSegments: (text: string) => readonly TextSegment[];
 export type BelongMessagePart = BelongUIMessage["parts"][number];

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

@@ -114,6 +114,7 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             }>>;
         }, z.core.$strip>>;
         subagentId: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-subagent">;
@@ -161,7 +162,10 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             stderr: "stderr";
         }>>;
         delta: z.ZodOptional<z.ZodString>;
+        seq: z.ZodOptional<z.ZodNumber>;
+        throughSeq: z.ZodOptional<z.ZodNumber>;
         exitCode: z.ZodOptional<z.ZodNumber>;
+        summary: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-ui-action">;
@@ -510,6 +514,24 @@ export declare class BelongChatTransport implements ChatTransport<BelongUIMessag
     /** Includes an outstanding SSE handshake and the transport's retry loop,
      * which can own the Session before useChat reports `streaming`. */
     get hasLiveStream(): boolean;
+    /** Like {@link hasLiveStream}, but only when the live stream is THIS
+     * transport's: what it reads lands in its own chat. */
+    get holdsLiveStream(): boolean;
+    /** The run this transport is following; null before one, and once it ended. */
+    get runId(): string | null;
+    /**
+     * The newest row of the server history the chat now holds. A resume with no
+     * cursor names it (`historyThrough`), so the server leaves to the history
+     * only the turns it holds: a reply saved after that history was read is
+     * replayed rather than lost.
+     */
+    noteHistoryThrough(messageId: string | null): void;
+    /**
+     * A kept chat shown again is the foreground chat: stamp its later
+     * `select_if_empty` writes with the current generation, as a fresh mount's
+     * transport would be (R2).
+     */
+    takeForeground(): void;
     /** Forget an unavailable session so the next send creates a fresh one. */
     reset(): void;
     /**

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

@@ -148,6 +148,12 @@ export type ToolCallData = {
      * lane is in the same group; otherwise it stays a flat item (§41).
      */
     readonly subagentId?: string | undefined;
+    /**
+     * Set only on a HISTORY part the server's summary view capped (a shell
+     * call's command/output, a skill's body): the full part is one
+     * `GET /v1/sessions/:id/tool-calls/:toolCallId` away (`tool-call-detail.ts`).
+     */
+    readonly summary?: true | undefined;
 };
 /**
  * BEL-199 — one delegated subagent. `running → finished | failed`, one part per
@@ -212,7 +218,14 @@ export type SandboxCommandData = {
      * identity churns on every unrelated stream chunk and is NOT a signal.
      */
     readonly seq?: number | undefined;
+    /**
+     * A resumed run's replay (belong-cloud `run-replay-snapshot.ts`): `delta` is
+     * the command's WHOLE output through this seq, to set rather than append.
+     */
+    readonly throughSeq?: number | undefined;
     readonly exitCode?: number | undefined;
+    /** A history part whose output the summary view cut to its tail (see ToolCallData). */
+    readonly summary?: true | undefined;
 };
 export type UiActionData = {
     readonly uiActionRequestId: string;

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

@@ -0,0 +1,12 @@
+/** Claims `key`; false when it already fired on this page. */
+export declare const claimDispatch: (key: string) => boolean;
+/**
+ * Run `effect` once for `key` on this page — or, without a key, once for the
+ * component's lifetime (React 19 StrictMode double-invokes included).
+ */
+export declare const useDispatchOnce: (key: string | undefined, effect: () => void, deps: readonly unknown[]) => void;
+/** Where a dispatch card's one-shot call stands. */
+export type DispatchStatus = "dispatching" | "running" | "ok" | "no_handler" | "failed" | "done";
+/** What a dispatch card shows, remembered by the same key as its guard. */
+export declare const dispatchStatuses: import('../lib/remembered-state.ts').RememberedState<DispatchStatus>;
+export declare const __resetDispatchOnceForTest: () => void;

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

@@ -0,0 +1,14 @@
+import { SandboxCommandData } from './belong-data-parts.ts';
+type Accumulated = {
+    readonly text: string;
+    /** Highest live seq folded into `text`; -1 before any. */
+    readonly appliedThroughSeq: number;
+};
+/** The next state for one part, or `current` itself when it changes nothing. */
+export declare const accumulateSandboxPart: (current: Accumulated, data: SandboxCommandData) => Accumulated;
+/** Fold one received part into its command's output. */
+export declare const applySandboxPart: (toolCallId: string, data: SandboxCommandData) => void;
+export declare const peekSandboxOutput: (toolCallId: string) => string;
+export declare const subscribeSandboxOutput: (toolCallId: string, listener: () => void) => (() => void);
+export declare const __resetSandboxOutputStoreForTest: () => void;
+export {};

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

@@ -53,12 +53,17 @@ export declare const sandboxDeltaKey: (data: SandboxCommandData) => string;
 /** Sort order for merging deltas: the folded full-text part precedes any live seq. */
 export declare const sandboxDeltaOrder: (data: SandboxCommandData) => number;
 /**
- * Accumulate a sandbox part's streamed deltas into one string across
- * re-renders, applying each delta exactly once by {@link sandboxDeltaKey}.
+ * A command's accumulated output: its streamed deltas folded into one string,
+ * each applied exactly once (`sandbox-output-store.ts`).
+ *
+ * The sum lives in a store keyed by `toolCallId`, so it survives the card
+ * unmounting — a virtualized transcript unmounts every row that scrolls out of
+ * view. Without an id (a part rendered outside a message) the card keeps its
+ * own key and the sum lasts as long as the card.
  *
  * Deliberately `useLayoutEffect` (not `useEffect`): it runs synchronously after
  * DOM mutations, so the flushSync-based test harness observes the accumulated
  * text within the same render flush. In production it's equally correct — it
  * runs before paint, so streamed output never renders a frame late.
  */
-export declare const useSandboxOutputText: (output: SandboxCommandData | null) => string;
+export declare const useSandboxOutputText: (output: SandboxCommandData | null, toolCallId?: string) => string;

package/dist/stream/select-session-usage.d.ts

@@ -31,4 +31,18 @@ export type SessionUsageSummary = {
      */
     readonly contextWindow: ContextWindowData | null;
 };
-export declare const selectSessionUsage: (messages: readonly BelongUIMessage[]) => SessionUsageSummary | null;
+/** The chat's usage total as of a history read (the ledger's sums). */
+export type SessionUsageBaseline = {
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly totalCacheReadInputTokens: number;
+    readonly totalCacheWriteInputTokens: number;
+    readonly turns: number;
+};
+export declare const selectSessionUsage: (messages: readonly BelongUIMessage[], 
+/**
+ * The newest history page's total (`null`: the chat had no usage yet);
+ * `undefined` when there is none to go by — then every part is summed.
+ */
+baseline?: SessionUsageBaseline | null) => SessionUsageSummary | null;

package/dist/stream/tool-call-detail.d.ts

@@ -0,0 +1,16 @@
+import { SandboxCommandData, ToolCallData } from './belong-data-parts.ts';
+export type ToolCallDetail = {
+    readonly command: ToolCallData | null;
+    readonly output: SandboxCommandData | null;
+};
+/** Resolves a call's full parts; rejects when they cannot be read. */
+export type ToolCallDetailLoader = (toolCallId: string) => Promise<ToolCallDetail>;
+/** Null outside a chat transcript (live-only surfaces): cards keep what they have. */
+export declare const ToolCallDetailContext: import('react').Context<ToolCallDetailLoader | null>;
+/** `GET /v1/sessions/:id/tool-calls/:toolCallId` — throws on any failure. */
+export declare const fetchToolCallDetail: (apiBaseUrl: string, sessionId: string, toolCallId: string) => Promise<ToolCallDetail>;
+/**
+ * A summarized card's full parts, loaded once `wanted` (the card is open and
+ * was cut). Null until they arrive — and for good when they cannot be read.
+ */
+export declare const useToolCallDetail: (toolCallId: string | undefined, wanted: boolean) => ToolCallDetail | null;

package/package.json

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