@candor-ui/react 0.0.0-stage → 1.0.1

package/dist/adapters/claude-agent-sdk.js

@@ -0,0 +1,265 @@
+import { markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+/**
+ * Turns Claude Agent SDK events into Candor messages, waiting approvals and usage.
+ * Pure, so it can run on every render; useClaudeAgent calls it for you.
+ */
+export function fromClaudeAgentEvents(events, options) {
+    const messages = [];
+    const approvals = new Map();
+    // Assigned inside `current`, which TypeScript can't follow, so it's typed by assertion.
+    let reply = null;
+    let sessionId;
+    let model;
+    let usage;
+    let lastCost = 0;
+    let notice;
+    const current = (id) => (reply ??= { id, parts: [], reasoning: [], tools: new Map(), live: new Map() });
+    const close = (last) => {
+        if (reply)
+            messages.push(render(reply, { ...options, model, last }));
+        reply = null;
+    };
+    for (const e of events) {
+        // Subagents report through their parent's tool call; the main thread is what the person reads.
+        if ("parent_tool_use_id" in e && e.parent_tool_use_id)
+            continue;
+        switch (e.type) {
+            case "candor_user":
+                close(false);
+                messages.push({ id: e.id, author: { role: "user" }, status: "complete", blocks: plainBlocks(e.text) });
+                notice = undefined;
+                break;
+            case "candor_approval": {
+                const { type: _, ...approval } = e;
+                approvals.set(e.id, approval);
+                const call = reply?.tools.get(e.toolUseId);
+                if (call)
+                    call.status = "waiting";
+                break;
+            }
+            case "candor_approval_closed": {
+                const approval = approvals.get(e.id);
+                approvals.delete(e.id);
+                const call = approval && reply?.tools.get(approval.toolUseId);
+                if (call && call.status === "waiting") {
+                    call.status = e.approved ? "running" : "cancelled";
+                    if (!e.approved)
+                        call.error = e.reason ? `Denied: ${e.reason}` : "Denied.";
+                }
+                break;
+            }
+            case "candor_card":
+                current(`card-${messages.length}`).parts.push({ kind: "card", card: e.card, props: e.props, summary: e.summary });
+                break;
+            case "candor_error":
+                // The first failure is the one that explains what happened.
+                current(`error-${messages.length}`).failure ??= e.message;
+                break;
+            case "system":
+                if (e.subtype === "init") {
+                    sessionId = e.session_id;
+                    model = e.model;
+                }
+                else if (e.subtype === "permission_denied") {
+                    const call = reply?.tools.get(e.tool_use_id);
+                    if (call) {
+                        call.status = "cancelled";
+                        call.error = `Not allowed: ${e.message}`;
+                    }
+                }
+                else if (e.subtype === "api_retry") {
+                    notice = `Claude’s API didn’t answer${e.error_status ? ` (${e.error_status})` : ""}; trying again, attempt ${e.attempt} of ${e.max_retries}.`;
+                }
+                break;
+            case "stream_event": {
+                const r = current(e.uuid);
+                const ev = e.event;
+                if (ev.type === "content_block_start" && (ev.content_block.type === "text" || ev.content_block.type === "thinking")) {
+                    r.live.set(ev.index, { kind: ev.content_block.type, text: "" });
+                }
+                else if (ev.type === "content_block_delta") {
+                    const live = r.live.get(ev.index);
+                    if (live && ev.delta.type === "text_delta")
+                        live.text += ev.delta.text;
+                    else if (live && ev.delta.type === "thinking_delta")
+                        live.text += ev.delta.thinking;
+                }
+                break;
+            }
+            case "assistant": {
+                const r = current(e.message.id);
+                // A complete message replaces whatever was streaming before it.
+                r.live.clear();
+                notice = undefined;
+                if (e.aborted)
+                    r.aborted = true;
+                // An API error arrives as a synthetic message whose text is meant for a terminal user ("run /login"); say it plainly instead.
+                if (e.error) {
+                    r.failure ??= assistantError(e.error);
+                    break;
+                }
+                for (const block of e.message.content)
+                    addBlock(r, block, options);
+                break;
+            }
+            case "user": {
+                if (!reply || typeof e.message.content === "string")
+                    break;
+                for (const block of e.message.content) {
+                    if (block.type !== "tool_result")
+                        continue;
+                    const call = reply.tools.get(block.tool_use_id);
+                    if (!call || call.status === "cancelled")
+                        continue;
+                    const output = resultText(block.content);
+                    call.output = output || undefined;
+                    call.outputLanguage = "text";
+                    call.status = block.is_error ? "failed" : "succeeded";
+                    if (block.is_error)
+                        call.error = firstLine(output) ?? "The tool failed and didn’t say why.";
+                }
+                break;
+            }
+            case "result": {
+                sessionId = e.session_id;
+                // The SDK's totals are cumulative for the session, so a reply's cost is the change since the last result.
+                const cost = e.total_cost_usd >= lastCost ? e.total_cost_usd - lastCost : e.total_cost_usd;
+                lastCost = e.total_cost_usd;
+                const tokens = Object.values(e.modelUsage ?? {});
+                usage = {
+                    costUsd: e.total_cost_usd,
+                    inputTokens: tokens.reduce((n, m) => n + m.inputTokens + m.cacheReadInputTokens + m.cacheCreationInputTokens, 0),
+                    outputTokens: tokens.reduce((n, m) => n + m.outputTokens, 0),
+                    turns: e.num_turns,
+                };
+                const r = current(e.uuid);
+                r.result = e.subtype === "success" && !e.is_error ? { ok: true, cost } : { ok: false, cost, error: resultError(e) };
+                notice = undefined;
+                break;
+            }
+        }
+    }
+    close(true);
+    return {
+        messages,
+        approvals: options.running ? [...approvals.values()] : [],
+        sessionId,
+        usage,
+        notice: options.running ? notice : undefined,
+    };
+}
+function addBlock(r, block, options) {
+    if (block.type === "text") {
+        if (block.text.trim())
+            r.parts.push({ kind: "text", text: block.text });
+    }
+    else if (block.type === "thinking") {
+        // With the SDK's default display, thinking arrives empty; there's nothing to show then.
+        if (block.thinking.trim())
+            r.reasoning.push(reasoningEntry(`${r.id}-r${r.reasoning.length}`, block.thinking, false));
+    }
+    else if (block.type === "tool_use" || block.type === "server_tool_use" || block.type === "mcp_tool_use") {
+        const call = { id: block.id, tool: block.name, title: options.toolTitle?.(block.name, block.input) ?? block.name, status: "running", input: json(block.input) };
+        r.tools.set(block.id, call);
+        r.parts.push({ kind: "tool", id: block.id });
+    }
+    else if ("tool_use_id" in block) {
+        // A server tool's result (web search, code execution) arrives in the assistant's own message.
+        const call = r.tools.get(block.tool_use_id);
+        if (call) {
+            const content = block.content;
+            const failed = !!content && typeof content === "object" && "error_code" in content;
+            call.status = failed ? "failed" : "succeeded";
+            call.output = content === undefined ? undefined : json(content);
+            call.outputLanguage = "json";
+            if (failed)
+                call.error = `The tool failed: ${String(content.error_code)}.`;
+        }
+    }
+}
+function render(r, o) {
+    const open = o.last && o.running;
+    const parts = [...r.parts];
+    const reasoning = [...r.reasoning];
+    if (open) {
+        for (const [index, live] of [...r.live].sort(([a], [b]) => a - b)) {
+            if (!live.text.trim())
+                continue;
+            if (live.kind === "text")
+                parts.push({ kind: "text", text: live.text });
+            else
+                reasoning.push(reasoningEntry(`${r.id}-live${index}`, live.text, true));
+        }
+    }
+    const ended = !open && !r.result?.ok;
+    const blocks = [];
+    let calls = [];
+    const flush = () => {
+        if (calls.length)
+            blocks.push({ kind: "tools", calls });
+        calls = [];
+    };
+    for (const p of parts) {
+        if (p.kind === "tool") {
+            const call = r.tools.get(p.id);
+            // A run that stopped early can't finish its tool calls.
+            calls.push(ended && (call.status === "running" || call.status === "waiting") ? { ...call, status: "cancelled", error: call.error ?? "Stopped before it finished." } : { ...call });
+            continue;
+        }
+        flush();
+        if (p.kind === "card")
+            blocks.push({ kind: "card", card: p.card, props: p.props, summary: p.summary });
+        else
+            blocks.push(...markdownBlocks(p.text));
+    }
+    flush();
+    const error = r.failure ?? r.result?.error;
+    if (error)
+        blocks.push({ kind: "degraded", reason: error });
+    return {
+        id: r.id,
+        author: { role: "agent", agent: o.agent },
+        status: open ? "streaming" : r.result?.ok ? "complete" : error ? "failed" : "interrupted",
+        blocks,
+        reasoning: reasoning.length ? reasoning : undefined,
+        attribution: r.result ? { model: o.model, cost: r.result.cost ? `$${r.result.cost.toFixed(r.result.cost < 0.01 ? 4 : 2)} (estimated)` : undefined } : undefined,
+    };
+}
+const assistantErrors = {
+    authentication_failed: "Claude couldn’t sign in. Check the server’s API key or login.",
+    billing_error: "Claude’s account has a billing problem.",
+    rate_limit: "Claude is rate-limited right now. Try again shortly.",
+    overloaded: "Claude is overloaded right now. Try again shortly.",
+    max_output_tokens: "The reply hit its length limit and was cut off.",
+    model_not_found: "The configured model isn’t available.",
+};
+const assistantError = (code) => assistantErrors[code] ?? `Claude’s API returned an error (${code}).`;
+function resultError(e) {
+    if (e.subtype === "error_max_turns")
+        return "The agent reached its turn limit before finishing.";
+    if (e.subtype === "error_max_budget_usd")
+        return "The agent reached its spending limit before finishing.";
+    if (e.subtype === "success")
+        return "The agent finished with an error.";
+    return e.errors[0] ?? "The agent stopped because of an error.";
+}
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((c) => (c.type === "text" ? (c.text ?? "") : c.type ? `[${c.type}]` : "")).join("\n");
+}
+const firstLine = (text) => text.trim().split("\n")[0] || undefined;
+const json = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 2));
+function reasoningEntry(id, text, streaming) {
+    const first = text.trim().split(/\n|(?<=[.!?])\s/)[0] ?? "";
+    return {
+        id,
+        title: first.length > 90 ? `${first.slice(0, 87)}…` : first,
+        body: text.trim(),
+        streaming,
+        basis: "believed",
+        assumption: "The model’s own reasoning; nothing checked it.",
+    };
+}

