@cueplusplus/ui 0.2.0 → 0.5.0

package/dist/agent-runtime/_glyphs.js

@@ -0,0 +1,43 @@
+import "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/agent-runtime/_glyphs.tsx
+/**
+* Shared agent-runtime glyphs.
+*
+* Drawn inline for the same reason as `chat/_glyphs.tsx`: a chevron on a branch
+* stepper should not put an icon dependency on the render path of a transcript,
+* and hand-set strokes stay hairline-thin at the 8–12px sizes console density
+* asks for. `currentColor` everywhere — the tone comes from the parent.
+*
+* @internal Not part of the public API.
+*/
+/** A leftward chevron — the direction the previous branch lies in. */
+function ChevronLeftGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m10 3-5 5 5 5" })
+	});
+}
+/** A rightward chevron — the direction the next branch lies in. */
+function ChevronRightGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m6 3 5 5-5 5" })
+	});
+}
+//#endregion
+export { ChevronLeftGlyph, ChevronRightGlyph };

package/dist/agent-runtime/branch-picker.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+//#region src/agent-runtime/branch-picker.d.ts
+/** Which way along the sibling branches a click moves. */
+type BranchDirection = "previous" | "next";
+interface BranchPickerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onChange" | "children"> {
+  /** 1-based position of the branch on show — what the readout prints. */
+  index: number;
+  /** How many sibling branches exist. Below 2 the picker renders nothing. */
+  count: number;
+  /** Called with the direction to move in. Never called past either end. */
+  onNavigate: (direction: BranchDirection) => void;
+  /** Accessible name of the previous button. Defaults to `"Previous branch"`. */
+  previousLabel?: string;
+  /** Accessible name of the next button. Defaults to `"Next branch"`. */
+  nextLabel?: string;
+  /** Block both buttons — a run is in flight and the runtime cannot switch mid-run. */
+  disabled?: boolean;
+  /** Accessible name for the group. Defaults to `"Branches"`. */
+  "aria-label"?: string;
+}
+/**
+ * The `‹ 2 / 3 ›` stepper that walks a turn's regenerated siblings.
+ *
+ * It keeps a segmented control's two promises — exactly one branch is on show,
+ * and the set cannot be emptied — without being one. A row of N numbered
+ * segments is the wrong shape for a count that is usually 2 and occasionally 9,
+ * and a segmented control's recessed frame fights the message bubble it sits
+ * in. Two ghost icon buttons around a mono readout stay quiet until the reader
+ * has a reason to look at them.
+ *
+ * A single branch is not a choice, so below two branches this renders nothing
+ * at all: the host can hand it every turn's `branch` without deciding which
+ * turns deserve a control. It belongs in an agent turn's `footer` — a user
+ * bubble is a solid accent fill, and a stepper drawn on it is unreadable.
+ *
+ * The picker never moves the thread itself. It reports a direction and the host
+ * asks the runtime; under an ExternalStore runtime the switch arrives back at
+ * the adapter's `setMessages`, which is the host's to write.
+ *
+ * @example
+ * <Message agent="planner" footer={<BranchPicker index={2} count={3} onNavigate={go} disabled={busy} />}>…</Message>
+ */
+declare const BranchPicker: React.ForwardRefExoticComponent<BranchPickerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { BranchDirection, BranchPicker, BranchPickerProps };

package/dist/agent-runtime/branch-picker.js

