@belonguniverseai/react-sdk 0.6.21 → 0.6.23

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

@@ -22,9 +22,9 @@ export declare const choiceAnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export declare const choiceStateSchema: z.ZodEnum<{
     detached: "detached";
     pending: "pending";
+    cancelled: "cancelled";
     dismissed: "dismissed";
     answered: "answered";
-    cancelled: "cancelled";
 }>;
 /**
  * The wire/stored part union. Exported so the history loader (chat.tsx) can
@@ -129,6 +129,22 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         stepsUsed: z.ZodOptional<z.ZodNumber>;
         summary: z.ZodOptional<z.ZodString>;
         timedOut: z.ZodOptional<z.ZodBoolean>;
+        outcome: z.ZodCatch<z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            ok: "ok";
+            timeout: "timeout";
+            stopped: "stopped";
+            stalled: "stalled";
+            interrupted: "interrupted";
+        }>>>;
+        queued: z.ZodOptional<z.ZodBoolean>;
+        startedAt: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        tokensCount: z.ZodOptional<z.ZodNumber>;
+        waveId: z.ZodOptional<z.ZodString>;
+        groupLabel: z.ZodOptional<z.ZodString>;
+        planStepId: z.ZodOptional<z.ZodString>;
+        stoppable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-sandbox-command">;
@@ -183,6 +199,17 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         title: z.ZodString;
         mimeType: z.ZodString;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"data-model-activity">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        state: z.ZodEnum<{
+            waiting: "waiting";
+            idle: "idle";
+        }>;
+        stepIndex: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-status">;
     id: z.ZodString;
@@ -228,9 +255,9 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         state: z.ZodEnum<{
             detached: "detached";
             pending: "pending";
+            cancelled: "cancelled";
             dismissed: "dismissed";
             answered: "answered";
-            cancelled: "cancelled";
         }>;
         questions: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -255,6 +282,92 @@ export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         }, z.core.$strip>], "kind">>>;
         reply: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"data-goal">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        goalId: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            paused: "paused";
+            clarifying: "clarifying";
+            completion_claimed: "completion_claimed";
+            deferred: "deferred";
+            waiting_for_user: "waiting_for_user";
+            waiting_for_approval: "waiting_for_approval";
+            waiting_for_ui_action: "waiting_for_ui_action";
+            blocked: "blocked";
+            budget_limited: "budget_limited";
+            complete: "complete";
+            cleared: "cleared";
+        }>;
+        statusReason: z.ZodNullable<z.ZodString>;
+        objective: z.ZodString;
+        successCriteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+            status: z.ZodEnum<{
+                open: "open";
+                met: "met";
+            }>;
+            evidence: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+        constraints: z.ZodArray<z.ZodString>;
+        tokensUsed: z.ZodNumber;
+        tokenBudget: z.ZodNumber;
+        turnsUsed: z.ZodNumber;
+        maxTurns: z.ZodNumber;
+        activeSeconds: z.ZodNumber;
+        maxActiveSeconds: z.ZodNumber;
+        lastProgressNote: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodString;
+        startedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        originatingClientMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        clarifyMaxQuestions: z.ZodOptional<z.ZodNumber>;
+        judgeFeedback: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        judgeRejections: z.ZodOptional<z.ZodNumber>;
+        clarifyingTurns: z.ZodOptional<z.ZodNumber>;
+        resumeAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        journal: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            seq: z.ZodNumber;
+            kind: z.ZodString;
+            actor: z.ZodString;
+            toStatus: z.ZodNullable<z.ZodEnum<{
+                active: "active";
+                paused: "paused";
+                clarifying: "clarifying";
+                completion_claimed: "completion_claimed";
+                deferred: "deferred";
+                waiting_for_user: "waiting_for_user";
+                waiting_for_approval: "waiting_for_approval";
+                waiting_for_ui_action: "waiting_for_ui_action";
+                blocked: "blocked";
+                budget_limited: "budget_limited";
+                complete: "complete";
+                cleared: "cleared";
+            }>>;
+            note: z.ZodNullable<z.ZodString>;
+            at: z.ZodString;
+        }, z.core.$strip>>>;
+        runway: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            quick: "quick";
+            normal: "normal";
+            long: "long";
+        }>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"data-goal-proposal">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        objective: z.ZodString;
+        why: z.ZodString;
+        criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        runway: z.ZodOptional<z.ZodEnum<{
+            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. */
@@ -262,6 +375,22 @@ export declare const AUTH_EXPIRED_ERROR_PREFIX = "auth_expired:";
 /** 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:";
+/**
+ * `POST /v1/sessions/:id/messages` refused the send. Carries the raw status
+ * + body — the same shape as `AttachmentUploadError`'s precedent
+ * (`chat-upload.ts`) — so a caller can recognize a SPECIFIC refusal (e.g. the
+ * goal-cap 429s, `goal_cap_user` / `goal_cap_tenant`) instead of pattern-
+ * matching the thrown `Error`'s message string. Deviation 11: this is the
+ * minimum honest channel — the send path had no error surface at all before
+ * this, so `goal_exists` and the new caps were previously invisible in the
+ * dock. The message text is unchanged from the plain `Error` this replaces,
+ * so every existing `.rejects.toThrow(...)` assertion still passes.
+ */
+export declare class PostMessageError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
 /** First reconnect delay — identical to the historic fixed delay, so the
  * BEL-48 mid-run clean-EOF reconnect regains the stream just as fast. */
 export declare const RECONNECT_BASE_DELAY_MS = 1000;