package/dist/adapters/claude-agent-server.d.ts

@@ -0,0 +1,53 @@
+import type { CanUseTool, Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentEvent } from "./claude-agent-sdk.js";
+export type RunClaudeAgent = (tools: {
+    /** Pass to query()'s `canUseTool`, so permission requests reach the person. */
+    canUseTool: CanUseTool;
+    /** Pass to query()'s `abortController`, so stopping in the browser stops the agent. */
+    abortController: AbortController;
+    /**
+     * Send a typed card to the browser, e.g. from a tool handler: `emit({ type: "candor_card", card: "diff", props, summary })`.
+     * It renders through the app's card registry, in the reply where it was sent.
+     */
+    emit: (event: AgentEvent) => void;
+}) => Query;
+export type StreamClaudeAgentOptions = {
+    /** The incoming request's signal (`request.signal`): the agent stops when the browser goes away. */
+    signal?: AbortSignal;
+    /** Who may answer this run's permission requests, e.g. the signed-in user's id. Checked by answerClaudeAgentApproval. */
+    owner?: string;
+    /** The sentence shown when the run fails. Defaults to a generic one, so server errors don't leak to the browser. */
+    describeError?: (error: unknown) => string;
+    /**
+     * Called with every SDK message just before it's sent to the browser, e.g. to record usage and cost from
+     * `assistant` and `result` messages. To stop the run from here, abort the run's abortController: the message
+     * in hand is still sent, and nothing after it.
+     */
+    onMessage?: (message: SDKMessage) => void | Promise<void>;
+};
+/**
+ * Run an agent and stream it to useClaudeAgent.
+ *
+ *   // app/api/agent/route.ts
+ *   export async function POST(request: Request) {
+ *     const { prompt, sessionId } = await request.json()
+ *     return streamClaudeAgent(
+ *       ({ canUseTool, abortController }) =>
+ *         query({ prompt, options: { canUseTool, abortController, resume: sessionId, includePartialMessages: true } }),
+ *       { signal: request.signal, owner: userId, onMessage: (m) => m.type === "result" && recordCost(m.total_cost_usd) }
+ *     )
+ *   }
+ */
+export declare function streamClaudeAgent(run: RunClaudeAgent, { signal, owner, describeError, onMessage }?: StreamClaudeAgentOptions): Response;
+/**
+ * Answer a waiting permission request. Returns false when there's no such
+ * request (already answered, the run ended, or it ran in another process) or
+ * `owner` doesn't match the run's owner.
+ *
+ *   // app/api/agent/approve/route.ts
+ *   export async function POST(request: Request) {
+ *     const { id, approved, reason } = await request.json()
+ *     return Response.json({ ok: answerClaudeAgentApproval(id, approved, reason, userId) })
+ *   }
+ */
+export declare function answerClaudeAgentApproval(id: string, approved: boolean, reason?: string, owner?: string): boolean;

