@candor-ui/react 1.3.0 → 1.7.0

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

@@ -1,4 +1,248 @@
-const waiting = new Map();
+import { claudePermissionResult, claudeQuestions, } from "./claude-agent-sdk.js";
+/**
+ * The default ApprovalStore: this process's memory. Answered and closed requests are forgotten after `keepMs`
+ * (10 minutes), so it doesn't grow without bound.
+ */
+export function memoryApprovalStore({ keepMs = 10 * 60_000 } = {}) {
+    const items = new Map();
+    const waiters = new Map();
+    const wake = (id) => {
+        for (const w of waiters.get(id) ?? [])
+            w();
+        waiters.delete(id);
+    };
+    const forget = (id) => setTimeout(() => items.delete(id), keepMs).unref?.();
+    const now = () => new Date().toISOString();
+    const answer = (id, a) => {
+        const item = items.get(id);
+        if (!item || item.answer || item.closed)
+            return false;
+        item.answer = { ...structuredClone(a), at: now() };
+        wake(id);
+        forget(id);
+        return true;
+    };
+    const store = {
+        async put(approval) {
+            items.set(approval.id, structuredClone(approval));
+        },
+        async get(id) {
+            const a = items.get(id);
+            return a && structuredClone(a);
+        },
+        async answer(id, a) {
+            return answer(id, a);
+        },
+        async close(id, reason) {
+            const a = items.get(id);
+            if (!a || a.answer || a.closed)
+                return false;
+            a.closed = { at: now(), reason };
+            wake(id);
+            forget(id);
+            return true;
+        },
+        wait(id, signal) {
+            return new Promise((resolve) => {
+                const settle = () => {
+                    signal.removeEventListener("abort", onAbort);
+                    waiters.get(id)?.delete(settle);
+                    const a = items.get(id);
+                    resolve(a?.answer ? stripAt(a.answer) : undefined);
+                };
+                // Stopped before an answer: closed in the same step, so a late answer is refused rather than recorded.
+                const onAbort = () => {
+                    const a = items.get(id);
+                    if (a && !a.answer && !a.closed) {
+                        a.closed = { at: now(), reason: "The run was stopped." };
+                        forget(id);
+                    }
+                    settle();
+                };
+                const a = items.get(id);
+                if (!a || a.answer || a.closed)
+                    return settle();
+                if (signal.aborted)
+                    return onAbort();
+                let set = waiters.get(id);
+                if (!set)
+                    waiters.set(id, (set = new Set()));
+                set.add(settle);
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+        },
+        async pending(runId) {
+            return [...items.values()].filter((a) => !a.answer && !a.closed && (runId === undefined || a.runId === runId)).map((a) => structuredClone(a));
+        },
+    };
+    synchronous.set(store, { get: (id) => items.get(id), answer });
+    return store;
+}
+/** The memory store's own synchronous calls, so the 1.4 answer function can stay synchronous. */
+const synchronous = new WeakMap();
+const stripAt = (stored) => {
+    const answer = { ...stored };
+    delete answer.at;
+    return answer;
+};
+/** A `wait` for stores that can't push: reads the request every `intervalMs` (1s) until it's answered or closed. */
+export async function waitByPolling(get, id, signal, intervalMs = 1000) {
+    while (!signal.aborted) {
+        const a = await get(id);
+        if (!a || a.closed)
+            return undefined;
+        if (a.answer)
+            return stripAt(a.answer);
+        await new Promise((resolve) => {
+            const timer = setTimeout(done, intervalMs);
+            function done() {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", done);
+                resolve();
+            }
+            signal.addEventListener("abort", done, { once: true });
+        });
+    }
+    return undefined;
+}
+/** The store streamClaudeAgent and answerClaudeAgentApproval use when you don't pass one. */
+const defaultApprovals = memoryApprovalStore();
+/**
+ * A canUseTool that keeps each request in an ApprovalStore and waits for its answer from wherever it's given: your
+ * route, a queue, a workflow signal (`approvals.answer(id, { approved: true })`). Use it on its own when your agent
+ * runs somewhere other than streamClaudeAgent. When the SDK stops waiting, the request is closed, so a late answer
+ * is refused rather than lost.
+ */
+export function claudeCanUseTool({ approvals = defaultApprovals, emit, owner, runId, mode, track, editable, approvalTimeoutMs }) {
+    return async (tool, input, request) => {
+        const id = crypto.randomUUID();
+        const questions = tool === "AskUserQuestion" ? claudeQuestions(input) : undefined;
+        const approval = {
+            id,
+            toolUseId: request.toolUseID,
+            tool,
+            input,
+            title: request.title,
+            description: request.description,
+            reason: request.decisionReason,
+            blockedPath: request.blockedPath,
+            defaultToNo: request.defaultToNo,
+            displayName: request.displayName,
+            // A question has no rule to remember; and a request that mustn't offer one gets none.
+            suggestions: questions || request.suppressAlwaysAllowRule ? undefined : request.suggestions,
+            noAlwaysAllow: request.suppressAlwaysAllowRule || undefined,
+            mode: mode?.(),
+            questions,
+            agentId: request.agentID,
+            mcpServer: request.mcpServer,
+            // A question's answers aren't an edit; otherwise the server's policy decides, and the browser can't widen it.
+            editable: questions ? false : editable ? editable(tool, input) : true,
+        };
+        await approvals.put({ id, runId, owner, request: approval, createdAt: new Date().toISOString() });
+        track?.add(id);
+        emit({ type: "candor_approval", ...approval });
+        const timer = approvalTimeoutMs ? setTimeout(() => void approvals.close(id, EXPIRED), approvalTimeoutMs) : undefined;
+        const answer = await approvals.wait(id, request.signal);
+        clearTimeout(timer);
+        track?.delete(id);
+        if (!answer || request.signal.aborted) {
+            const stored = await approvals.get(id);
+            const reason = request.signal.aborted
+                ? stored?.answer
+                    ? "The run stopped before the answer could be used."
+                    : "The run was stopped."
+                : (stored?.closed?.reason ?? "The run ended.");
+            await approvals.close(id, reason);
+            emit({ type: "candor_approval_closed", id, approved: false, reason, expired: reason === EXPIRED || undefined });
+            return { behavior: "deny", message: reason, interrupt: request.signal.aborted };
+        }
+        const edited = answer.approved && answer.updatedInput !== undefined;
+        emit({
+            type: "candor_approval_closed",
+            id,
+            approved: answer.approved,
+            reason: answer.reason,
+            edited: edited || undefined,
+            // What actually ran, so the tool card and a replay show it rather than what the agent proposed.
+            input: edited ? answer.updatedInput : undefined,
+            kept: answer.alwaysAllow?.length || undefined,
+        });
+        return claudePermissionResult(approval, answer);
+    };
+}
+const EXPIRED = "Nobody answered in time.";
+/**
+ * The default ClaudeRunStore: this process's memory. It keeps at most `maxRuns` finished runs (100), forgetting the
+ * oldest finished one first; a run still going is never forgotten. Each run keeps at most `maxEvents` events
+ * (5,000): past that, partial-text events are no longer kept (the finished message still is), so a re-attached
+ * browser sees text arrive a message at a time instead of as it streams.
+ */
+export function memoryRunStore({ maxRuns = 100, maxEvents = 5000 } = {}) {
+    const runs = new Map();
+    const notify = (id) => runs.get(id)?.listeners.forEach((l) => l());
+    const forgetFinished = () => {
+        // Oldest first: Map keeps insertion order. Runs still going are skipped, so their owner is never lost.
+        for (const [id, r] of runs) {
+            if (runs.size <= maxRuns)
+                return;
+            if (r.ended)
+                runs.delete(id);
+        }
+    };
+    const start = (id, owner) => {
+        const r = runs.get(id);
+        if (r) {
+            if (owner !== undefined && r.owner === undefined)
+                r.owner = owner;
+            return;
+        }
+        runs.set(id, { events: [], ended: false, owner, listeners: new Set() });
+        forgetFinished();
+    };
+    return {
+        async start(id, owner) {
+            start(id, owner);
+        },
+        async append(id, event) {
+            const r = runs.get(id);
+            if (!r || r.ended)
+                return;
+            if (r.events.length >= maxEvents && event.type === "stream_event")
+                return;
+            r.events.push(event);
+            notify(id);
+        },
+        async end(id) {
+            const r = runs.get(id);
+            if (!r)
+                return;
+            r.ended = true;
+            notify(id);
+            forgetFinished();
+        },
+        async read(id, from) {
+            const r = runs.get(id);
+            return r && { events: r.events.slice(Math.max(0, from)), ended: r.ended };
+        },
+        subscribe(id, listener) {
+            const r = runs.get(id);
+            if (!r)
+                return () => { };
+            r.listeners.add(listener);
+            return () => r.listeners.delete(listener);
+        },
+        async ownerOf(id) {
+            return runs.get(id)?.owner;
+        },
+        async setOwner(id, owner) {
+            start(id, owner);
+        },
+    };
+}
+/* ---------------------------------------------------------------- streaming a run */
+/** Runs started by this process, so stop and the mode switch can reach them. */
+const live = new Map();
+const permits = (policy, mode) => (!policy ? true : typeof policy === "function" ? policy(mode) : policy.includes(mode));
 /**
  * Run an agent and stream it to useClaudeAgent.
  *
@@ -12,52 +256,61 @@ const waiting = new Map();
  *     )
  *   }
  */
-export function streamClaudeAgent(run, { signal, owner, describeError, onMessage } = {}) {
+export function streamClaudeAgent(run, { signal, owner, describeError, onMessage, onEvent, approvals = defaultApprovals, runs, runId = crypto.randomUUID(), detach = false, prompt, editable, approvalTimeoutMs, modes } = {}) {
     const encoder = new TextEncoder();
     const abortController = new AbortController();
     const mine = new Set();
+    let mode;
     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,
-        });
-    });
+    // Keeps the record in the order the browser saw it, even when the stores are slow.
+    let recorded = Promise.resolve();
+    const record = (event) => {
+        recorded = recorded.then(async () => {
+            await runs?.append(runId, event);
+            await onEvent?.(event);
+        }).catch((error) => console.error("Recording a Claude agent event failed:", error));
+    };
+    const emit = (event) => {
+        if (event.type === "candor_mode")
+            mode = event.mode;
+        else if (event.type === "system" && (event.subtype === "init" || event.subtype === "status") && event.permissionMode)
+            mode = event.permissionMode;
+        record(event);
+        send(event);
+    };
+    const canUseTool = claudeCanUseTool({ approvals, emit, owner, runId, mode: () => mode, track: mine, editable, approvalTimeoutMs });
     const body = new ReadableStream({
         async start(controller) {
             let open = true;
             send = (event) => {
-                if (open)
+                if (!open)
+                    return;
+                try {
                     controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+                }
+                catch {
+                    // The browser went away mid-run and the run carries on (detach): later events go only to the run store.
+                    open = false;
+                }
             };
             const stop = () => abortController.abort();
-            signal?.addEventListener("abort", stop, { once: true });
+            if (!detach)
+                signal?.addEventListener("abort", stop, { once: true });
+            if (runs?.start)
+                await runs.start(runId, owner);
+            else if (owner !== undefined)
+                await runs?.setOwner?.(runId, owner);
+            if (prompt)
+                record({ type: "candor_user", ...prompt });
+            const entry = { owner, abort: abortController, emit, query: undefined, modes };
+            live.set(runId, entry);
             try {
-                for await (const message of run({ canUseTool, abortController, emit: (event) => send(event) })) {
+                const query = run({ canUseTool, abortController, emit, runId });
+                entry.query = query;
+                for await (const message of query) {
                     // Awaited, so bookkeeping such as recording spend finishes before the next message is handled.
                     await onMessage?.(message);
-                    send(message);
+                    emit(message);
                     // Stopped (the browser went away, or onMessage or a tool aborted the run): nothing more is sent.
                     if (abortController.signal.aborted)
                         break;
@@ -66,39 +319,185 @@ export function streamClaudeAgent(run, { signal, owner, describeError, onMessage
             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." });
+                    emit({ type: "candor_error", message: describeError?.(error) ?? "The agent stopped because of an error on the server." });
                 }
             }
             finally {
+                live.delete(runId);
                 // Nobody can answer once the run is over.
-                for (const id of [...mine])
-                    waiting.get(id)?.answer(false, "The run ended.");
+                await Promise.all([...mine].map((id) => approvals.close(id, "The run ended.")));
+                await recorded;
+                await runs?.end(runId);
                 open = false;
                 signal?.removeEventListener("abort", stop);
-                controller.close();
+                try {
+                    controller.close();
+                }
+                catch {
+                    /* already closed by the browser going away */
+                }
             }
         },
         cancel() {
-            abortController.abort();
+            // The browser stopped reading. With detach, the run goes on and the browser can re-attach.
+            if (!detach)
+                abortController.abort();
+        },
+    });
+    return new Response(body, {
+        headers: { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no", "x-candor-run-id": runId },
+    });
+}
+/**
+ * Stream a run's events again, from index `from`, then live until it ends: for a browser re-attaching after a
+ * reload. 404 when the store doesn't know the run, 403 when `owner` isn't who started it.
+ *
+ *   // app/api/agent/[runId]/route.ts
+ *   export async function GET(request: Request, { params }) {
+ *     const from = Number(new URL(request.url).searchParams.get("from") ?? 0)
+ *     return attachClaudeAgentRun(runs, (await params).runId, { from, owner: userId, signal: request.signal })
+ *   }
+ */
+export async function attachClaudeAgentRun(runs, runId, { from = 0, owner, signal, pollMs = 500 } = {}) {
+    const first = await runs.read(runId, 0);
+    if (!first)
+        return Response.json({ error: "No such run." }, { status: 404 });
+    const startedBy = await runs.ownerOf?.(runId);
+    if (startedBy !== undefined && startedBy !== owner)
+        return Response.json({ error: "Not your run." }, { status: 403 });
+    const encoder = new TextEncoder();
+    let next = Number.isSafeInteger(from) && from > 0 ? from : 0;
+    const body = new ReadableStream({
+        async start(controller) {
+            let wake = () => { };
+            // Set by every notification, so one that lands while a read is under way isn't lost to the wait after it.
+            let dirty = false;
+            const unsubscribe = runs.subscribe?.(runId, () => {
+                dirty = true;
+                wake();
+            });
+            try {
+                while (!signal?.aborted) {
+                    dirty = false;
+                    const page = await runs.read(runId, next);
+                    if (!page)
+                        break;
+                    for (const event of page.events)
+                        controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+                    next += page.events.length;
+                    if (page.ended)
+                        break;
+                    if (dirty)
+                        continue;
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(done, unsubscribe ? 30_000 : pollMs);
+                        function done() {
+                            clearTimeout(timer);
+                            signal?.removeEventListener("abort", done);
+                            resolve();
+                        }
+                        wake = done;
+                        signal?.addEventListener("abort", done, { once: true });
+                    });
+                }
+            }
+            catch {
+                /* the browser went away */
+            }
+            finally {
+                unsubscribe?.();
+                try {
+                    controller.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            }
         },
     });
-    return new Response(body, { headers: { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no" } });
+    return new Response(body, { headers: { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store", "x-accel-buffering": "no", "x-candor-run-id": runId } });
+}
+/** Stop a run this process is running. False when it isn't running here, or `owner` didn't start it. */
+export function stopClaudeAgentRun(runId, owner) {
+    const run = live.get(runId);
+    if (!run || (run.owner !== undefined && run.owner !== owner))
+        return false;
+    run.abort.abort();
+    return true;
+}
+/**
+ * Change a running agent's permission mode (the SDK's `setPermissionMode`), and tell the browser. Only for a query
+ * in streaming input mode, as the SDK requires. False when the run isn't here, `owner` didn't start it, the mode
+ * isn't allowed, or the SDK refused. The route is where policy is enforced: a mode PermissionMode shows as locked
+ * must be left out of `allowed` (or the run's `modes`) too, since anyone can post to the route directly.
+ */
+export async function setClaudeAgentPermissionMode(runId, mode, owner, { allowed } = {}) {
+    const run = live.get(runId);
+    if (!run?.query || (run.owner !== undefined && run.owner !== owner))
+        return false;
+    if (!permits(run.modes, mode) || !permits(allowed, mode))
+        return false;
+    try {
+        await run.query.setPermissionMode(mode);
+    }
+    catch {
+        return false;
+    }
+    run.emit({ type: "candor_mode", mode });
+    return true;
 }
+/* ---------------------------------------------------------------- answering */
+const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
 /**
- * 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.
+ * Check an answer from the browser against the request it answers, and record it. False when there's no such
+ * request, it's already settled, `owner` isn't the run's owner, or the answer doesn't fit the request (an edited
+ * input that isn't an object, answers to a request that isn't a question, a suggestion that wasn't offered).
  *
  *   // 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) })
+ *     const { id, ...answer } = await request.json()
+ *     return Response.json({ ok: await answerClaudeApproval(approvals, id, answer, { owner: userId }) })
  *   }
  */
+export async function answerClaudeApproval(approvals, id, answer, { owner } = {}) {
+    const clean = checkAnswer(await approvals.get(id), answer, owner);
+    return clean ? approvals.answer(id, clean) : false;
+}
+/** The answer as it will be recorded, or null when it doesn't fit the request or the viewer may not give it. */
+function checkAnswer(stored, answer, owner) {
+    if (!stored || stored.answer || stored.closed)
+        return null;
+    if (stored.owner !== undefined && stored.owner !== owner)
+        return null;
+    if (typeof answer?.approved !== "boolean")
+        return null;
+    const r = stored.request;
+    if (answer.updatedInput !== undefined && (!isPlainObject(answer.updatedInput) || r.questions || r.editable === false))
+        return null;
+    if (answer.answers !== undefined && (!r.questions || !Array.isArray(answer.answers)))
+        return null;
+    if (answer.alwaysAllow !== undefined) {
+        const offered = r.noAlwaysAllow ? 0 : (r.suggestions?.length ?? 0);
+        if (!Array.isArray(answer.alwaysAllow) || answer.alwaysAllow.some((i) => !Number.isInteger(i) || i < 0 || i >= offered))
+            return null;
+    }
+    if (answer.reason != null && typeof answer.reason !== "string")
+        return null;
+    return {
+        approved: answer.approved,
+        ...(answer.reason && { reason: answer.reason.slice(0, 2000) }),
+        ...(answer.approved && answer.updatedInput && { updatedInput: answer.updatedInput }),
+        ...(answer.approved && answer.answers && { answers: answer.answers }),
+        ...(answer.approved && answer.alwaysAllow?.length && { alwaysAllow: answer.alwaysAllow }),
+    };
+}
+/**
+ * Answer a waiting permission request in the default, in-memory store. Kept from 1.4; answerClaudeApproval takes a
+ * store and the full answer (an edited input, answers to questions, "always allow"). Returns false when there's no
+ * such request, or `owner` doesn't match the run's owner.
+ */
 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;
+    const memory = synchronous.get(defaultApprovals);
+    const clean = checkAnswer(memory.get(id), { approved, reason }, owner);
+    return clean ? memory.answer(id, clean) : false;
 }

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

@@ -5,16 +5,16 @@ 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>;
+    headers?: Record<string, string> | undefined;
     /** Replaces the global fetch, e.g. to add auth or to play a script in tests and demos. */
-    fetch?: typeof fetch;
+    fetch?: typeof fetch | undefined;
     /** Continue an existing thread instead of starting a new one. */
-    threadId?: string;
+    threadId?: string | undefined;
     /** Sent with every run as `forwardedProps`, next to the `references` the person mentioned. */
-    forwardedProps?: Record<string, unknown>;
+    forwardedProps?: Record<string, unknown> | undefined;
     /** 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"];
+    tools?: RunAgentParameters["tools"] | undefined;
+    context?: RunAgentParameters["context"] | undefined;
 };
 /**
  * Wires an AG-UI agent to Candor: messages for <Thread>/<Message>, props for
@@ -41,6 +41,12 @@ export declare function useAgUi(options: UseAgUiOptions): {
     /** The request failed; say so, and let the person send again. */
     error: string | undefined;
     threadId: string | undefined;
+    /** The agent's shared state (STATE_SNAPSHOT/STATE_DELTA); undefined until it sends one. */
+    state: unknown;
+    /** Set, with the reason, when a state update couldn't be applied and `state` may be behind. */
+    stateOutOfDate: string | undefined;
+    /** The activities the agent reported, in order, with plan steps and agent entries where they map. */
+    activities: import("./ag-ui.js").AgUiActivity[];
     /** Forget the conversation and start a new thread. */
     reset: () => void;
     composer: {

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

@@ -16,7 +16,7 @@ import { fromAgUiEvents } from "./ag-ui.js";
  * 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 { url, headers, agent, agents, toolTitle, fetch: fetcher, threadId, forwardedProps, tools, context, initialState } = options;
     const [events, setEvents] = React.useState([]);
     const [running, setRunning] = React.useState(false);
     const [error, setError] = React.useState();
@@ -27,7 +27,7 @@ export function useAgUi(options) {
     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 state = React.useMemo(() => fromAgUiEvents(events, { agent, agents, toolTitle, running, now: new Date(now), initialState }), [events, agent, agents, toolTitle, running, now, initialState]);
     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);
@@ -42,7 +42,13 @@ export function useAgUi(options) {
     React.useEffect(() => () => run.current?.abort(), []);
     const getClient = React.useCallback(() => {
         if (!client.current)
-            client.current = new HttpAgent({ url, headers, fetch: fetcher, threadId });
+            client.current = new HttpAgent({
+                url,
+                ...(headers && { headers }),
+                ...(fetcher && { fetch: fetcher }),
+                ...(threadId !== undefined && { threadId }),
+                ...(initialState !== undefined && { initialState }),
+            });
         const http = client.current;
         // The latest options win, without losing the thread.
         http.url = url;
@@ -50,7 +56,7 @@ export function useAgUi(options) {
         if (fetcher)
             http.fetch = fetcher;
         return http;
-    }, [url, headers, fetcher, threadId]);
+    }, [url, headers, fetcher, threadId, initialState]);
     const start = React.useCallback(async (http, params, before) => {
         const controller = new AbortController();
         run.current = controller;
@@ -66,7 +72,13 @@ export function useAgUi(options) {
                 setEvents((e) => [...e, ...batch]);
         };
         try {
-            await http.runAgent({ resume: params.resume, tools, context, forwardedProps: { ...forwardedProps, references: params.references ?? [] }, abortController: controller }, {
+            await http.runAgent({
+                ...(params.resume && { resume: params.resume }),
+                ...(tools && { tools }),
+                ...(context && { context }),
+                forwardedProps: { ...forwardedProps, references: params.references ?? [] },
+                abortController: controller,
+            }, {
                 onEvent: ({ event }) => {
                     pending.events.push(event);
                     pending.frame ||= requestAnimationFrame(flush);
@@ -134,6 +146,12 @@ export function useAgUi(options) {
         /** The request failed; say so, and let the person send again. */
         error,
         threadId: state.threadId,
+        /** The agent's shared state (STATE_SNAPSHOT/STATE_DELTA); undefined until it sends one. */
+        state: state.state,
+        /** Set, with the reason, when a state update couldn't be applied and `state` may be behind. */
+        stateOutOfDate: state.stateOutOfDate,
+        /** The activities the agent reported, in order, with plan steps and agent entries where they map. */
+        activities: state.activities,
         /** Forget the conversation and start a new thread. */
         reset: () => {
             run.current?.abort();

package/dist/adapters/use-candor-chat.d.ts

@@ -8,7 +8,7 @@ export type PendingApproval = {
     toolCallId: string;
     tool: string;
     input: unknown;
-    reason?: string;
+    reason?: string | undefined;
 };
 /**
  * Wires a `useChat()` result to Candor: messages for <Thread>/<Message>, props