@@ -336,6 +465,10 @@ export type BelongChatTransportOptions = {
     readonly foregroundGeneration?: number;
 };
 export type StreamContext = {
+    modelActivity?: {
+        id: string;
+        stepIndex: number;
+    };
     /** Stable id we emit on every `text-delta`. Null when no text run is open. */
     textRunId: string | null;
     /**
@@ -391,6 +524,28 @@ export declare class BelongChatTransport implements ChatTransport<BelongUIMessag
      * best-effort.
      */
     cancelRun: (runId: string) => Promise<readonly RecalledQueuedMessage[]>;
+    /**
+     * Spec 2026-09-16 §1.4/§3.5 — ask belong-cloud to stop ONE subagent of a
+     * live run (`POST /v1/runs/:runId/subagents/:subagentId/stop`, 202
+     * `{ status: "stop_requested" }`). Modelled on `cancelRun`: same auth
+     * headers, same transient retries (the route is idempotent, §18). It changes
+     * nothing locally — the lane flips only when the `subagent_finished` part
+     * arrives — and the stop is best-effort BY DESIGN (spec §5: the backend
+     * swallows delivery failures too), so the dock promises nothing here.
+     *
+     * The two failure families are deliberately NOT collapsed into one. A 404
+     * (`subagent_not_found`, or an API that has not deployed the route yet) and a
+     * 409 (`subagent_not_running` — it finished while the user was clicking) are
+     * ordinary things that happen to a working product: the lane simply never
+     * flips and nothing is said. A 401 is something else entirely — the host
+     * session going stale mid-click — so it takes the same §C3 treatment every
+     * other authed call in this transport gets: one FORCED token rotation and one
+     * retry, which makes a merely stale token still stop the subagent. Only a
+     * SECOND 401 is a genuinely expired session, and that is reported as
+     * `auth_expired` (the evidence behind the dock's re-auth surface), never as an
+     * unaccepted stop.
+     */
+    stopSubagent: (runId: string, subagentId: string) => Promise<void>;
     sendMessages: ChatTransport<BelongUIMessage>["sendMessages"];
     reconnectToStream: ChatTransport<BelongUIMessage>["reconnectToStream"];
 }

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

@@ -1,5 +1,7 @@
 import { UIMessage } from 'ai';
 import { BelongMessageMetadata } from './message-metadata.ts';