@@ -0,0 +1,87 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { IconButton } from "../primitives/icon-button.js";
+import { ChevronLeftGlyph, ChevronRightGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/agent-runtime/branch-picker.tsx
+/**
+* The `‹ 2 / 3 ›` stepper that walks a turn's regenerated siblings.
+*
+* It keeps a segmented control's two promises — exactly one branch is on show,
+* and the set cannot be emptied — without being one. A row of N numbered
+* segments is the wrong shape for a count that is usually 2 and occasionally 9,
+* and a segmented control's recessed frame fights the message bubble it sits
+* in. Two ghost icon buttons around a mono readout stay quiet until the reader
+* has a reason to look at them.
+*
+* A single branch is not a choice, so below two branches this renders nothing
+* at all: the host can hand it every turn's `branch` without deciding which
+* turns deserve a control. It belongs in an agent turn's `footer` — a user
+* bubble is a solid accent fill, and a stepper drawn on it is unreadable.
+*
+* The picker never moves the thread itself. It reports a direction and the host
+* asks the runtime; under an ExternalStore runtime the switch arrives back at
+* the adapter's `setMessages`, which is the host's to write.
+*
+* @example
+* <Message agent="planner" footer={<BranchPicker index={2} count={3} onNavigate={go} disabled={busy} />}>…</Message>
+*/
+const BranchPicker = React.forwardRef(function BranchPicker({ className, index, count, onNavigate, previousLabel = "Previous branch", nextLabel = "Next branch", disabled, "aria-label": ariaLabel = "Branches", ...elementProps }, ref) {
+	if (count < 2) return null;
+	const position = Math.min(Math.max(index, 1), count);
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "branch-picker",
+		role: "group",
+		"aria-label": ariaLabel,
+		"data-index": position,
+		"data-count": count,
+		className: cn("inline-flex items-center gap-(--cue-space-1)", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx(IconButton, {
+				type: "button",
+				size: "sm",
+				variant: "ghost",
+				icon: ChevronLeftGlyph,
+				"aria-label": previousLabel,
+				"data-slot": "branch-picker-previous",
+				disabled: disabled === true || position <= 1,
+				onClick: () => onNavigate("previous")
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				"data-slot": "branch-picker-position",
+				className: "font-mono text-(length:--cue-text-micro) tabular-nums text-fg-subtle",
+				children: [/* @__PURE__ */ jsxs("span", {
+					"aria-hidden": "true",
+					children: [
+						position,
+						" / ",
+						count
+					]
+				}), /* @__PURE__ */ jsxs("span", {
+					className: "sr-only",
+					children: [
+						"branch ",
+						position,
+						" of ",
+						count
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx(IconButton, {
+				type: "button",
+				size: "sm",
+				variant: "ghost",
+				icon: ChevronRightGlyph,
+				"aria-label": nextLabel,
+				"data-slot": "branch-picker-next",
+				disabled: disabled === true || position >= count,
+				onClick: () => onNavigate("next")
+			})
+		]
+	});
+});
+//#endregion
+export { BranchPicker };

package/dist/agent-runtime/index.d.ts

@@ -0,0 +1,4 @@
+import { BranchDirection, BranchPicker, BranchPickerProps } from "./branch-picker.js";
+import { ToolCallCard, ToolCallCardProps, ToolCallStatus } from "./tool-call-card.js";
+import { AgentThread, AgentToolCall, AgentTurn, AgentTurnStatus, UseAgentThreadOptions, useAgentThread } from "./use-agent-thread.js";
+export { type AgentThread, type AgentToolCall, type AgentTurn, type AgentTurnStatus, type BranchDirection, BranchPicker, type BranchPickerProps, ToolCallCard, type ToolCallCardProps, type ToolCallStatus, type UseAgentThreadOptions, useAgentThread };

package/dist/agent-runtime/index.js

@@ -0,0 +1,4 @@
+import { BranchPicker } from "./branch-picker.js";
+import { ToolCallCard } from "./tool-call-card.js";
+import { useAgentThread } from "./use-agent-thread.js";
+export { BranchPicker, ToolCallCard, useAgentThread };

package/dist/agent-runtime/tool-call-card.d.ts

@@ -0,0 +1,69 @@
+import { AskDanger } from "../chat/ask-box.js";
+import * as React from "react";
+//#region src/agent-runtime/tool-call-card.d.ts
+/** Where a tool call has got to. `idle` is a call parked on a human. */
+type ToolCallStatus = "working" | "done" | "failed" | "idle";
+interface ToolCallCardProps extends Omit<React.ComponentPropsWithoutRef<"div">, "title"> {
+  /** Name of the tool being called. */
+  tool: string;
+  /** The call's arguments, rendered verbatim as preformatted text. Pass a string you already formatted — JSON, a command line. An empty string counts as absent. */
+  args?: string;
+  /** What the tool returned, rendered verbatim. A string is shown as text; pass your own renderer for rich output and own that decision. `null`, `false`, an empty string or an empty array count as absent. */
+  result?: React.ReactNode;
+  /** Where the call has got to. Omit to draw no status line at all. */
+  status?: ToolCallStatus;
+  /** What the tool is doing right now. Shown beside the spinner while `working`, and as the text while `idle`. */
+  activity?: React.ReactNode;
+  /** Risk rating for the call, chipped the way an AskBox approval is. Omit for a routine call. */
+  danger?: AskDanger;
+  /** Slug of the agent making the call, so the rail takes its colour. Named in assistive text as well as inked. */
+  agent?: string;
+  /** Slug of the orchestrator, so its calls take the theme accent. */
+  rootAgent?: string;
+  /** Open state when controlled. Pass with `onOpenChange`. */
+  open?: boolean;
+  /** Initial open state. Defaults to `false`. */
+  defaultOpen?: boolean;
+  /** Called with the state the card is asking to move to. */
+  onOpenChange?: (open: boolean) => void;
+  /** Eyebrow over the arguments block. Defaults to `"arguments"`. */
+  argsLabel?: React.ReactNode;
+  /** Eyebrow over the result block. Defaults to `"result"`. */
+  resultLabel?: React.ReactNode;
+  /** What a finished call says. Defaults to `"Completed"`. */
+  doneLabel?: React.ReactNode;
+  /** What a failed call says. Defaults to `"Failed"`. */
+  failedLabel?: React.ReactNode;
+  /** Extra detail under the result — an approval `AskBox`, a nested transcript. */
+  children?: React.ReactNode;
+}
+/**
+ * An LLM's own tool call, shown while it runs and after.
+ *
+ * The two neighbours it is deliberately not: `AskBox` is a question put to a
+ * human and it waits for an answer; `DelegationCard` is another agent's work
+ * folded into a lane. This is the model reaching for a tool by itself — nobody
+ * is being asked anything, and nothing downstream is another agent's turn. It
+ * borrows both their surfaces on purpose, so a transcript mixing all three
+ * reads as one family: the tool name and risk chip are `AskBox`'s, the status
+ * line and the disclosure are `DelegationCard`'s.
+ *
+ * Arguments and results are rendered verbatim: there is no markdown or HTML
+ * path here on purpose. Both are untrusted text — half of it is the model's
+ * own output and the other half is whatever the tool returned — and a
+ * component that quietly parsed them would make every consumer of this library
+ * one prompt away from an injection. `args` is text you already formatted;
+ * `result` takes nodes, so a caller who wants rich output passes their own
+ * renderer and owns that decision.
+ *
+ * The body is mounted and unmounted rather than height-animated. A call's
+ * result lands mid-render and its arguments grow while they stream, and
+ * animating the height of something that changes size on its own is how a panel
+ * ends up permanently mid-transition.
+ *
+ * @example
+ * <ToolCallCard tool="read_file" args={'{ "path": "cue.json" }'} status="working" activity="reading 12 KB" />
+ */
+declare const ToolCallCard: React.ForwardRefExoticComponent<ToolCallCardProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ToolCallCard, ToolCallCardProps, ToolCallStatus };

package/dist/agent-runtime/tool-call-card.js

@@ -0,0 +1,187 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { AGENT_ROOT_COLOR, agentColor } from "../chat/agent-color.js";
+import { CheckGlyph } from "../chat/_glyphs.js";
+import { Chip } from "../primitives/chip.js";
+import { Spinner } from "../primitives/spinner.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/agent-runtime/tool-call-card.tsx
+/**
+* The same map `AskBox` paints an approval with, for the same reason: a call
+* the reader is watching and the question asking them to allow it must rate
+* risk in one vocabulary, or the two cards disagree about what "critical"
+* looks like.
+*/
+const DANGER_TONES = {
+	low: "ok",
+	high: "warn",
+	critical: "danger"
+};
+/**
+* The header row, shared by the disclosure button and the buttonless header a
+* card with nothing to disclose draws instead — the two must sit at exactly the
+* same height and ink, or a list of calls ripples as some of them gain detail.
+*/
+const HEADER = "flex min-w-0 items-center gap-(--cue-space-2) border-0 bg-transparent p-0 text-start font-mono text-(length:--cue-text-ui) text-fg-muted outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+/** The label over a block in the body, in the same eyebrow as a message header. */
+const EYEBROW = "font-mono text-(length:--cue-text-micro) tracking-[0.15em] uppercase text-fg-subtle";
+/**
+* An LLM's own tool call, shown while it runs and after.
+*
+* The two neighbours it is deliberately not: `AskBox` is a question put to a
+* human and it waits for an answer; `DelegationCard` is another agent's work
+* folded into a lane. This is the model reaching for a tool by itself — nobody
+* is being asked anything, and nothing downstream is another agent's turn. It
+* borrows both their surfaces on purpose, so a transcript mixing all three
+* reads as one family: the tool name and risk chip are `AskBox`'s, the status
+* line and the disclosure are `DelegationCard`'s.
+*
+* Arguments and results are rendered verbatim: there is no markdown or HTML
+* path here on purpose. Both are untrusted text — half of it is the model's
+* own output and the other half is whatever the tool returned — and a
+* component that quietly parsed them would make every consumer of this library
+* one prompt away from an injection. `args` is text you already formatted;
+* `result` takes nodes, so a caller who wants rich output passes their own
+* renderer and owns that decision.
+*
+* The body is mounted and unmounted rather than height-animated. A call's
+* result lands mid-render and its arguments grow while they stream, and
+* animating the height of something that changes size on its own is how a panel
+* ends up permanently mid-transition.
+*
+* @example
+* <ToolCallCard tool="read_file" args={'{ "path": "cue.json" }'} status="working" activity="reading 12 KB" />
+*/
+const ToolCallCard = React.forwardRef(function ToolCallCard({ className, tool, args, result, status, activity, danger, agent, rootAgent, open: openProp, defaultOpen, onOpenChange, argsLabel = "arguments", resultLabel = "result", doneLabel = "Completed", failedLabel = "Failed", children, style, ...elementProps }, ref) {
+	const bodyId = React.useId();
+	const isControlled = openProp !== void 0;
+	const [uncontrolled, setUncontrolled] = React.useState(defaultOpen ?? false);
+	const open = isControlled ? openProp : uncontrolled;
+	const hasArgs = args !== void 0 && args !== "";
+	const hasResult = result !== void 0 && result !== null && result !== false && result !== "" && !(Array.isArray(result) && result.length === 0);
+	const hasDetail = hasArgs || hasResult || children !== void 0;
+	const toggle = () => {
+		const next = !open;
+		if (!isControlled) setUncontrolled(next);
+		onOpenChange?.(next);
+	};
+	const color = agent === void 0 ? AGENT_ROOT_COLOR : agentColor(agent, { root: rootAgent });
+	const heading = /* @__PURE__ */ jsxs(Fragment, { children: [
+		/* @__PURE__ */ jsx("span", {
+			"aria-hidden": "true",
+			className: "shrink-0 text-(--agent-color)",
+			children: "●"
+		}),
+		/* @__PURE__ */ jsx("code", {
+			"data-slot": "tool-call-card-tool",
+			className: "min-w-0 truncate font-mono text-(length:--cue-text-micro) text-fg",
+			children: tool
+		}),
+		agent === void 0 ? null : /* @__PURE__ */ jsxs("span", {
+			className: "sr-only",
+			children: ["by ", agent]
+		}),
+		danger === void 0 ? null : /* @__PURE__ */ jsx(Chip, {
+			"data-slot": "tool-call-card-danger",
+			tone: DANGER_TONES[danger],
+			"data-danger": danger,
+			children: danger
+		})
+	] });
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "tool-call-card",
+		"data-agent": agent,
+		"data-status": status,
+		"data-state": hasDetail ? open ? "open" : "closed" : void 0,
+		"data-danger": danger,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-2) rounded-(--radius-control) border border-border px-(--cue-space-3) py-(--cue-space-2)", className),
+		style: {
+			"--agent-color": color,
+			...style
+		},
+		...elementProps,
+		children: [
+			hasDetail ? /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				"data-slot": "tool-call-card-trigger",
+				"aria-expanded": open,
+				"aria-controls": open ? bodyId : void 0,
+				className: cn(HEADER, "cursor-pointer"),
+				onClick: toggle,
+				children: [/* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					"data-slot": "tool-call-card-caret",
+					className: "shrink-0 text-(length:--cue-text-micro) leading-none select-none",
+					children: open ? "▾" : "▸"
+				}), heading]
+			}) : /* @__PURE__ */ jsxs("div", {
+				"data-slot": "tool-call-card-header",
+				className: HEADER,
+				children: [/* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					"data-slot": "tool-call-card-caret-space",
+					className: "invisible shrink-0 text-(length:--cue-text-micro) leading-none select-none",
+					children: "▸"
+				}), heading]
+			}),
+			status === void 0 ? null : /* @__PURE__ */ jsxs("div", {
+				"data-slot": "tool-call-card-status",
+				"data-status": status,
+				className: cn("flex min-w-0 items-center gap-(--cue-space-2) ps-(--cue-space-5) font-mono text-(length:--cue-text-micro)", status === "failed" ? "text-danger" : "text-fg-subtle"),
+				children: [
+					status === "working" ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Spinner, {
+						size: "sm",
+						label: "working",
+						"data-slot": "tool-call-card-spinner",
+						className: "text-(--agent-color)"
+					}), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: activity ?? "working…"
+					})] }) : null,
+					status === "done" ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CheckGlyph, { className: "size-icon-sm shrink-0 text-ok" }), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: doneLabel
+					})] }) : null,
+					status === "failed" ? /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: failedLabel
+					}) : null,
+					status === "idle" ? /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 truncate",
+						children: activity ?? "waiting"
+					}) : null
+				]
+			}),
+			open && hasDetail ? /* @__PURE__ */ jsxs("div", {
+				id: bodyId,
+				"data-slot": "tool-call-card-body",
+				className: "ms-(--cue-space-3) flex min-w-0 flex-col gap-(--cue-space-2) border-s-2 [border-inline-start-color:var(--agent-color)] ps-(--cue-space-4)",
+				children: [
+					hasArgs ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+						"data-slot": "tool-call-card-args-label",
+						className: EYEBROW,
+						children: argsLabel
+					}), /* @__PURE__ */ jsx("pre", {
+						"data-slot": "tool-call-card-args",
+						className: "m-0 min-w-0 overflow-x-auto font-mono text-(length:--cue-text-micro) leading-relaxed break-words whitespace-pre-wrap text-fg-muted",
+						children: args
+					})] }) : null,
+					hasResult ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+						"data-slot": "tool-call-card-result-label",
+						className: EYEBROW,
+						children: resultLabel
+					}), /* @__PURE__ */ jsx("div", {
+						"data-slot": "tool-call-card-result",
+						className: "min-w-0 font-mono text-(length:--cue-text-micro) leading-relaxed break-words whitespace-pre-wrap text-fg",
+						children: result
+					})] }) : null,
+					children
+				]
+			}) : null
+		]
+	});
+});
+//#endregion
+export { ToolCallCard };

