@cueplusplus/ui 0.13.0

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-(--cue-leading-ui) 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-(--cue-leading-ui) 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 };

package/dist/agent-runtime/use-agent-thread.js

@@ -0,0 +1,251 @@
+"use client";
+import * as React from "react";
+//#region src/agent-runtime/use-agent-thread.ts
+/**
+* The runtime says `assistant`; this library has said `agent` since its first
+* chat component, because a turn here can come from one of a dozen named
+* workers rather than the assistant.
+*/
+const ROLES = {
+	assistant: "agent",
+	system: "system",
+	user: "user"
+};
+/** Every text part of a turn, as one block of prose. */
+function joinText(content) {
+	return content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n\n");
+}
+/** Every reasoning part, or nothing at all when the model showed none. */
+function joinReasoning(content) {
+	const thoughts = content.flatMap((part) => part.type === "reasoning" ? [part.text] : []);
+	return thoughts.length === 0 ? void 0 : thoughts.join("\n\n");
+}
+/**
+* While a call is still streaming, `args` is a partial parse — often `{}` for
+* several frames — and `argsText` is what the model has actually said. Show the
+* parse once there is one, the raw text until then, and nothing invented in
+* either case.
+*/
+function formatArgs(part) {
+	const args = part.args;
+	if (typeof args === "object" && args !== null && Object.keys(args).length > 0) return JSON.stringify(args, null, 2);
+	return part.argsText ?? "";
+}
+/** A result as text, whatever the tool returned. Never parsed, never rendered as markup. */
+function formatResult(result) {
+	if (result === void 0) return void 0;
+	if (typeof result === "string") return result;
+	return JSON.stringify(result, null, 2) ?? String(result);
+}
+/**
+* A call has no status of its own until it has an outcome, so until then it
+* borrows the turn's: a call inside a running turn is working, one inside a
+* turn parked on a human is waiting.
+*/
+function toolStatus(part, message) {
+	if (part.isError === true) return "failed";
+	if (part.result !== void 0) return "done";
+	switch (message.status?.type) {
+		case "running": return "working";
+		case "requires-action": return "idle";
+		case "incomplete": return "failed";
+		default: return "done";
+	}
+}
+/** The turn's tool calls, in the order the model made them. */
+function toolCalls(message) {
+	return message.content.flatMap((part) => part.type === "tool-call" ? [{
+		id: part.toolCallId,
+		tool: part.toolName,
+		args: formatArgs(part),
+		result: formatResult(part.result),
+		status: toolStatus(part, message)
+	}] : []);
+}
+/** The runtime's status vocabulary, in this library's words. */
+function turnStatus(message) {
+	if (message.role !== "assistant") return "complete";
+	switch (message.status.type) {
+		case "running": return "streaming";
+		case "requires-action": return "requires-action";
+		case "incomplete": return message.status.reason === "cancelled" ? "cancelled" : "failed";
+		default: return "complete";
+	}
+}
+/** Where the turn sits among its regenerated siblings. */
+function branchOf(runtime, id) {
+	try {
+		const state = runtime.thread.getMessageById(id).getState();
+		return {
+			index: state.branchNumber,
+			count: state.branchCount
+		};
+	} catch {
+		return {
+			index: 1,
+			count: 1
+		};
+	}
+}
+/** One runtime message, in the props the Chat group takes. */
+function toTurn(runtime, message, agent) {
+	const role = ROLES[message.role];
+	const status = turnStatus(message);
+	return {
+		id: message.id,
+		role,
+		agent: role !== "agent" ? void 0 : typeof agent === "function" ? agent(message) : agent,
+		text: joinText(message.content),
+		reasoning: joinReasoning(message.content),
+		toolCalls: toolCalls(message),
+		status,
+		pending: status === "streaming",
+		createdAt: message.createdAt,
+		branch: branchOf(runtime, message.id),
+		message
+	};
+}
+/**
+* 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}
+* />
+*/
+function useAgentThread(runtime, options) {
+	const agent = options?.agent;
+	const agentRef = React.useRef(agent);
+	agentRef.current = agent;
+	const agentKey = typeof agent === "function" ? "fn" : agent;
+	const subscribe = React.useCallback((onStoreChange) => runtime.thread.subscribe(onStoreChange), [runtime]);
+	const getState = React.useCallback(() => runtime.thread.getState(), [runtime]);
+	const { capabilities, isDisabled, isRunning, messages } = React.useSyncExternalStore(subscribe, getState, getState);
+	const turns = React.useMemo(() => messages.map((message) => toTurn(runtime, message, agentRef.current)), [
+		messages,
+		runtime,
+		agentKey
+	]);
+	const onSend = React.useCallback((text) => {
+		runtime.thread.append({
+			role: "user",
+			content: [{
+				type: "text",
+				text
+			}]
+		});
+	}, [runtime]);
+	const cancel = React.useCallback(() => {
+		runtime.thread.cancelRun();
+	}, [runtime]);
+	const reload = React.useCallback((turnId) => {
+		runtime.thread.getMessageById(turnId).reload();
+	}, [runtime]);
+	const switchTo = React.useCallback((turnId, direction) => {
+		runtime.thread.getMessageById(turnId).switchToBranch({ position: direction });
+	}, [runtime]);
+	return React.useMemo(() => ({
+		turns,
+		busy: isRunning,
+		disabled: isDisabled,
+		onSend,
+		onStop: capabilities.cancel ? cancel : void 0,
+		regenerate: capabilities.reload ? reload : void 0,
+		switchBranch: capabilities.switchToBranch ? switchTo : void 0,
+		runtime
+	}), [
+		turns,
+		isRunning,
+		isDisabled,
+		capabilities,
+		onSend,
+		cancel,
+		reload,
+		switchTo,
+		runtime
+	]);
+}
+//#endregion
+export { useAgentThread };