+import { GoalView } from '../api/goals.ts';
+import { GoalRunwayPreset } from '../embed/goal-runway.ts';
 /**
  * F2 — per-step execution status. Optional: absent means `pending`
  * (back-compat with plans proposed before F2 and the initial propose). The
@@ -20,6 +22,11 @@ export type SandboxCommandState = "started" | "output" | "completed" | "failed";
 export type SandboxStream = "stdout" | "stderr";
 export type UiActionState = "requested" | "completed" | "failed";
 export type RunStatusKind = "continuing" | "completed" | "cancelled" | "failed" | "throttled";
+export type ModelActivityData = {
+    readonly state: "waiting" | "idle";
+    readonly stepIndex: number;
+    readonly elapsedMs: number;
+};
 export type ReasoningData = {
     readonly delta: string;
 };
@@ -137,8 +144,8 @@ export type ToolCallData = {
     /**
      * BEL-199 — the `data-subagent` part id this call ran INSIDE. Absent on every
      * main-loop call (and on every part emitted before BEL-199). The expanded
-     * activity group chips a matching item with a muted "via <name>" —
-     * attribution, not nesting.
+     * activity group nests a matching item under that subagent's lane when the
+     * lane is in the same group; otherwise it stays a flat item (§41).
      */
     readonly subagentId?: string | undefined;
 };
