@belonguniverseai/react-sdk 0.6.21 → 0.6.22

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
@@ -137,8 +139,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;
 };
@@ -153,8 +155,15 @@ export type ToolCallData = {
  * 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 +178,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 +293,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:
@@ -289,6 +329,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 +357,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<"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 {};

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

@@ -0,0 +1,89 @@
+import { ReactNode } from 'react';
+import { TFunction } from 'i18next';
+import { ActivityItem, ToolActivityItem } from './activity-items.ts';
+import { SubagentData } from './belong-data-parts.ts';
+import { SubagentControlsState } from './subagent-controls-store.ts';
+import { SubagentLane, SubagentLaneStatus, SubagentMessageIndex, SubagentWaveCounts, SubagentWaveLabel } from './subagent-lanes-model.ts';
+type RenderToolItem = (item: ToolActivityItem) => ReactNode;
+/**
+ * §3.6 — the wave label, worded. An unlabelled wave says how many are running
+ * only while any lane still is: "3 running" beside counts of "3 done" would be
+ * a false state claim on the surface §42 exists to keep honest. Once none runs,
+ * it reads the progress the collapsed line already words. BY NAME: that key is
+ * "{{done}} of {{count}} done" — a swapped pass renders "3 of 2 done".
+ */
+export declare const waveLabelText: (t: TFunction, label: SubagentWaveLabel) => string;
+/** §3.6 — non-zero counts, in order: done, running, waiting, need a look, stopped. */
+export declare const waveCountsText: (t: TFunction, counts: SubagentWaveCounts) => string;
+/**
+ * The elapsed-time LEAF (§3.4). It owns the only interval, so a tick re-renders
+ * this span and nothing else, and it runs only while the group is live and the
+ * lane is running — the group's content is force-mounted while collapsed, so an
+ * unconditional interval would tick for every group in the transcript. This
+ * leaf is the wall-clock adapter; the model takes `nowMs` (§25).
+ */
+export declare const SubagentElapsed: ({ data, status, live, }: {
+    readonly data: SubagentData;
+    readonly status: SubagentLaneStatus;
+    readonly live: boolean;
+}) => import("react").JSX.Element | null;
+/** Accent spinner only while live (a reloaded crashed run must not spin), tick when ok, dot when orange. */
+export declare const SubagentGlyph: ({ status, live, }: {
+    readonly status: SubagentLaneStatus;
+    readonly live: boolean;
+}) => import("react").JSX.Element;
+/**
+ * §3.3 subline: orange for the ended-badly outcomes, muted otherwise — including
+ * §4a's "Waiting for you" on a running lane whose approval is pending (waiting
+ * on a person is not a failure).
+ */
+export declare const SubagentOutcomeLine: ({ status, waiting, }: {
+    readonly status: SubagentLaneStatus;
+    readonly waiting: boolean;
+}) => import("react").JSX.Element | null;
+/** §3.5 — the subagent's own written report, as PLAIN text (never HTML). */
+export declare const SubagentReport: ({ summary }: {
+    readonly summary: string;
+}) => import("react").JSX.Element;
+/**
+ * §3.5 — the Stop handler for a lane, or null when Stop must not render: the
+ * lane is stoppable (own loop only) and still running or queued, its group is
+ * live, and the chat has an active run.
+ */
+export declare const stopHandlerFor: (controls: SubagentControlsState | null, live: boolean, lane: SubagentLane) => SubagentControlsState["stop"] | null;
+/**
+ * Stop ONE subagent. Disables after the click and shows nothing optimistic:
+ * the lane changes only when its `subagent_finished` part arrives (§3.5).
+ * `outline`, never `destructive` (§42) — a stop is an ordinary thing to ask
+ * for, and it is best-effort besides.
+ */
+export declare const SubagentStopButton: ({ subagentId, onStop, }: {
+    readonly subagentId: string;
+    readonly onStop: SubagentControlsState["stop"];
+}) => import("react").JSX.Element;
+/**
+ * Decision 9 — Stop all confirms INLINE, in two steps: the first click turns
+ * the button into "Stop N?" for 4 s; a second click inside that window stops.
+ * No modal. Once it stops, it stays disabled until the lanes finish and the
+ * button unmounts (nothing optimistic).
+ */
+export declare const SubagentStopAll: ({ count, onStopAll, }: {
+    readonly count: number;
+    readonly onStopAll: () => Promise<void>;
+}) => import("react").JSX.Element;
+/** A report worth a toggle: present and not blank. */
+export declare const reportOf: (data: SubagentData) => string | null;
+/**
+ * The expanded group's body: main-loop items in place, lanes with their nested
+ * steps, and waves. Keys are the model's (`item-<i>`, `lane-<id>`,
+ * `wave-<id>`), never a render index, so a re-sort never remounts a lane.
+ * `index` is the group's MESSAGE (§4a): a lane nests its calls, and a wave its
+ * lanes, from every group of it. Absent, the items are their own message.
+ */
+export declare const SubagentLanes: ({ items, live, renderToolItem, index, }: {
+    readonly items: readonly ActivityItem[];
+    readonly live: boolean;
+    readonly renderToolItem: RenderToolItem;
+    readonly index?: SubagentMessageIndex | undefined;
+}) => import("react").JSX.Element;
+export {};

package/dist/stream/use-publish-subagent-controls.d.ts

@@ -0,0 +1,11 @@
+import { BelongChatTransport } from './belong-chat-transport.ts';
+import { BelongUIMessage } from './belong-data-parts.ts';
+import { PublishedSubagentWave } from './subagent-controls-store.ts';
+/**
+ * Every wave in the conversation, in message order — each message grouped and
+ * indexed exactly as `MessageParts` draws it (§4a, deviation 16: the same
+ * `indexableMessageParts` filter, so the pane's lanes and the chat's lanes are
+ * the same lanes down to their step keys), `waiting` included.
+ */
+export declare const collectSubagentWaves: (messages: readonly BelongUIMessage[], runActive: boolean) => readonly PublishedSubagentWave[];
+export declare const usePublishSubagentControls: (transport: Pick<BelongChatTransport, "stopSubagent">, messages: readonly BelongUIMessage[]) => void;

package/dist/stream/workspace-focus-store.d.ts

@@ -1,6 +1,11 @@
 import { PreviewTarget } from './preview-panel-store.ts';
 export type WorkspaceFocusTarget = PreviewTarget | {
     readonly kind: "plan";
+}
+/** Spec 2026-09-16 §3.5 — one wave's full subagent list ("Show all" in fullscreen). */
+ | {
+    readonly kind: "subagents";
+    readonly waveId: string;
 };
 export type WorkspaceFocusState = {
     readonly target: WorkspaceFocusTarget | null;
@@ -9,7 +14,8 @@ export type WorkspaceFocusState = {
     /** The agent wants this shown, but the user holds the pane. */
     readonly pending: WorkspaceFocusTarget | null;
 };
-/** Same thing on screen? Artifacts by id, workspace files by pinned scope + path, plans by kind. */
+/** Same thing on screen? Artifacts by id, workspace files by pinned scope + path,
+ *  plans by kind, subagent views by wave. */
 export declare const isSameFocusTarget: (a: WorkspaceFocusTarget, b: WorkspaceFocusTarget) => boolean;
 export declare const peekWorkspaceFocus: () => WorkspaceFocusState;
 export declare const subscribeWorkspaceFocus: (listener: () => void) => (() => void);

package/dist/test/render.d.ts

@@ -16,8 +16,25 @@ export declare function setValue(el: HTMLInputElement | HTMLTextAreaElement, val
  * it holds or `timeoutMs` elapses. The repo's render harness serves React's
  * prod build (no `React.act`), so async state — react-query settling, a $post
  * resolving — is observed by polling rather than awaiting `act`.
+ *
+ * `predicate` keeps its ORIGINAL truthy contract — a falsy return (`false`,
+ * `null`, `0`, `""`, a `querySelector` miss, …) means "not yet, keep
+ * polling" — with exactly two additions, both needed for the
+ * `waitFor(() => expect(x).toBe(y))` idiom: `undefined` counts as
+ * "satisfied" (a PASSING `expect(...)` call returns nothing, so treating
+ * `undefined` as falsy would spin every such predicate to the timeout), and
+ * a THROW (a FAILING `expect(...)` call) means "not yet, keep polling"
+ * rather than an immediate hard stop. Without the second part, the very
+ * FIRST call to a throwing predicate always races an async continuation
+ * that hasn't had a microtask turn yet, so it would fail on that first race
+ * almost every time, no matter how the component under test is implemented
+ * — see IssueReportDialog.test.tsx's failed-send case for a concrete
+ * instance. Every existing boolean/element-returning predicate in this repo
+ * is unaffected: `true`/a found element still short-circuits immediately,
+ * `false`/`null` still retries. On timeout the LAST assertion error (if any)
+ * is re-thrown, which is more actionable than the generic message below.
  */
-export declare function waitFor(predicate: () => boolean, { timeoutMs, stepMs }?: {
+export declare function waitFor(predicate: () => unknown, { timeoutMs, stepMs }?: {
     timeoutMs?: number;
     stepMs?: number;
 }): Promise<void>;

package/dist/test/subagent-fixtures.d.ts

@@ -0,0 +1,24 @@
+import { ActivityItem, ToolActivityItem } from '../stream/activity-items.ts';
+import { SubagentLane } from '../stream/subagent-lanes-model.ts';
+import { ApprovalState, BelongUIMessage, SubagentData, ToolCallData } from '../stream/belong-data-parts.ts';
+/** A subagent activity item; `data` overrides the running defaults. */
+export declare const subagentItem: (subagentId: string, data?: Partial<SubagentData>) => ActivityItem;
+/**
+ * A tool activity item, completed unless `state` says otherwise; `subagentId`
+ * nests it under that lane.
+ */
+export declare const toolItem: (toolName: string, subagentId?: string, state?: ToolCallData["state"]) => ToolActivityItem;
+/** An approval card part; `subagentId` undefined = the main agent raised it. */
+export declare const approvalPart: (subagentId: string | undefined, state?: ApprovalState) => BelongUIMessage["parts"][number];
+/**
+ * A `data-subagent` message part; `data` overrides the running defaults. Lives
+ * here (not in one suite) because the whole-message suite and the controls
+ * suite must build the SAME part — they assert the two index it identically.
+ */
+export declare const subagentPart: (id: string, data?: Partial<SubagentData>) => BelongUIMessage["parts"][number];
+/**
+ * A resolved lane with no steps and no pending approval — what the pure model
+ * and the fullscreen pane both start from. `status` is derived, never passed,
+ * so a fixture can never claim a state its data does not imply.
+ */
+export declare const subagentLane: (subagentId: string, data?: Partial<SubagentData>) => SubagentLane;