package/dist/brand/_chassis.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+//#region src/brand/_chassis.d.ts
+/**
+ * What every brand asset in this group shares: how big it is drawn, where its
+ * ink comes from, and how it is named to a screen reader.
+ *
+ * Three assets, one contract, because a header that puts the mark next to the
+ * logotype has to be able to say `size="sm"` twice and get two things the same
+ * height.
+ */
+/**
+ * Rung of the density control ladder a brand asset is drawn at.
+ *
+ * The same three rungs `Button`, `Avatar` and every form control use, and for
+ * the same reason: a mark in a toolbar is furniture on that toolbar's row, so
+ * it has to move when the density does. `size` picks the rung; the density
+ * decides what the rung measures.
+ */
+type BrandSize = "sm" | "md" | "lg";
+/**
+ * Where a brand asset takes its ink from.
+ *
+ * Not a light/dark pair. The source artwork ships two files that hard-code
+ * `white`, `black` and `#1E1E1E`; this library ships one component that reads
+ * the token layer, so a single element is correct in all ten presets and both
+ * modes without anybody choosing a file.
+ */
+type BrandTone = "inherit" | "fg" | "accent";
+/** The props every asset in this group takes. */
+interface BrandAssetProps extends Omit<React.ComponentPropsWithoutRef<"svg">, "children" | "width" | "height" | "title"> {
+  /**
+   * Rung of the density control ladder to draw at, or an explicit height in px.
+   * Defaults to `"md"`.
+   *
+   * Height, always — every asset here keeps its own aspect ratio, so the width
+   * follows from the artwork rather than from the caller.
+   */
+  size?: BrandSize | number;
+  /**
+   * Where the ink comes from: `currentColor`, the foreground token, or the
+   * accent. Defaults to `"inherit"`.
+   */
+  tone?: BrandTone;
+  /**
+   * The accessible name.
+   *
+   * Omit it and the asset is decorative — `aria-hidden`, announced by nothing.
+   * Pass one only when the mark is the *only* thing naming what it sits on: a
+   * bare logo link, a splash screen with no heading.
+   */
+  title?: string;
+}
+//#endregion
+export { BrandAssetProps, BrandSize, BrandTone };