package/dist/agent-runtime/use-agent-thread.d.ts

@@ -0,0 +1,164 @@
+import { BranchDirection } from "./branch-picker.js";
+import { ToolCallStatus } from "./tool-call-card.js";
+import { MessageRole } from "../chat/message.js";
+import { AssistantRuntime, ThreadMessage } from "@assistant-ui/react";
+//#region src/agent-runtime/use-agent-thread.d.ts
+/** Where an agent turn has got to. */
+type AgentTurnStatus = "streaming" | "complete" | "requires-action" | "cancelled" | "failed";
+/** One tool call inside a turn, in the shape `ToolCallCard` takes. */
+interface AgentToolCall {
+  /** The runtime's id for the call. */
+  id: string;
+  /** Tool name. Spread onto `ToolCallCard` as `tool`. */
+  tool: string;
+  /** Arguments as text: the pretty-printed parse once any field has landed, else the raw JSON as streamed. Spread as `args`. */
+  args: string;
+  /** The result as text, or `undefined` until there is one. Spread as `result`. */
+  result: string | undefined;
+  /** Spread onto `ToolCallCard` as `status`. */
+  status: ToolCallStatus;
+}
+/** One turn, in the shape `Message` takes. */
+interface AgentTurn {
+  /** The runtime's message id. Use it as the React key and for `regenerate`/`switchBranch`. */
+  id: string;
+  /** Spread onto `Message` as `role`. */
+  role: MessageRole;
+  /** From `options.agent`; `undefined` when unset. Spread onto `Message` as `agent`. */
+  agent: string | undefined;
+  /** Every text part, joined by a blank line. Render verbatim as `Message`'s children. */
+  text: string;
+  /** Every reasoning part, joined by a blank line, or `undefined` when there is none. */
+  reasoning: string | undefined;
+  /** The turn's tool calls, in order. */
+  toolCalls: readonly AgentToolCall[];
+  /** Where the turn has got to, in words rather than in flags. */
+  status: AgentTurnStatus;
+  /** `status === "streaming"`. Spread onto `Message` as `pending`. */
+  pending: boolean;
+  /** When the runtime first saw the turn. */
+  createdAt: Date;
+  /** 1-based position among sibling branches, and how many there are — `BranchPicker`'s `index`/`count`. */
+  branch: {
+    readonly index: number;
+    readonly count: number;
+  };
+  /** The runtime's own message, for anything this shape leaves out. */
+  message: ThreadMessage;
+}
+interface UseAgentThreadOptions {
+  /** Names the agent behind agent turns: a fixed slug, or a resolver reading the runtime message (e.g. `m.metadata.custom.agent`). A resolver may be inline: it is read through a ref and applied when the thread changes, not on every render. */
+  agent?: string | ((message: ThreadMessage) => string | undefined);
+}
+/** What the hook returns — every field named for the prop it feeds. */
+interface AgentThread {
+  /** The thread, oldest first. One `Message` each. */
+  turns: readonly AgentTurn[];
+  /** A run is in flight. Spread onto `Composer` as `busy`. */
+  busy: boolean;
+  /** The thread cannot take input. Spread onto `Composer` as `disabled`. */
+  disabled: boolean;
+  /** Send a user turn. Spread onto `Composer` as `onSend`. */
+  onSend: (text: string) => void;
+  /** Abort the run — `undefined` when the runtime cannot cancel, so `Composer` keeps Send. Spread as `onStop`. */
+  onStop: (() => void) | undefined;
+  /** Regenerate an agent turn in place (a new branch), or `undefined` when the runtime cannot reload. */
+  regenerate: ((turnId: string) => void) | undefined;
+  /** Move a turn to its previous/next sibling branch, or `undefined` when the runtime cannot switch. Feed `BranchPicker`'s `onNavigate`. */
+  switchBranch: ((turnId: string, direction: BranchDirection) => void) | undefined;
+  /** The runtime itself, for anything this shape leaves out. */
+  runtime: AssistantRuntime;
+}
+/**
+ * An assistant-ui runtime, read as the props the Chat group already takes.
+ *
+ * `Message`, `MessageList` and `Composer` render turns that have finished
+ * arriving. The hard part of a turn that is *still* arriving — assembling
+ * tokens, tracking a run, cancelling one, keeping a regenerated answer beside
+ * its sibling — is a solved problem, so this library does not re-derive it. You
+ * build a runtime with one line of assistant-ui, typically
+ * `useExternalStoreRuntime(adapter)`, and hand the object over; every field
+ * that comes back is named for the prop it feeds.
+ *
+ * It is provider-free by construction: a `useSyncExternalStore` over the
+ * runtime's thread, and nothing else. No `AssistantRuntimeProvider`, no
+ * primitive, no context and no borrowed DOM — this library renders 100% of what
+ * the reader sees, and the peer is only a type in the shipped modules.
+ *
+ * `MessageList` follows a turn that is still growing on its own: the items
+ * container is watched for growth, so a streaming bubble keeps the bottom in
+ * view without the host adding anything, while a tool-call card the reader
+ * folds away leaves the view where it was.
+ *
+ * Four things are worth knowing before wiring an `ExternalStoreAdapter` to it:
+ *
+ * - **Pass `convertMessage`, and keep its identity.** Without it your messages
+ *   must already be complete runtime messages, and a missing `metadata`
+ *   throws; `convertMessage: (m) => m` lets the runtime fill the defaults in.
+ *   Declare it outside the component (or memoise it): the runtime caches the
+ *   conversion against that function, so a fresh arrow every render re-converts
+ *   the whole thread, which re-renders, which converts it again — an inline
+ *   arrow turns the next message change into "Maximum update depth exceeded".
+ * - **`onReload` takes two arguments** — `(parentId, config)`. Regenerating a
+ *   turn re-runs its *parent*, which is what puts the new answer beside the old
+ *   one rather than after it.
+ * - **A branch switch is host-owned.** Under an ExternalStore runtime
+ *   `switchBranch` does not move the thread: it arrives at the adapter's
+ *   `setMessages` with the newly visible list, and the host writes it back. A
+ *   host that ignores `setMessages` gets a picker that does nothing.
+ * - **`onStop`, `regenerate` and `switchBranch` are `undefined`** until the
+ *   matching callback exists on the adapter (`onCancel`, `onReload`,
+ *   `setMessages`). That is deliberate: `Composer` keeps drawing Send while
+ *   `onStop` is missing, so a control that cannot work is never drawn.
+ *
+ * @example
+ * // Outside the component: the runtime caches the conversion against this
+ * // function, and a new one every render is an update loop.
+ * const convertMessage = (m: ThreadMessageLike) => m;
+ *
+ * const runtime = useExternalStoreRuntime({
+ *   messages,
+ *   isRunning,
+ *   convertMessage,
+ *   onNew,
+ *   onCancel,
+ *   onReload,
+ *   setMessages,
+ * });
+ * const thread = useAgentThread(runtime, { agent: "planner" });
+ *
+ * <MessageList aria-label="Thread">
+ *   {thread.turns.map((t) => (
+ *     <Message
+ *       key={t.id}
+ *       role={t.role}
+ *       agent={t.agent}
+ *       pending={t.pending}
+ *       footer={
+ *         t.branch.count > 1 && thread.switchBranch ? (
+ *           <BranchPicker
+ *             index={t.branch.index}
+ *             count={t.branch.count}
+ *             onNavigate={(d) => thread.switchBranch?.(t.id, d)}
+ *             disabled={thread.busy}
+ *           />
+ *         ) : undefined
+ *       }
+ *     >
+ *       {t.text}
+ *       {t.toolCalls.map((c) => (
+ *         <ToolCallCard key={c.id} tool={c.tool} args={c.args} result={c.result} status={c.status} />
+ *       ))}
+ *     </Message>
+ *   ))}
+ * </MessageList>
+ * <Composer
+ *   onSend={thread.onSend}
+ *   busy={thread.busy}
+ *   disabled={thread.disabled || thread.busy}
+ *   onStop={thread.onStop}
+ * />
+ */
+declare function useAgentThread(runtime: AssistantRuntime, options?: UseAgentThreadOptions): AgentThread;
+//#endregion
+export { AgentThread, AgentToolCall, AgentTurn, AgentTurnStatus, UseAgentThreadOptions, useAgentThread };