@belonguniverseai/react-sdk 0.6.27 → 0.6.29

package/dist/lib/tab-control-store.d.ts

@@ -0,0 +1,14 @@
+/** Live ownership shared by the composer and the browser-control channel. */
+export type TabOwnership = {
+    readonly term: number;
+    readonly tabId: string;
+};
+export type TabControlSnapshot = {
+    readonly role: "pending" | "leader" | "follower";
+    readonly owner: TabOwnership | null;
+};
+export declare const peekTabControl: (sessionId: string) => TabControlSnapshot;
+export declare const subscribeTabControl: (listener: () => void) => (() => void);
+export declare const publishTabControl: (sessionId: string, snapshot: TabControlSnapshot) => void;
+/** A departing controller must not clear a newer controller's snapshot. */
+export declare const clearTabControl: (sessionId: string, snapshot: TabControlSnapshot) => void;

package/dist/lib/tab-leadership.d.ts

@@ -1,26 +1,9 @@
-/**
- * Multi-tab same-session guard (plan 007 §C5).
- *
- * Two dock tabs open on ONE session can double-send and clobber the persisted
- * `{ runId, lastEventId }` stream state. This module elects a single LEADER
- * tab per session over a `BroadcastChannel` (`belong:session:<sessionId>`);
- * follower tabs banner "open in another tab" and disable the composer.
- *
- * Protocol (all messages Zod-parsed at the perimeter — §4):
- *   - on start every tab broadcasts a `claim` carrying `{ tabId, claimedAtMs }`
- *   - seniority = the EARLIER claim; equal timestamps tie-break on tabId
- *   - the leader heartbeats every ~5 s and re-asserts when a junior claims
- *   - a tab that hears a senior claim/heartbeat becomes follower
- *   - a follower takes over when no senior beat lands for ~12 s, or
- *     immediately on the leader's `release` (stop / pagehide)
- *
- * Feature detection: no `BroadcastChannel` (older WebKit, jsdom) → guard
- * disabled, the tab stays leader, zero behavior change.
- */
+import { TabControlSnapshot } from './tab-control-store.ts';
 export type TabRole = "leader" | "follower";
 export declare const HEARTBEAT_INTERVAL_MS = 5000;
 export declare const TAKEOVER_TIMEOUT_MS = 12000;