package/dist/adapters/claude-agent-server.js

@@ -0,0 +1,104 @@
+const waiting = new Map();
+/**
+ * Run an agent and stream it to useClaudeAgent.
+ *
+ *   // app/api/agent/route.ts
+ *   export async function POST(request: Request) {
+ *     const { prompt, sessionId } = await request.json()
+ *     return streamClaudeAgent(
+ *       ({ canUseTool, abortController }) =>
+ *         query({ prompt, options: { canUseTool, abortController, resume: sessionId, includePartialMessages: true } }),
+ *       { signal: request.signal, owner: userId, onMessage: (m) => m.type === "result" && recordCost(m.total_cost_usd) }
+ *     )
+ *   }
+ */
+export function streamClaudeAgent(run, { signal, owner, describeError, onMessage } = {}) {
+    const encoder = new TextEncoder();
+    const abortController = new AbortController();
+    const mine = new Set();
+    let send = () => { };
+    const canUseTool = (tool, input, request) => new Promise((resolve) => {
+        const id = crypto.randomUUID();
+        const answer = (approved, reason, interrupt) => {
+            if (!waiting.delete(id))
+                return;
+            mine.delete(id);
+            send({ type: "candor_approval_closed", id, approved, reason });
+            resolve(approved
+                ? { behavior: "allow", updatedInput: input }
+                : { behavior: "deny", message: reason ? `The user declined: ${reason}` : "The user declined this action.", interrupt });
+        };
+        waiting.set(id, { owner, answer });
+        mine.add(id);
+        request.signal.addEventListener("abort", () => answer(false, "The run was stopped.", true), { once: true });
+        send({
+            type: "candor_approval",
+            id,
+            toolUseId: request.toolUseID,
+            tool,
+            input,
+            title: request.title,
+            description: request.description,
+            reason: request.decisionReason,
+            blockedPath: request.blockedPath,
+            defaultToNo: request.defaultToNo,
+        });
+    });
+    const body = new ReadableStream({
+        async start(controller) {
+            let open = true;
+            send = (event) => {
+                if (open)
+                    controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+            };
+            const stop = () => abortController.abort();
+            signal?.addEventListener("abort", stop, { once: true });
+            try {
+                for await (const message of run({ canUseTool, abortController, emit: (event) => send(event) })) {
+                    // Awaited, so bookkeeping such as recording spend finishes before the next message is handled.
+                    await onMessage?.(message);
+                    send(message);
+                    // Stopped (the browser went away, or onMessage or a tool aborted the run): nothing more is sent.
+                    if (abortController.signal.aborted)
+                        break;
+                }
+            }
+            catch (error) {
+                if (!abortController.signal.aborted) {
+                    console.error("Claude agent run failed:", error);
+                    send({ type: "candor_error", message: describeError?.(error) ?? "The agent stopped because of an error on the server." });
+                }
+            }
+            finally {
+                // Nobody can answer once the run is over.
+                for (const id of [...mine])
+                    waiting.get(id)?.answer(false, "The run ended.");
+                open = false;
+                signal?.removeEventListener("abort", stop);
+                controller.close();
+            }
+        },
+        cancel() {
+            abortController.abort();
+        },
+    });
+    return new Response(body, { headers: { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no" } });
+}
+/**
+ * Answer a waiting permission request. Returns false when there's no such
+ * request (already answered, the run ended, or it ran in another process) or
+ * `owner` doesn't match the run's owner.
+ *
+ *   // app/api/agent/approve/route.ts
+ *   export async function POST(request: Request) {
+ *     const { id, approved, reason } = await request.json()
+ *     return Response.json({ ok: answerClaudeAgentApproval(id, approved, reason, userId) })
+ *   }
+ */
+export function answerClaudeAgentApproval(id, approved, reason, owner) {
+    const request = waiting.get(id);
+    if (!request || (request.owner !== undefined && request.owner !== owner))
+        return false;
+    request.answer(approved, reason);
+    return true;
+}

package/dist/adapters/use-ag-ui.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+import { type RunAgentParameters } from "@ag-ui/client";
+import type { EntityRef } from "../lib/chat.js";
+import { type FromAgUiOptions } from "./ag-ui.js";
+export type UseAgUiOptions = Omit<FromAgUiOptions, "running" | "now"> & {
+    /** Your AG-UI endpoint (LangGraph, Mastra, CrewAI, Google ADK, Pydantic AI…). It receives a RunAgentInput and streams events back. */
+    url: string;
+    headers?: Record<string, string>;
+    /** Replaces the global fetch, e.g. to add auth or to play a script in tests and demos. */
+    fetch?: typeof fetch;
+    /** Continue an existing thread instead of starting a new one. */
+    threadId?: string;
+    /** Sent with every run as `forwardedProps`, next to the `references` the person mentioned. */
+    forwardedProps?: Record<string, unknown>;
+    /** Tools and context for every run, as AG-UI defines them. Candor doesn't run frontend tools for you. */
+    tools?: RunAgentParameters["tools"];
+    context?: RunAgentParameters["context"];
+};
+/**
+ * Wires an AG-UI agent to Candor: messages for <Thread>/<Message>, props for
+ * <Composer>, and the interrupts waiting on a person. The same shape as
+ * useClaudeAgent and useCandorChat, so screens work with any of them.
+ *
+ *   const { messages, composer, approvals, respond } = useAgUi({ url: "/api/agent", agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ *
+ * A run that ends on an interrupt shows it in `approvals`. `respond` records the
+ * answer, and once every open interrupt has one, starts the next run with
+ * `resume`: approved → `{ status: "resolved", payload: { approved: true } }`,
+ * denied → `{ status: "cancelled", payload: { approved: false, reason } }`.
+ * Mentions are sent as structured `forwardedProps.references`, not pasted into the text.
+ */
+export declare function useAgUi(options: UseAgUiOptions): {
+    messages: import("../index.js").MessageData[];
+    approvals: import("./ag-ui.js").AgUiApproval[];
+    respond: (interruptId: string, approved: boolean, reason?: string) => Promise<void>;
+    /** Tokens the runs reported, summed. AG-UI reports no cost. */
+    usage: import("./ag-ui.js").AgUiUsage | undefined;
+    /** Something the person should know that isn't part of a reply, such as an expired request. */
+    notice: string | undefined;
+    /** The request failed; say so, and let the person send again. */
+    error: string | undefined;
+    threadId: string | undefined;
+    /** Forget the conversation and start a new thread. */
+    reset: () => void;
+    composer: {
+        value: string;
+        onChange: React.Dispatch<React.SetStateAction<string>>;
+        state: "streaming" | "ready" | "sending";
+        references: EntityRef[];
+        onReferencesChange: React.Dispatch<React.SetStateAction<EntityRef[]>>;
+        onStop: () => void | undefined;
+        onSubmit: (text: string, refs: EntityRef[]) => void;
+    };
+};

package/dist/adapters/use-ag-ui.js

@@ -0,0 +1,168 @@
+import * as React from "react";
+import { HttpAgent, isInterruptExpired } from "@ag-ui/client";
+import { fromAgUiEvents } from "./ag-ui.js";
+/**
+ * Wires an AG-UI agent to Candor: messages for <Thread>/<Message>, props for
+ * <Composer>, and the interrupts waiting on a person. The same shape as
+ * useClaudeAgent and useCandorChat, so screens work with any of them.
+ *
+ *   const { messages, composer, approvals, respond } = useAgUi({ url: "/api/agent", agent })
+ *   <Thread footer={<Composer {...composer} />}>{messages.map((m) => <Message key={m.id} message={m} />)}</Thread>
+ *
+ * A run that ends on an interrupt shows it in `approvals`. `respond` records the
+ * answer, and once every open interrupt has one, starts the next run with
+ * `resume`: approved → `{ status: "resolved", payload: { approved: true } }`,
+ * denied → `{ status: "cancelled", payload: { approved: false, reason } }`.
+ * Mentions are sent as structured `forwardedProps.references`, not pasted into the text.
+ */
+export function useAgUi(options) {
+    const { url, headers, agent, toolTitle, fetch: fetcher, threadId, forwardedProps, tools, context } = options;
+    const [events, setEvents] = React.useState([]);
+    const [running, setRunning] = React.useState(false);
+    const [error, setError] = React.useState();
+    const [value, setValue] = React.useState("");
+    const [references, setReferences] = React.useState([]);
+    // Interrupts expire on the clock, not on an event; `now` moves when one does.
+    const [now, setNow] = React.useState(() => Date.now());
+    const run = React.useRef(null);
+    const client = React.useRef(null);
+    const answers = React.useRef(new Map());
+    const state = React.useMemo(() => fromAgUiEvents(events, { agent, toolTitle, running, now: new Date(now) }), [events, agent, toolTitle, running, now]);
+    const nextExpiry = state.approvals.reduce((soonest, a) => {
+        const at = a.expiresAt ? Date.parse(a.expiresAt) : NaN;
+        return Number.isNaN(at) ? soonest : Math.min(soonest ?? at, at);
+    }, undefined);
+    React.useEffect(() => {
+        if (nextExpiry === undefined)
+            return;
+        const timer = setTimeout(() => setNow(Date.now()), Math.max(0, nextExpiry - Date.now()) + 50);
+        return () => clearTimeout(timer);
+    }, [nextExpiry]);
+    // Stop the agent if the component goes away mid-run.
+    React.useEffect(() => () => run.current?.abort(), []);
+    const getClient = React.useCallback(() => {
+        if (!client.current)
+            client.current = new HttpAgent({ url, headers, fetch: fetcher, threadId });
+        const http = client.current;
+        // The latest options win, without losing the thread.
+        http.url = url;
+        http.headers = { ...headers };
+        if (fetcher)
+            http.fetch = fetcher;
+        return http;
+    }, [url, headers, fetcher, threadId]);
+    const start = React.useCallback(async (http, params, before) => {
+        const controller = new AbortController();
+        run.current = controller;
+        setError(undefined);
+        setRunning(true);
+        setEvents((e) => [...e, ...before]);
+        // Streamed text arrives a few characters at a time; apply it once per frame.
+        const pending = { events: [], frame: 0 };
+        const flush = () => {
+            pending.frame = 0;
+            const batch = pending.events.splice(0);
+            if (batch.length)
+                setEvents((e) => [...e, ...batch]);
+        };
+        try {
+            await http.runAgent({ resume: params.resume, tools, context, forwardedProps: { ...forwardedProps, references: params.references ?? [] }, abortController: controller }, {
+                onEvent: ({ event }) => {
+                    pending.events.push(event);
+                    pending.frame ||= requestAnimationFrame(flush);
+                },
+            });
+        }
+        catch (err) {
+            if (!controller.signal.aborted) {
+                const status = err.status;
+                const message = typeof status === "number" ? `The agent request failed (${status}).` : "The agent request failed, or its stream broke off.";
+                pending.events.push({ type: "candor_error", message });
+                setError(message);
+            }
+        }
+        finally {
+            cancelAnimationFrame(pending.frame);
+            flush();
+            run.current = null;
+            setRunning(false);
+        }
+    }, [tools, context, forwardedProps]);
+    const send = React.useCallback((text, refs) => {
+        if (run.current)
+            return;
+        const http = getClient();
+        // A new message moves on from any interrupt still open: the agent is told each was cancelled.
+        const reason = "The person sent a new message instead.";
+        const resume = http.pendingInterrupts.map((i) => ({ interruptId: i.id, status: "cancelled", payload: { approved: false, reason } }));
+        const closed = http.pendingInterrupts.map((i) => ({ type: "candor_answer", interruptId: i.id, approved: false, reason }));
+        answers.current.clear();
+        const id = crypto.randomUUID();
+        http.addMessage({ id, role: "user", content: text });
+        void start(http, { resume: resume.length ? resume : undefined, references: refs }, [...closed, { type: "candor_user", id, text, references: refs.length ? refs : undefined }]);
+    }, [getClient, start]);
+    const respond = React.useCallback(async (interruptId, approved, reason) => {
+        const http = client.current;
+        if (run.current || !http)
+            return;
+        const open = http.pendingInterrupts;
+        if (!open.some((i) => i.id === interruptId)) {
+            setError("That request is no longer open.");
+            return;
+        }
+        answers.current.set(interruptId, { approved, reason });
+        const answer = { type: "candor_answer", interruptId, approved, reason };
+        // The agent expects one answer for every open interrupt; wait for the rest.
+        if (open.some((i) => !answers.current.has(i.id) && !isInterruptExpired(i))) {
+            setEvents((e) => [...e, answer]);
+            return;
+        }
+        const resume = open.map((i) => resumeEntry(i, answers.current.get(i.id)));
+        answers.current.clear();
+        await start(http, { resume }, [answer]);
+    }, [start]);
+    const stop = React.useCallback(() => run.current?.abort(), []);
+    const composerState = running ? (state.messages.at(-1)?.author.role === "agent" ? "streaming" : "sending") : "ready";
+    return {
+        messages: state.messages,
+        approvals: state.approvals,
+        respond,
+        /** Tokens the runs reported, summed. AG-UI reports no cost. */
+        usage: state.usage,
+        /** Something the person should know that isn't part of a reply, such as an expired request. */
+        notice: state.notice,
+        /** The request failed; say so, and let the person send again. */
+        error,
+        threadId: state.threadId,
+        /** Forget the conversation and start a new thread. */
+        reset: () => {
+            run.current?.abort();
+            client.current = null;
+            answers.current.clear();
+            setEvents([]);
+            setError(undefined);
+        },
+        composer: {
+            value,
+            onChange: setValue,
+            state: composerState,
+            references,
+            onReferencesChange: setReferences,
+            onStop: stop,
+            onSubmit: (text, refs) => {
+                if (!text.trim() || running)
+                    return;
+                send(text, refs);
+                setValue("");
+                setReferences([]);
+            },
+        },
+    };
+}
+/** An expired interrupt can only be cancelled; the client refuses anything else. */
+function resumeEntry(i, answer) {
+    if (answer?.approved && !isInterruptExpired(i))
+        return { interruptId: i.id, status: "resolved", payload: { approved: true } };
+    const reason = answer ? answer.reason : "Nobody answered before it expired.";
+    return { interruptId: i.id, status: "cancelled", payload: { approved: false, ...(reason ? { reason } : {}) } };
+}