@@ -146,15 +153,22 @@ export type ToolCallData = {
  * BEL-199 — one delegated subagent. `running → finished | failed`, one part per
  * subagent, reconciled by id like every other lifecycle part.
  *
- * It renders as an ACTIVITY ITEM: one thin line INSIDE the §42 collapsed
- * activity line, never a card beside it. A failed subagent carries no
+ * It renders as an inspectable ACTIVITY ITEM inside the §42 collapsed
+ * activity group, never a card beside it. A failed subagent carries no
  * `ToolErrorSeverity` — deliberately, so it can never reach the collapsed line:
  * the parent agent reads the failure in its tool result and recovers, and
  * surfacing it would read as breakage. Nothing about it is ever red.
  */
 export type SubagentState = "running" | "finished" | "failed";
+/**
+ * Spec 2026-09-16 §1.2 — how a subagent ended. An optional FIELD beside
+ * `state` (never new `state` values: older docks strict-parse that enum). The
+ * dock parses it leniently, so a future value degrades to "absent" and the
+ * outcome is derived from `state` / `timedOut` instead.
+ */
+export type SubagentOutcome = "ok" | "error" | "timeout" | "stopped" | "stalled" | "interrupted";
 export type SubagentData = {
-    /** Registry name, e.g. "general-purpose" — the "via <name>" chip's text. */
+    /** Registry name, e.g. "general-purpose". Operator vocabulary: never rendered (§42). */
     readonly name: string;
     /** The model's own task label; this is what the line shows. */
     readonly description: string;
@@ -169,6 +183,23 @@ export type SubagentData = {
      * server prose.
      */
     readonly timedOut?: boolean | undefined;
+    readonly outcome?: SubagentOutcome | undefined;
+    /** Waiting for a concurrency slot; re-emitted without it (same id) once started. */
+    readonly queued?: boolean | undefined;
+    /** ISO instant the subagent actually started; the elapsed timer's origin (§41). */
+    readonly startedAt?: string | undefined;
+    /** Integer ms from `startedAt` to finish; 0 when it never left the queue. */
+    readonly durationMs?: number | undefined;
+    /** Operator-only (insights). The dock never renders token counts (§42). */
+    readonly tokensCount?: number | undefined;
+    /** Subagents launched together share one wave id. */
+    readonly waveId?: string | undefined;
+    /** Model-provided name for the wave's work, e.g. "Auditing datasets". */
+    readonly groupLabel?: string | undefined;
+    /** The single plan step in progress at launch — a wave-label fallback. */
+    readonly planStepId?: string | undefined;
+    /** Only the own loop can stop a subagent; gates the dock's Stop. Never set once finished. */
+    readonly stoppable?: boolean | undefined;
 };
 export type SandboxCommandData = {
     readonly state: SandboxCommandState;
@@ -267,6 +298,20 @@ export type UsageData = {
     /** The detailed context-window breakdown (own-loop runtimes only). */
     readonly contextWindow?: ContextWindowData | undefined;
 };
+/**
+ * Goal Mode M6 — a goal the agent OFFERED. Nothing exists on the backend
+ * until the user confirms; this part is the offer itself.
+ *
+ * Task 17 — `criteria`/`runway` are optional so a pre-Task-17 stored part
+ * still parses (§4): when present, Start skips the interview the same way
+ * the compose sheet's "Done when…" field does.
+ */
+export type GoalProposalData = {
+    readonly objective: string;
+    readonly why: string;
+    readonly criteria?: readonly string[] | undefined;
+    readonly runway?: GoalRunwayPreset | undefined;
+};
 /**
  * Single source of truth for Belong's custom data parts. The record
  * keys (`reasoning`, `plan`, …) become the part-type suffix:
@@ -274,6 +319,7 @@ export type UsageData = {
  * `data-reasoning` part.
  */
 export type BelongDataParts = {
+    "model-activity": ModelActivityData;
     reasoning: ReasoningData;
     plan: PlanData;
     "approval-request": ApprovalRequestData;
@@ -289,6 +335,10 @@ export type BelongDataParts = {
     status: StatusData;
     /** F3 — context/cost meter. Additive; absent on old sessions. */
     usage: UsageData;
+    /** Goal Mode M1 — the session's live long-running-goal snapshot. */
+    goal: GoalView;
+    /** Goal Mode M6 — a goal the agent offered via `propose_goal`. */
+    "goal-proposal": GoalProposalData;
 };
 /**
  * The concrete `UIMessage` shape the chat surface and transport speak.
@@ -313,5 +363,5 @@ export type WireDataPart<NAME extends keyof BelongDataParts> = {
     readonly id: string;
     readonly data: BelongDataParts[NAME];
 };
-export type WireStreamPart = WireTextPart | WireDataPart<"reasoning"> | WireDataPart<"plan"> | WireDataPart<"approval-request"> | WireDataPart<"choice-request"> | WireDataPart<"tool-call"> | WireDataPart<"subagent"> | WireDataPart<"sandbox-command"> | WireDataPart<"ui-action"> | WireDataPart<"cli-reconnect"> | WireDataPart<"navigation"> | WireDataPart<"artifact"> | WireDataPart<"status"> | WireDataPart<"usage">;
+export type WireStreamPart = WireTextPart | WireDataPart<"model-activity"> | WireDataPart<"reasoning"> | WireDataPart<"plan"> | WireDataPart<"approval-request"> | WireDataPart<"choice-request"> | WireDataPart<"tool-call"> | WireDataPart<"subagent"> | WireDataPart<"sandbox-command"> | WireDataPart<"ui-action"> | WireDataPart<"cli-reconnect"> | WireDataPart<"navigation"> | WireDataPart<"artifact"> | WireDataPart<"status"> | WireDataPart<"usage"> | WireDataPart<"goal"> | WireDataPart<"goal-proposal">;
 export type WireStreamPartType = WireStreamPart["type"];

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

@@ -0,0 +1,43 @@
+import { GoalView } from '../api/goals.ts';
+export type GoalState = {
+    readonly sessionId: string;
+    readonly goal: GoalView;
+} | null;
+/**
+ * Whether `next` should replace `current` in the store. Accepts when: the
+ * store is empty; `next` is `null` (an explicit clear always wins); the
+ * session changed; or `next`'s goal is strictly newer by `updatedAt`.
+ *
+ * On an EQUAL `updatedAt` several tie-breaks still accept: a higher
+ * `turnsUsed`, a different `status`, a different `objective`/`maxTurns`/
+ * `tokenBudget`, or a different `tokensUsed`/`activeSeconds`. Postgres stamps
+ * `updated_at` per write and the dock's two writers can observe two different
+ * rows carrying the same timestamp (a goal turn and its status flip inside
+ * one drain iteration, or a timestamp truncated to the same millisecond on
+ * the wire); rejecting those pinned the pill to the older of two genuinely
+ * different states. The objective/turns/budget tie-break covers `/goal edit`:
+ * an edit bumps `updatedAt` but leaves `status` and `turnsUsed` untouched, so
+ * without it a same-millisecond edit would be indistinguishable from a no-op
+ * and get dropped. The tokensUsed/activeSeconds tie-break covers M3
+ * accounting (`recordTurnOutcome`): it writes counters on every turn without
+ * necessarily changing `status` or `turnsUsed` (a mid-drain accounting write
+ * followed by a same-millisecond read). Only a view equal on all nine —
+ * timestamp, turns, status, objective, maxTurns, tokenBudget, tokensUsed,
+ * activeSeconds and resumeAt — is rejected as a no-op.
+ *
+ * The resumeAt tie-break covers M5: a goal deferred again to a NEW time
+ * (the backoff doubling) changes neither `status` nor `turnsUsed`, so a
+ * same-millisecond republish would otherwise pin the pill to the old time.
+ *
+ * The journal-length tie-break covers M6: a repo-backed view that appended a
+ * History entry (a progress note, a status transition already covered
+ * above) without otherwise changing any of the other tie-break fields would
+ * be a no-op by the old rule, dropping the fresher History off the panel.
+ */
+export declare const isNewerGoalState: (current: GoalState, next: GoalState) => boolean;
+export declare const publishGoalState: (next: GoalState) => void;
+export declare const peekGoalState: () => GoalState;
+export declare const subscribeGoalState: (listener: () => void) => (() => void);
+export declare const useGoalState: () => GoalState;
+export declare const publishGoalFetchSettled: (next: boolean) => void;
+export declare const useGoalFetchSettled: () => boolean;

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

@@ -11,5 +11,6 @@ export declare const belongMessageMetadataSchema: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodString>;
     skill: z.ZodOptional<z.ZodString>;
     fromHistory: z.ZodOptional<z.ZodBoolean>;
+    clientMessageId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type BelongMessageMetadata = z.infer<typeof belongMessageMetadataSchema>;

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

@@ -0,0 +1,42 @@
+import { BelongMessagePart, PartRendererProps } from './ai-sdk-part-renderers.tsx';
+/**
+ * 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
+ * shifts every later group's key — so the chat here and the fullscreen pane
+ * (`collectSubagentWaves`) must drop them the same way, or the two would draw
+ * the same message's lanes with different step keys.
+ *
+ * Idempotent: ChatRoute already filters before it renders, and filtering twice
+ * is the same list.
+ */
+export declare const indexableMessageParts: (parts: readonly BelongMessagePart[]) => readonly BelongMessagePart[];
+export declare const MessageParts: ({ parts, streaming, historical, onContinueConnector, onExecutePlan, onFollowContinuation, partProps, }: {
+    /** 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. */
+    readonly streaming: boolean;
+    /**
+     * Restored history must render settled, never re-fire the dispatch
+     * renderers' one-shot side effects (reconnect grant mint, host navigation,
+     * ui-action result POST).
+     */
+    readonly historical: boolean;
+    readonly onContinueConnector?: PartRendererProps["onContinueConnector"];
+    /** The plan card's "Run this plan" CTA — omitted while a run streams. */
+    readonly onExecutePlan?: PartRendererProps["onExecutePlan"];
+    /**
+     * An agent-raised plan card's decision: the server posts it as the user's
+     * message and names the turn it started, which the chat must then follow
+     * live. Without it the card settles and the run it began never appears.
+     */
+    readonly onFollowContinuation?: PartRendererProps["onFollowContinuation"];
+    /**
+     * Extra `PartRenderer` props computed PER PART — the goal surfaces' wiring
+     * (`routes/chat/part-renderer-extra-props.ts`), whose `renderGoalSetCard`
+     * gate depends on the specific part's id, so it cannot be hoisted to one
+     * value per message. Spread AFTER the props above, so a caller that routes
+     * `onContinueConnector` / `onExecutePlan` through here rather than through
+     * the named props still wins. Absent = no goal wiring (stories, tests).
+     */
+    readonly partProps?: ((part: BelongMessagePart) => Partial<PartRendererProps>) | undefined;
+}) => import("react").JSX.Element;

package/dist/stream/select-goal-set-part-id.d.ts

@@ -0,0 +1,2 @@
+import { BelongUIMessage } from './belong-data-parts.ts';
+export declare const selectGoalSetPartIds: (messages: readonly BelongUIMessage[]) => ReadonlySet<string>;

package/dist/stream/select-latest-goal.d.ts

@@ -0,0 +1,13 @@
+import { BelongUIMessage } from './belong-data-parts.ts';
+import { GoalView } from '../api/goals.ts';
+export declare const selectLatestGoal: (messages: readonly BelongUIMessage[]) => GoalView | null;
+/**
+ * Task 13 — the completion card's cue for whether "Get the files" has
+ * anything to show: every `file` (user attachment) or `data-artifact`
+ * (agent-published) part across the WHOLE session, not just the goal's own
+ * turns — the objective can reference something attached earlier in the same
+ * conversation. Counts part instances rather than deduping by id, so a
+ * re-emitted historical part only ever makes the button MORE likely to show,
+ * never hides files that were actually produced.
+ */
+export declare const countSessionFiles: (messages: readonly BelongUIMessage[]) => number;

package/dist/stream/subagent-controls-store.d.ts

@@ -0,0 +1,20 @@
+import { SubagentLane } from './subagent-lanes-model.ts';
+export type PublishedSubagentWave = {
+    readonly waveId: string;
+    /** Arrival order; readers sort with `orderLanes`. */
+    readonly lanes: readonly SubagentLane[];
+    /** In the last message while a run is active — the only time Stop applies. */
+    readonly live: boolean;
+};
+export type SubagentControlsState = {
+    /** The active run of this chat, or null when none (Stop hides). */
+    readonly runId: string | null;
+    readonly stop: (subagentId: string) => Promise<void>;
+    /** Stops every stoppable running or queued lane of the wave, in parallel (§15). */
+    readonly stopAll: (waveId: string) => Promise<void>;
+    readonly waves: readonly PublishedSubagentWave[];
+};
+export declare const publishSubagentControls: (next: SubagentControlsState | null) => void;
+export declare const peekSubagentControls: () => SubagentControlsState | null;
+export declare const useSubagentControls: () => SubagentControlsState | null;
+export declare const findPublishedWave: (controls: SubagentControlsState | null, waveId: string) => PublishedSubagentWave | undefined;

package/dist/stream/subagent-lanes-model.d.ts

@@ -0,0 +1,175 @@
+import { ActivityItem, ToolActivityItem } from './activity-items.ts';
+import { ApprovalState, BelongUIMessage, PlanData, SubagentData } from './belong-data-parts.ts';
+/** A lane's state: the two in-flight states plus every §1.2 outcome. */
+export type SubagentLaneStatus = "queued" | "running" | "ok" | "error" | "timeout" | "stalled" | "stopped" | "interrupted";
+/** §3.3 colour column: accent while running, orange when it ended badly, else neutral. */
+export type SubagentLaneTone = "active" | "notice" | "quiet";
+/** §3.3 + §4a — what a lane's subline says; running and ok lanes say nothing of their own. */
+export type SubagentLaneSubline = "waiting" | Exclude<SubagentLaneStatus, "running" | "ok">;
+type SubagentLaneStep = {
+    /**
+     * `<group key>:item-<index in that group>` — unique across the message (a
+     * lane's steps can come from several groups) and stable as the stream
+     * appends, so a step never remounts.
+     */
+    readonly key: string;
+    readonly item: ToolActivityItem;
+};
+export type SubagentLane = {
+    readonly subagentId: string;
+    readonly data: SubagentData;
+    readonly status: SubagentLaneStatus;
+    /** §4a — an approval this subagent raised is still pending in its message. */
+    readonly waiting: boolean;
+    readonly steps: readonly SubagentLaneStep[];
+};
+/**
+ * One render group of a message, the shape `groupMessageParts` returns —
+ * restated structurally so this model never imports the renderers file
+ * (depcruise counts type-only imports, and the renderers import this file).
+ */
+export type SubagentIndexGroup = {
+    readonly kind: "activity";
+    readonly key: string;
+    readonly items: readonly ActivityItem[];
+} | {
+    readonly kind: "part";
+    readonly key: string;
+    readonly part: BelongUIMessage["parts"][number];
+};
+/** §4a — what every lane needs to know about ITS message, computed once per message. */
+export type SubagentMessageIndex = {
+    /** subagentId → its lane: steps from every group, `waiting` from every approval card. */
+    readonly lanesById: ReadonlyMap<string, SubagentLane>;
+    /** waveId → its lanes, in arrival order across every group. */
+    readonly lanesByWaveId: ReadonlyMap<string, readonly SubagentLane[]>;
+};
+/**
+ * What a group's lanes read from the message around them. `live` is the
+ * MESSAGE's liveness (it is the one a run streams into), not the group's: an
+ * approval or question card after the lanes makes their group non-last while
+ * the subagents still run, and their timers and Stop must not vanish then.
+ */
+export type SubagentLanesContext = {
+    readonly index: SubagentMessageIndex;
+    readonly live: boolean;
+};
+export type SubagentActivityEntry = {
+    readonly kind: "tool";
+    readonly key: string;
+    readonly item: ToolActivityItem;
+} | {
+    readonly kind: "lane";
+    readonly key: string;
+    readonly lane: SubagentLane;
+} | {
+    readonly kind: "wave";
+    readonly key: string;
+    readonly waveId: string;
+    /** Arrival order across the message. `orderLanes` sorts for display. */
+    readonly lanes: readonly SubagentLane[];
+};
+export type SubagentWaveCounts = {
+    readonly total: number;
+    /** `ok` */
+    readonly done: number;
+    readonly running: number;
+    readonly queued: number;
+    /** `error`, `timeout`, `stalled` */
+    readonly needsLook: number;
+    readonly stopped: number;
+    /** Every lane no longer running or queued (the meter's numerator). */
+    readonly ended: number;
+};
+export type SubagentWaveLabel = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    /**
+     * No label anywhere: the renderer words the wave itself. It needs both
+     * numbers, because "{{count}} running" is a STATE CLAIM — an unlabelled
+     * wave whose lanes have all ended must read its progress instead (§42).
+     */
+    readonly kind: "count";
+    readonly count: number;
+    /** `ok` lanes. */
+    readonly done: number;
+    readonly running: number;
+};
+/**
+ * §3.3 — the lane's state. `outcome` wins when present; an OLD part without it
+ * derives one: `finished` → ok, `failed` + `timedOut` → timeout, `failed` → error.
+ */
+export declare const subagentLaneStatus: (data: SubagentData) => SubagentLaneStatus;
+export declare const subagentLaneTone: (status: SubagentLaneStatus) => SubagentLaneTone;
+/**
+ * §4a — an approval card still waiting for a decision. The WIRE half of
+ * `ApprovalRenderer`'s own reading: `approved`, `rejected`, `amend_requested`
+ * and `expired` settle the card; only `pending` keeps it armed. (The card also
+ * settles on the viewer's own click before the wire catches up; a lane follows
+ * the wire, so the two agree once `approval_state_changed` lands, and after any
+ * reload.)
+ */
+export declare const isApprovalPending: (state: ApprovalState) => boolean;
+/**
+ * §3.3 + §4a — a running lane is silent unless an approval it raised is pending
+ * ("Waiting for you"); an ok lane is silent; every other state names itself. An
+ * ENDED lane never reads "waiting": its approval settled or went with it.
+ */
+export declare const laneSubline: (status: SubagentLaneStatus, waiting: boolean) => SubagentLaneSubline | null;
+/**
+ * §4a — read ONE message's groups once: every lane with its steps and wait, every wave.
+ *
+ * Known gap (spec deviation 15, a BACKEND defect the dock must not work around):
+ * when the executor's approval dedupe join binds two sibling subagents to one
+ * approval row, the joining seat re-emits the card under ITS OWN `subagentId`.
+ * The earlier sibling — still blocked on the same human — therefore loses its
+ * "Waiting for you" here, because the dock has no wire signal for the join.
+ */
+export declare const indexMessageSubagents: (groups: readonly SubagentIndexGroup[]) => SubagentMessageIndex;
+/**
+ * Lay ONE group out against its message's index. Without an `index` the items
+ * are treated as a whole message of their own (a story, a unit test, a pane).
+ */
+export declare const partitionActivityItems: (items: readonly ActivityItem[], index?: SubagentMessageIndex) => readonly SubagentActivityEntry[];
+/**
+ * §3.2 — running (earliest `startedAt` first), then queued, then ended badly,
+ * then interrupted, then ok. Ties keep first appearance.
+ */
+export declare const orderLanes: (lanes: readonly SubagentLane[]) => readonly SubagentLane[];
+export declare const capLanes: (lanes: readonly SubagentLane[], showAll: boolean) => {
+    readonly visible: readonly SubagentLane[];
+    readonly hiddenCount: number;
+};
+export declare const waveCounts: (lanes: readonly SubagentLane[]) => SubagentWaveCounts;
+/** Integer percent for the wave meter: ended / total. */
+export declare const waveMeterPercent: (counts: SubagentWaveCounts) => number;
+/**
+ * §3.2 — the first non-blank `groupLabel` (arrival order), else the title of
+ * the plan step a lane names, else the counts the renderer words (how many
+ * still run decides WHICH wording it may honestly use).
+ */
+export declare const waveLabel: (lanes: readonly SubagentLane[], plan: PlanData | null) => SubagentWaveLabel;
+/** §3.3 — the collapsed line's progress: how many subagents, how many are `ok`. */
+export declare const subagentProgress: (items: readonly ActivityItem[]) => {
+    readonly count: number;
+    readonly done: number;
+};
+/**
+ * §3.4 — `m:ss` (`h:mm:ss` from one hour). Running: `nowMs − startedAt`, and
+ * only while live (a crashed run's reloaded `running` part must not count up
+ * forever). Ended: `durationMs`. No `startedAt` → no timer.
+ */
+export declare const laneElapsedLabel: (input: {
+    readonly data: SubagentData;
+    readonly status: SubagentLaneStatus;
+    readonly live: boolean;
+    readonly nowMs: number;
+}) => string | null;
+/** Still in flight — the only states Stop applies to. */
+export declare const isLaneInFlight: (status: SubagentLaneStatus) => boolean;
+/** §3.6 — the fullscreen pane's filters. "running" includes queued lanes (still in flight). */
+export type SubagentPaneFilter = "all" | "running" | "attention" | "done";
+export declare const SUBAGENT_PANE_FILTERS: readonly SubagentPaneFilter[];
+export declare const laneMatchesFilter: (status: SubagentLaneStatus, filter: SubagentPaneFilter) => boolean;
+export {};