-/** The narrow `BroadcastChannel` surface the guard uses (injectable for tests). */
+/** Allow the channel's asynchronous discovery replies to arrive before claiming. */
+export declare const DISCOVERY_INTERVAL_MS = 150;
 export type LeadershipChannel = {
     postMessage: (message: unknown) => void;
     close: () => void;
@@ -30,17 +13,19 @@ export type LeadershipChannel = {
 };
 export type TabLeadershipOptions = {
     readonly sessionId: string;
-    /** Fired on every role CHANGE (the caller assumes "leader" until told). */
-    readonly onRoleChange: (role: TabRole) => void;
+    readonly onChange: (snapshot: TabControlSnapshot) => void;
     readonly heartbeatIntervalMs?: number;
     readonly takeoverTimeoutMs?: number;
-    /** Channel seam; return `null` for "unsupported" (guard disabled). */
+    readonly discoveryIntervalMs?: number;
     readonly createChannel?: (name: string) => LeadershipChannel | null;
-    /** Clock seam (§25). */
     readonly nowMs?: () => number;
+    /** Separate browser realms have separate page identities; injectable in tests. */
+    readonly tabId?: string;
 };
 export type TabLeadershipHandle = {
     readonly stop: () => void;
+    readonly requestControl: () => void;
+    readonly getSnapshot: () => TabControlSnapshot;
 };
 export declare const tabLeadershipChannelName: (sessionId: string) => string;
 export declare const startTabLeadership: (options: TabLeadershipOptions) => TabLeadershipHandle;

package/dist/lib/use-now.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The dock's clock, as one moving value every surface can read.
+ *
+ * Surfaces that say something about time — "Link works until…", "refreshed 2h
+ * ago", "hasn't refreshed since…" — used to capture `new Date()` in a
+ * `useState` initializer. That freezes the comparison at MOUNT: a link that
+ * expired four minutes ago was still offered as live, and an overdue warning
+ * never appeared, even after a refetch brought fresh rows (P2, 2026-09-27
+ * PR #614 deep audit finding 8). Server-side expiry is enforced, so the damage
+ * was a screen that lied, not access — which is exactly the kind of thing a
+ * reader stops trusting the rest of the surface over.
+ *
+ * ONE STORE, not a hook-local interval, and that is the point: every consumer
+ * in a render reads the SAME `Date` object. Two independent clocks a few
+ * milliseconds apart can straddle an expiry and render "live" beside "expired"
+ * in the same paint (§25), which is the bug the frozen `useState` was
+ * originally protecting against — this keeps that guarantee and adds movement.
+ *
+ * One interval for the whole SDK, started by the first subscriber and cleared
+ * by the last: nothing ticks while no surface is on screen, and a store that
+ * has been idle re-reads the wall clock when it starts again rather than
+ * handing out the instant it stopped at.
+ */
+/**
+ * How often the shared instant advances. Half a minute: everything the dock
+ * says about time is minute-scale or coarser ("works until 10:00", "2h ago"),
+ * so this is fine enough that no reader sees a stale answer, and coarse enough
+ * that an idle dock is not re-rendering its surfaces every second.
+ */
+export declare const NOW_TICK_MS = 30000;
+/** The current instant, shared with every other consumer of this render. */
+export declare const useNow: () => Date;

package/dist/lib/use-tab-leadership.d.ts

@@ -1,8 +1,6 @@
 import { TabRole } from './tab-leadership.ts';
-/**
- * @param chatId The mount-time chat id — the persisted server session if one
- *   was already known at mount, else a per-tab `belong-chat-<nanoid>`
- *   placeholder. Used only as the channel key until the real server session id
- *   is persisted.
- */
-export declare const useTabLeadership: (chatId: string) => TabRole;
+/** The persisted server id replaces a new Session's per-tab placeholder. */
+export declare const useTabLeadership: (chatId: string) => {
+    readonly role: TabRole;
+    readonly requestControl: () => void;
+};

package/dist/routes/artifact-detail.d.ts

@@ -0,0 +1,2 @@
+/** /artifacts/:liveArtifactId — one live report and every version it has had. */
+export declare const ArtifactDetailRoute: () => import("react").JSX.Element;

package/dist/routes/artifacts.d.ts

@@ -0,0 +1,2 @@
+/** /artifacts — the live reports the assistant keeps up to date (rail tab). */
+export declare const ArtifactsRoute: () => import("react").JSX.Element;

package/dist/routes/chat/history-merge.d.ts

@@ -0,0 +1,53 @@
+import { BelongUIMessage } from '../../stream/belong-data-parts.ts';
+/**
+ * Merge freshly-fetched server history with whatever is CURRENTLY on screen
+ * (§41 — a history load must never make a message the user is looking at
+ * disappear). Server order is authoritative; any LOCAL-ONLY message — most
+ * often the optimistic turn a concurrent send appended after this fetch
+ * started — survives, appended AFTER the server-ordered messages rather than
+ * lost to the replace.
+ *
+ * What is on screen above the page stays above it: the page lines up on the
+ * first of its rows found on screen (`isRowOf`, so a turn this tab streamed
+ * live lines up too), then back over the earlier rows of the page.
+ *
+ * Dedupe prefers the row id, then the client id the row was sent with. A
+ * message with no id match yet falls back to `(role, flattened text)`. Only
+ * the suffix AFTER the last server-known on-screen message can be local-only.
+ * Within that suffix, an assistant at the same next position as a durable
+ * assistant is the same historical turn with stream-vs-folded whitespace/part
+ * drift, not a new reply. A genuinely live assistant is preserved when
+ * durable history has no assistant at that position yet.
+ */
+export declare const mergeRestoredHistory: (loaded: readonly BelongUIMessage[], onScreen: readonly BelongUIMessage[]) => BelongUIMessage[];
+/**
+ * A kept chat shows every turn it streamed. The server's newest page holds
+ * something it never saw only when it has a user turn that is not on screen:
+ * one sent from another tab or device (the reply to it comes with it).
+ *
+ * Turns are matched one to one, by their row id or the client id they were
+ * sent with, so a prompt repeated elsewhere ("continue", or two files-only
+ * turns with no text) is still a new turn. Text is only a fallback for a row
+ * that carries no client id, matched in order against the turns on screen
+ * that no id accounted for.
+ */
+export declare const hasUnseenTurns: (loaded: readonly BelongUIMessage[], onScreen: readonly BelongUIMessage[]) => boolean;
+/**
+ * #839 — what an IDLE chat shows once the reader comes back to it, given the
+ * newest page read just now: the conversation a reload would show (§41),
+ * without the reload. Null when the page brings nothing the screen lacks, so
+ * a return with nothing new leaves every message — and every card — as it is.
+ *
+ * - The page lines up with the screen (some message on screen is one of its
+ *   rows): the turns added elsewhere are merged in after what is on screen,
+ *   exactly as a mount merges its read (`mergeRestoredHistory`) — no
+ *   duplicates, server order, older pages above it and anything only this
+ *   tab holds kept.
+ * - Nothing on screen is on the page: the conversation moved past a whole
+ *   page while this tab was away, or was cleared elsewhere and went on. What
+ *   is on screen is from before the page, so the page replaces it, as a
+ *   reload would; scrolling up loads what came before it.
+ * - An empty page never empties the screen: a chat cleared in another tab
+ *   reads empty after the next reload, but a return alone wipes nothing.
+ */
+export declare const catchUpTranscript: (page: readonly BelongUIMessage[], onScreen: readonly BelongUIMessage[]) => BelongUIMessage[] | null;

package/dist/routes/chat/history-paging.d.ts

@@ -38,16 +38,35 @@ export declare const withoutOlderPages: <T extends {
 export declare const olderHistoryCursor: (paging: HistoryPaging, messages: readonly {
     readonly id: string;
 }[]) => string | undefined;
+/** Where a walk back over a page stands: page row and on-screen message. */
+export type PageRowPlace = {
+    readonly pageIndex: number;
+    readonly screenIndex: number;
+};
+/** How a page's rows are told apart on screen (see {@link splitOlderPrefix}). */
+export type PageRowMatch<R, T> = {
+    /** `message` IS `row`. Anchors the page on screen. */
+    readonly isRow: (row: R, message: T) => boolean;
+    /** `message`, on screen right above where the page lines up so far, stands
+     * for `row`, an earlier page row; `at` says where both are. */
+    readonly isSameTurn: (row: R, message: T, at: PageRowPlace) => boolean;
+};
 /**
- * What a newest-page re-read must leave alone: the older pages the reader
- * scrolled in ABOVE it. Found by the page's first row id; nothing when the
- * page does not line up with the screen (then it is merged as a whole).
+ * What a newest-page re-read must leave alone: whatever is on screen ABOVE
+ * the page (older pages the reader scrolled in, turns from before it). The
+ * page's first row found on screen anchors it; walking back from there, each
+ * earlier page row takes the message right above while that message stands
+ * for it, and the first one that does not ends the walk: what is above it
+ * stays where it is, even if that shows a message the page also holds. An
+ * extra message reads better than a wrong pairing. Nothing when no row of the
+ * page is on screen (it is merged as a whole). By default rows match by id
+ * only; the chat's merge passes its own rules.
  */
-export declare const splitOlderPrefix: <T extends {
+export declare const splitOlderPrefix: <R extends {
     readonly id: string;
-}>(loaded: readonly {
+}, T extends {
     readonly id: string;
-}[], current: readonly T[]) => {
+}>(loaded: readonly R[], current: readonly T[], match?: PageRowMatch<R, T>) => {
     readonly older: readonly T[];
     readonly rest: readonly T[];
 };

package/dist/routes/chat/transcript-row.d.ts

@@ -29,6 +29,7 @@ export type TranscriptRowWiring = {
     readonly onGoalStartAnother: () => void;
 };
 export type TranscriptRowProps = {
+    readonly onFirstResponseRendered?: ComponentProps<typeof MessageParts>["onFirstResponseRendered"];
     readonly message: BelongUIMessage;
     /** This message's index in the FULL conversation (not the render window). */
     readonly index: number;

package/dist/routes/chat/use-catch-up-on-return.d.ts

@@ -0,0 +1,70 @@
+import { BelongUIMessage } from '../../stream/belong-data-parts.ts';
+import { HistoryPageResult, LoadedHistoryPage } from './history-cache.ts';
+import { useReturnToPage } from './use-return-to-page.ts';
+/** The chat as the catch-up reads it: `@ai-sdk/react`'s `Chat`, live. Its
+ * `messages` array is replaced on every change, so identity says "changed". */
+export type CatchUpChat = {
+    readonly status: "submitted" | "streaming" | "ready" | "error";
+    readonly messages: readonly BelongUIMessage[];
+};
+/** The server's answer about the session's active run. `failed` (network,
+ * non-2xx, a drifted body) is not `none`: only a confirmed `none` is
+ * remembered. */
+export type ActiveRunLookup = {
+    readonly kind: "none";
+} | {
+    readonly kind: "run";
+    readonly runId: string;
+} | {
+    readonly kind: "failed";
+};
+/** The transport as the catch-up reads it. */
+export type CatchUpTransport = {
+    readonly sessionId: string | null;
+    /** A stream, its handshake or its retry loop owns this session. */
+    readonly hasLiveStream: boolean;
+};
+/** What else may own the transcript right now; any of them blocks a step. */
+export type CatchUpBlockers = {
+    /** The workspace does not resolve. */
+    readonly workspaceMissing: boolean;
+    /** The mount's first history read is out. */
+    readonly historyLoading: boolean;
+    /** A resume handshake is under way. */
+    readonly restoringLiveRun: boolean;
+    /** A queued-reply reconciliation is pending. It starts without a render,
+     * so it is asked for when needed rather than passed as a value. */
+    readonly queuedReconciliationPending: () => boolean;
+};
+export declare const useCatchUpOnReturn: (input: {
+    readonly chat: CatchUpChat;
+    readonly transport: CatchUpTransport;
+    /** Checked when a step starts and again after every await, against the
+     * latest render's values, never those of the render that started it. */
+    readonly blockers: CatchUpBlockers;
+    /** Read the newest page from the server now. */
+    readonly readNewestPage: (sessionId: string) => Promise<HistoryPageResult>;
+    /** The read landed after the transcript changed: the page it cached may
+     * predate the change (a clear), so no chat may be painted from it. */
+    readonly onReadOutdated: (sessionId: string) => void;
+    /** Show `caughtUp`, the conversation `page` brought the screen up to. */
+    readonly onCaughtUp: (caughtUp: BelongUIMessage[], page: LoadedHistoryPage) => void;
+    /** Ask the server for the session's active run. */
+    readonly findActiveRun: (sessionId: string) => Promise<ActiveRunLookup>;
+    /** Follow `runId`, the reply to the turn `page` ends on, from its first event. */
+    readonly onFollowRun: (sessionId: string, runId: string, page: LoadedHistoryPage) => void;
+    /** The session this tab has selected now (the stream-state pointer). */
+    readonly selectedSessionId: () => string | null;
+    /** Bumped when the transcript's work loses its owner (leaving the chat, a
+     * clear, a stop): a step started under an older value drops itself. A
+     * clear's POST runs before it empties the screen, so the transcript alone
+     * cannot tell a lookup that the clear is under way. */
+    readonly ownerGeneration: () => number;
+    /** A newly controlling tab catches up even when the page stayed visible. */
+    readonly controlRole?: "leader" | "follower";
+    /** Explicit retries of a control request, including a failed catch-up. */
+    readonly controlRequestId?: number;
+    readonly prepareControl?: (sessionId: string) => Promise<void>;
+    readonly onControlReady?: (ready: boolean) => void;
+    readonly returnOptions?: Parameters<typeof useReturnToPage>[1];
+}) => void;

package/dist/routes/chat/use-return-to-page.d.ts

@@ -0,0 +1,7 @@
+/** Two return signals closer together than this are one return. */
+export declare const RETURN_MIN_GAP_MS = 2000;
+export declare const useReturnToPage: (onReturn: () => void, options?: {
+    readonly minGapMs?: number;
+    /** Clock seam (§25). */
+    readonly nowMs?: () => number;
+}) => void;

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

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { ChatTransport, UIMessageChunk } from 'ai';
+import { FirstResponseObservation, FirstResponseSample } from '../infrastructure/telemetry/first-response-timing.ts';
+import { AUTH_EXPIRED_ERROR_PREFIX } from '../api/auth-errors.ts';
 import { BelongUIMessage, WireStreamPart } from './belong-data-parts.ts';
 declare const cancelRunResponseSchema: z.ZodObject<{
     recalledMessages: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -22,9 +24,9 @@ export declare const choiceAnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export declare const choiceStateSchema: z.ZodEnum<{
     cancelled: "cancelled";
     pending: "pending";
-    detached: "detached";
     dismissed: "dismissed";
     answered: "answered";
+    detached: "detached";
 }>;
 /**
  * The wire/stored part union. Exported so the history loader (chat.tsx) can
@@ -37,6 +39,14 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     type: z.ZodLiteral<"text">;
     id: z.ZodString;
     text: z.ZodString;
+    responsePhase: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        phase: z.ZodEnum<{
+            acknowledgment: "acknowledgment";
+            main: "main";
+        }>;
+        sourceMessageIds: z.ZodArray<z.ZodString>;
+        replyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-reasoning">;
     id: z.ZodString;
@@ -250,6 +260,7 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
                 count: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        weightedHundredths: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-choice-request">;
@@ -259,9 +270,9 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         state: z.ZodEnum<{
             cancelled: "cancelled";
             pending: "pending";
-            detached: "detached";
             dismissed: "dismissed";
             answered: "answered";
+            detached: "detached";
         }>;
         questions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -354,9 +365,9 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             at: z.ZodString;
         }, z.core.$strip>>>;
         runway: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            long: "long";
             quick: "quick";
             normal: "normal";
-            long: "long";
         }>>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
@@ -367,15 +378,17 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         why: z.ZodString;
         criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runway: z.ZodOptional<z.ZodEnum<{
+            long: "long";
             quick: "quick";
             normal: "normal";
-            long: "long";
         }>>;
     }, z.core.$strip>;
 }, z.core.$strip>], "type">;
-/** A request was 401'd twice (once with a freshly re-read token): the host
- * session is expired — the dock must surface re-auth, not retry forever. */
-export declare const AUTH_EXPIRED_ERROR_PREFIX = "auth_expired:";
+/** A request was 401'd twice (once with a freshly re-read token), or no usable
+ * token could be had at all (`BelongAuthUnavailableError`): the host session is
+ * expired — the dock must surface re-auth, not retry forever. Defined by the
+ * request layer, which raises it too; re-exported here for chat.tsx. */
+export { AUTH_EXPIRED_ERROR_PREFIX };
 /** The SSE reconnect loop exhausted its attempt budget without the backend
  * delivering a single event — the service is unreachable. */
 export declare const BACKEND_UNAVAILABLE_ERROR_PREFIX = "backend_unavailable:";
@@ -434,6 +447,10 @@ export declare const RESUME_GRACE_MS = 120000;
  * across tests in the same file otherwise). */
 export declare const __resetLiveStreamRegistryForTest: () => void;
 export type BelongChatTransportOptions = {
+    readonly firstResponseTiming?: {
+        readonly nowMs: () => number;
+        readonly report: (sample: FirstResponseSample) => void;
+    };
     /** Belong cloud base URL, e.g. `http://localhost:8787`. */
     readonly apiBaseUrl: string;
     /**
@@ -469,6 +486,10 @@ export type BelongChatTransportOptions = {
     readonly foregroundGeneration?: number;
 };
 export type StreamContext = {
+    textPhaseKey?: string;
+    firstResponseObservations?: (phase: NonNullable<Extract<WireStreamPart, {
+        type: "text";
+    }>["responsePhase"]>) => readonly FirstResponseObservation[];
     modelActivity?: {
         id: string;
         stepIndex: number;
@@ -572,8 +593,17 @@ export declare class BelongChatTransport implements ChatTransport<BelongUIMessag
      * unaccepted stop.
      */
     stopSubagent: (runId: string, subagentId: string) => Promise<void>;
+    beginFirstResponse: (clientMessageId: string) => void;
+    cancelFirstResponse: (clientMessageId: string) => void;
+    acceptFirstResponse: (input: {
+        sessionId: string;
+        runId: string;
+        clientMessageId: string;
+        messageId: string;
+        idempotent: boolean;
+    }) => void;
+    observeFirstResponseRendered: (observation: FirstResponseObservation) => void;
     sendMessages: ChatTransport<BelongUIMessage>["sendMessages"];
     reconnectToStream: ChatTransport<BelongUIMessage>["reconnectToStream"];
 }
 export declare const wireToUiChunks: (part: WireStreamPart, ctx: StreamContext) => readonly UIMessageChunk[];
-export {};

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

@@ -310,6 +310,11 @@ export type UsageData = {
     readonly autoCompactThresholdChars: number;
     /** The detailed context-window breakdown (own-loop runtimes only). */
     readonly contextWindow?: ContextWindowData | undefined;
+    /**
+     * Plan 018 — the turn in WEIGHTED tokens, in hundredths: the one unit the
+     * dock shows users. Absent on a turn from a cloud that predates it.
+     */
+    readonly weightedHundredths?: number | undefined;
 };
 /**
  * Goal Mode M6 — a goal the agent OFFERED. Nothing exists on the backend
@@ -367,6 +372,11 @@ export type BelongUIMessage = UIMessage<BelongMessageMetadata, BelongDataParts>;
  * chunks yet — the transport translates this into `UIMessageChunk`.
  */
 export type WireTextPart = {
+    readonly responsePhase?: {
+        readonly phase: "acknowledgment" | "main";
+        readonly sourceMessageIds: readonly string[];
+        readonly replyKey?: string | undefined;
+    } | undefined;
     readonly type: "text";
     readonly id: string;
     readonly text: string;

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

@@ -4,7 +4,7 @@ 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;
+export declare const useDispatchOnce: (key: string | undefined, effect: () => void, deps: readonly unknown[], canDispatch?: () => boolean) => 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. */

package/dist/stream/message-parts.d.ts

@@ -1,4 +1,5 @@
 import { BelongMessagePart, PartRendererProps } from './ai-sdk-part-renderers.tsx';
+import { FirstResponseObservation } from '../infrastructure/telemetry/first-response-timing.ts';
 /**
  * The parts a message is INDEXED from (spec deviation 16). File parts render as
  * chips above the message and never reach a render group, and dropping one
@@ -10,7 +11,7 @@ import { BelongMessagePart, PartRendererProps } from './ai-sdk-part-renderers.ts
  * is the same list.
  */
 export declare const indexableMessageParts: (parts: readonly BelongMessagePart[]) => readonly BelongMessagePart[];
-export declare const MessageParts: ({ parts, streaming, historical, onContinueConnector, onExecutePlan, onFollowContinuation, partProps, }: {
+export declare const MessageParts: ({ parts, streaming, historical, onContinueConnector, onExecutePlan, onFollowContinuation, partProps, onFirstResponseRendered, }: {
     /** The message's parts, file parts already removed (they render as chips). */
     readonly parts: readonly BelongMessagePart[];
     /** This message is the one a run is streaming into right now. */
@@ -39,4 +40,5 @@ export declare const MessageParts: ({ parts, streaming, historical, onContinueCo
      * the named props still wins. Absent = no goal wiring (stories, tests).
      */
     readonly partProps?: ((part: BelongMessagePart) => Partial<PartRendererProps>) | undefined;
+    readonly onFirstResponseRendered?: ((observation: FirstResponseObservation) => void) | undefined;
 }) => import("react").JSX.Element;

package/dist/stream/queued-message-outbox.d.ts

@@ -15,6 +15,12 @@ declare const queuedMessageOutboxEntrySchema: z.ZodObject<{
     runtime: z.ZodOptional<z.ZodString>;
     llmProvider: z.ZodOptional<z.ZodString>;
     llmModel: z.ZodOptional<z.ZodString>;
+    responseMode: z.ZodOptional<z.ZodEnum<{
+        balanced: "balanced";
+        fast: "fast";
+        smart: "smart";
+    }>>;
+    pageLabel: z.ZodOptional<z.ZodString>;
     workspaceExternalId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type QueuedMessageOutboxEntry = Readonly<z.infer<typeof queuedMessageOutboxEntrySchema>>;

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

@@ -30,6 +30,13 @@ export type SessionUsageSummary = {
      * panel then falls back to the session-usage view.
      */
     readonly contextWindow: ContextWindowData | null;
+    /**
+     * Plan 018 — the chat in WEIGHTED tokens, in hundredths: the one figure the
+     * panel shows users (round once with `Math.round(x / 100)`). `null` when any
+     * turn folded here, or the history baseline, predates the field — an honest
+     * "unknown" rather than a total that silently skips turns.
+     */
+    readonly totalWeightedHundredths: number | null;
 };
 /** The chat's usage total as of a history read (the ledger's sums). */
 export type SessionUsageBaseline = {
@@ -39,6 +46,8 @@ export type SessionUsageBaseline = {
     readonly totalCacheReadInputTokens: number;
     readonly totalCacheWriteInputTokens: number;
     readonly turns: number;
+    /** Plan 018 — absent from a cloud that predates weighted tokens. */
+    readonly totalWeightedHundredths?: number | undefined;
 };
 export declare const selectSessionUsage: (messages: readonly BelongUIMessage[], 
 /**

package/dist/stream/session-control-context.d.ts

@@ -0,0 +1,7 @@
+export type SessionControl = {
+    readonly readOnly: boolean;
+    /** Read live ownership again at the moment a side effect starts. */
+    readonly canControl: () => boolean;
+};
+export declare const SessionControlContext: import('react').Context<SessionControl>;
+export declare const useSessionControl: () => SessionControl;

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

@@ -6,6 +6,10 @@
  * DTOs. Kept as an explicit local mirror (not inferred from AppType) so the CSV
  * column contract is readable in one place.
  *
+ * Plan 018 — tokens appear in WEIGHTED tokens only, the one unit users see; the
+ * raw input / output split is no longer exported. The weighted fields are
+ * optional here because an older cloud does not send them (an empty cell).
+ *
  * 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.
@@ -13,14 +17,10 @@
 export type SessionStatsTurn = {
     readonly turn: number;
     readonly at: string;
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly totalTokens: number;
+    readonly weightedTokens?: number;
 };
 export type SessionStatsDetail = {
-    readonly totalInputTokens: number;
-    readonly totalOutputTokens: number;
-    readonly totalTokens: number;
+    readonly totalWeightedTokens?: number;
     readonly turns: number;
     readonly runningMs: number;
     readonly toolCalls: number;
@@ -32,9 +32,7 @@ export type SessionStatsSummaryRow = {
     readonly title: string | null;
     readonly createdAt: string;
     readonly updatedAt: string;
-    readonly totalInputTokens: number;
-    readonly totalOutputTokens: number;
-    readonly totalTokens: number;
+    readonly totalWeightedTokens?: number;
     readonly turns: number;
     readonly runningMs: number;
     readonly toolCalls: number;

package/dist/types/public.d.ts

@@ -114,17 +114,17 @@ export type PartialBelongTheme = {
     /** Per-locale welcome-copy override (BEL-135). */
     readonly copy?: DockCopyOverride;
 };
-/** Built-in theme presets selectable via `belong.applyPreset(name)`. */
-export type PresetName = "belong" | "simetrik" | "custom";
+/** Theme styles. `tenant` restores the latest published tenant default. */
+export type PresetName = "tenant" | "belong" | "simetrik" | "custom";
 /** UI languages the dock ships. `setLocale` / `init({ locale })` accept these. */
 export type BelongLocale = "en" | "es" | "pt" | "it";
 export type BelongInitInput = {
     /** Belong cloud base URL, e.g. `https://api.belong.host` or `http://localhost:8787`. */
     readonly apiBaseUrl: string;
     /**
-     * Public tenant slug (BEL-129, multi-tenant deployments). Used for
+     * Public tenant ID or slug (multi-tenant deployments). Used for
      * boot-time, unauthenticated surfaces only — the theme fetch adds
-     * `?tenant=<slug>` and every request carries it as `X-Belong-Tenant`
+     * `?tenant=<id-or-slug>` and every request carries it as `X-Belong-Tenant`
      * (observability). Authenticated routes derive the tenant from the JWT;
      * this value can never escalate. Omit on single-tenant deployments.
      */
@@ -166,9 +166,11 @@ export type BelongInitInput = {
     };
     /**
      * What page the user is on, shown as "Looking at ‹label›" before the first
-     * message. Omit `label` to use the browser tab title (`document.title`,
+     * message and in the composer's page chip, and SENT with every message so
+     * the agent can resolve "this page" (the label only, never the page's
+     * contents). Omit `label` to use the browser tab title (`document.title`,
      * tracked live so SPA navigation updates the line); pass
-     * `fromDocumentTitle: false` to show nothing unless a label is given.
+     * `fromDocumentTitle: false` to show and send nothing unless a label is given.
      * A re-`init` replaces this config wholesale: omitting `pageContext` clears
      * a previously seeded `label` and restores the tab-title fallback.
      * `belong.setPageContext` overrides both at runtime and SURVIVES a later
@@ -182,7 +184,12 @@ export type BelongInitInput = {
     readonly theme?: PartialBelongTheme;
     /** Optional voice config (push-to-talk + read-aloud). */
     readonly voice?: {
-        /** Hold-to-talk key as a `KeyboardEvent.code`. Default `"ControlLeft"`. */
+        /**
+         * Default hold-to-talk key as a `KeyboardEvent.code`: one of
+         * `"ControlRight"`, `"ControlLeft"`, `"AltRight"`, `"AltLeft"`, `"F2"`,
+         * `"F8"`, `"F9"`; any other code is ignored. Default: none — each user
+         * picks a key (or keeps it off) in Settings → Voice, and their choice wins.
+         */
         readonly pushToTalkKey?: string;
         /** Auto-read assistant replies aloud (ElevenLabs TTS). Default `true`. */
         readonly autoplayTts?: boolean;
@@ -324,8 +331,8 @@ export type BelongGlobal = {
         readonly displayName?: string | null;
     } | null) => void;
     /**
-     * Set the page label shown before the first message (wins over
-     * `init({ pageContext })` and the tab title). `null` drops the override.
+     * Set the page label shown in the dock and sent with each message (wins
+     * over `init({ pageContext })` and the tab title). `null` drops the override.
      */
     readonly setPageContext: (label: string | null) => void;
     readonly setTheme: (theme: PartialBelongTheme) => void;