@candor-ui/react 1.3.0 → 1.5.0

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

@@ -13,7 +13,8 @@ export function fromClaudeAgentEvents(events, options) {
     let usage;
     let lastCost = 0;
     let notice;
-    const current = (id) => (reply ??= { id, parts: [], reasoning: [], tools: new Map(), live: new Map() });
+    let permissionMode;
+    const current = (id) => (reply ??= { id, parts: [], reasoning: [], tools: new Map(), live: new Map(), sources: new Map(), inputs: new Map() });
     const close = (last) => {
         if (reply)
             messages.push(render(reply, { ...options, model, last }));
@@ -43,11 +44,24 @@ export function fromClaudeAgentEvents(events, options) {
                 const call = approval && reply?.tools.get(approval.toolUseId);
                 if (call && call.status === "waiting") {
                     call.status = e.approved ? "running" : "cancelled";
-                    if (!e.approved)
+                    if (e.expired)
+                        call.error = `Expired: ${e.reason ?? "nobody answered in time."}`;
+                    else if (!e.approved)
                         call.error = e.reason ? `Denied: ${e.reason}` : "Denied.";
+                    // What ran is what the person allowed, so the card shows it, with what the agent proposed kept beside it.
+                    if (e.approved && e.input !== undefined) {
+                        call.approval = { by: "person", originalInput: call.input };
+                        call.input = json(e.input);
+                        reply.inputs.set(call.id, e.input);
+                    }
+                    else if (e.approved)
+                        call.approval = { by: "person" };
                 }
                 break;
             }
+            case "candor_mode":
+                permissionMode = e.mode;
+                break;
             case "candor_card":
                 current(`card-${messages.length}`).parts.push({ kind: "card", card: e.card, props: e.props, summary: e.summary });
                 break;
@@ -59,6 +73,12 @@ export function fromClaudeAgentEvents(events, options) {
                 if (e.subtype === "init") {
                     sessionId = e.session_id;
                     model = e.model;
+                    if (e.permissionMode)
+                        permissionMode = e.permissionMode;
+                }
+                else if (e.subtype === "status") {
+                    if (e.permissionMode)
+                        permissionMode = e.permissionMode;
                 }
                 else if (e.subtype === "permission_denied") {
                     const call = reply?.tools.get(e.tool_use_id);
@@ -117,6 +137,9 @@ export function fromClaudeAgentEvents(events, options) {
                     call.status = block.is_error ? "failed" : "succeeded";
                     if (block.is_error)
                         call.error = firstLine(output) ?? "The tool failed and didn’t say why.";
+                    else if (options.sourcesFrom)
+                        for (const found of options.sourcesFrom(call.tool, reply.inputs.get(call.id), output) ?? [])
+                            addSource(reply, found);
                 }
                 break;
             }
@@ -146,12 +169,40 @@ export function fromClaudeAgentEvents(events, options) {
         sessionId,
         usage,
         notice: options.running ? notice : undefined,
+        permissionMode,
     };
 }
+/** Adds a source once (by key) and returns its id. Markers count up in the order sources first appear. */
+function addSource(r, source) {
+    const { key: own, ...rest } = source;
+    const key = own ?? `${rest.kind}:${rest.label}`;
+    const known = r.sources.get(key);
+    if (known)
+        return known.id;
+    const id = `${r.id}-s${r.sources.size + 1}`;
+    r.sources.set(key, { ...rest, id, marker: r.sources.size + 1 });
+    return id;
+}
+/** One of Claude's citations as a source: a web page by its address, a document or search result by its title. */
+function citationSource(c) {
+    const snippet = c.cited_text?.trim() ? clip(c.cited_text.trim(), 280) : undefined;
+    if (c.url)
+        return { key: `web:${c.url}`, kind: "web", label: c.title || c.url, origin: host(c.url), snippet };
+    const title = c.document_title ?? c.title ?? c.source;
+    if (title)
+        return { key: `document:${title}`, kind: "document", label: title, snippet };
+    return undefined;
+}
 function addBlock(r, block, options) {
     if (block.type === "text") {
-        if (block.text.trim())
-            r.parts.push({ kind: "text", text: block.text });
+        if (!block.text.trim())
+            return;
+        // Claude's citations point at what it read; the [n] comes from them, never from numbers in the text.
+        const cites = (block.citations ?? []).flatMap((c) => {
+            const source = citationSource(c);
+            return source ? [addSource(r, source)] : [];
+        });
+        r.parts.push({ kind: "text", text: block.text, cites: cites.length ? [...new Set(cites)] : undefined });
     }
     else if (block.type === "thinking") {
         // With the SDK's default display, thinking arrives empty; there's nothing to show then.
@@ -161,6 +212,7 @@ function addBlock(r, block, options) {
     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.inputs.set(block.id, block.input);
         r.parts.push({ kind: "tool", id: block.id });
     }
     else if ("tool_use_id" in block) {
@@ -174,6 +226,13 @@ function addBlock(r, block, options) {
             call.outputLanguage = "json";
             if (failed)
                 call.error = `The tool failed: ${String(content.error_code)}.`;
+            // Web search results are sources the reply can stand on, whether or not the text cites them.
+            if (!failed && block.type === "web_search_tool_result" && Array.isArray(content)) {
+                for (const item of content) {
+                    if (item.type === "web_search_result" && item.url)
+                        addSource(r, { key: `web:${item.url}`, kind: "web", label: item.title || item.url, origin: host(item.url) });
+                }
+            }
         }
     }
 }
@@ -210,7 +269,7 @@ function render(r, o) {
         if (p.kind === "card")
             blocks.push({ kind: "card", card: p.card, props: p.props, summary: p.summary });
         else
-            blocks.push(...markdownBlocks(p.text));
+            blocks.push(...withCitations(markdownBlocks(p.text), p.cites));
     }
     flush();
     const error = r.failure ?? r.result?.error;
@@ -222,6 +281,7 @@ function render(r, o) {
         status: open ? "streaming" : r.result?.ok ? "complete" : error ? "failed" : "interrupted",
         blocks,
         reasoning: reasoning.length ? reasoning : undefined,
+        sources: r.sources.size ? [...r.sources.values()] : 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,
     };
 }
@@ -251,6 +311,84 @@ function resultText(content) {
     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 clip = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+const host = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Puts a text block's [n] markers at its end: after the last paragraph's, heading's or list item's words. */
+function withCitations(blocks, cites) {
+    if (!cites?.length)
+        return blocks;
+    const marks = cites.map((sourceId) => ({ kind: "citation", sourceId }));
+    const out = [...blocks];
+    for (let i = out.length - 1; i >= 0; i--) {
+        const b = out[i];
+        if (b.kind === "paragraph" || b.kind === "heading") {
+            out[i] = { ...b, nodes: [...b.nodes, ...marks] };
+            return out;
+        }
+        if (b.kind === "list" && b.items.length) {
+            out[i] = { ...b, items: [...b.items.slice(0, -1), [...b.items.at(-1), ...marks]] };
+            return out;
+        }
+    }
+    // Only code or plain text: the markers get a line of their own.
+    return [...out, { kind: "paragraph", nodes: marks }];
+}
+/**
+ * The questions in an AskUserQuestion call, ready for ClarifyingQuestions; undefined when the input isn't one.
+ * Option ids are their labels, which is what the SDK takes back.
+ */
+export function claudeQuestions(input) {
+    const qs = input?.questions;
+    if (!Array.isArray(qs) || !qs.length)
+        return undefined;
+    const out = [];
+    for (const q of qs) {
+        if (typeof q?.question !== "string" || !Array.isArray(q.options))
+            return undefined;
+        out.push({
+            id: q.question,
+            kind: "choice",
+            prompt: q.question,
+            tag: typeof q.header === "string" && q.header ? q.header : undefined,
+            options: q.options.filter((o) => typeof o?.label === "string").map((o) => ({ id: o.label, label: o.label, detail: o.description || undefined })),
+            multiple: q.multiSelect === true,
+            other: true,
+        });
+    }
+    return out;
+}
+/**
+ * What to hand back to the SDK for a person's answer: the `PermissionResult` canUseTool resolves with. Pure, so it
+ * works wherever the answer lands (your own route, a queue, a workflow signal). Questions become AskUserQuestion's
+ * `answers`, keyed by question text, several choices joined with ", " and the person's own words used as they are.
+ * Only the suggestions the person picked are kept, and none when the request offers no "always allow".
+ */
+export function claudePermissionResult(request, answer) {
+    if (!answer.approved) {
+        return { behavior: "deny", message: answer.reason ? `The user declined: ${answer.reason}` : "The user declined this action." };
+    }
+    const input = (request.input && typeof request.input === "object" ? request.input : {});
+    let updatedInput = answer.updatedInput ?? input;
+    if (request.questions) {
+        const answers = {};
+        for (const q of request.questions) {
+            const a = answer.answers?.find((x) => x.questionId === q.id);
+            const words = [...(a?.choice ?? []).filter((c) => q.options.some((o) => o.id === c)), ...(a?.text?.trim() ? [a.text.trim()] : [])];
+            if (words.length)
+                answers[q.id] = words.join(", ");
+        }
+        updatedInput = { ...input, answers };
+    }
+    const kept = request.noAlwaysAllow ? [] : [...new Set(answer.alwaysAllow ?? [])].flatMap((i) => (request.suggestions?.[i] ? [request.suggestions[i]] : []));
+    return { behavior: "allow", updatedInput, ...(kept.length && { updatedPermissions: kept }) };
+}
 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] ?? "";
@@ -263,3 +401,23 @@ function reasoningEntry(id, text, streaming) {
         assumption: "The model’s own reasoning; nothing checked it.",
     };
 }
+const scopes = { session: "session", localSettings: "local", projectSettings: "project", userSettings: "user", cliArg: "session" };
+/**
+ * The SDK's suggested permission updates as plain parts PermissionPrompt shows, in the same order, so the indexes a
+ * person ticks are the ones `alwaysAllow` sends back.
+ */
+export function claudeSuggestions(updates) {
+    return (updates ?? []).map((u) => {
+        const scope = scopes[u.destination] ?? u.destination;
+        if (u.type === "setMode")
+            return { action: "mode", what: u.mode, scope };
+        if (u.type === "addDirectories")
+            return { action: "directories", what: u.directories.join(", "), scope };
+        if (u.type === "removeDirectories")
+            return { action: "other", what: u.directories.join(", "), scope };
+        const what = u.rules.map((r) => (r.ruleContent ? `${r.toolName}(${r.ruleContent})` : r.toolName)).join(", ");
+        if (u.type === "removeRules")
+            return { action: "remove", what, scope };
+        return { action: u.behavior, what, scope };
+    });
+}

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

@@ -1,5 +1,123 @@
-import type { CanUseTool, Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
-import type { AgentEvent } from "./claude-agent-sdk.js";
+import type { CanUseTool, PermissionMode, Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type AgentEvent, type ClaudeApproval, type ClaudeApprovalAnswer, type ClaudePermissionMode } from "./claude-agent-sdk.js";
+import type { EntityRef } from "../lib/chat.js";
+/** A permission request as a store keeps it. */
+export type StoredApproval = {
+    id: string;
+    /** The run it belongs to, when the run has an id. */
+    runId?: string;
+    /** Who may answer it; checked by answerClaudeApproval. */
+    owner?: string;
+    request: ClaudeApproval;
+    createdAt: string;
+    /** Set once answered. Recorded, not necessarily used: a run that stopped at the same moment still denies the tool. */
+    answer?: ClaudeApprovalAnswer & {
+        at: string;
+    };
+    /** Set when nobody can answer any more (the run ended or stopped), with why. */
+    closed?: {
+        at: string;
+        reason: string;
+    };
+};
+/**
+ * Where waiting permission requests live. Answering and closing each happen once: whichever comes first wins, so a
+ * late answer to a run that already ended returns false instead of being lost. A store backed by a database does
+ * both as one conditional update (`… where answered_at is null and closed_at is null`).
+ */
+export interface ApprovalStore {
+    /** Record a request that waits on a person. */
+    put(approval: StoredApproval): Promise<void>;
+    get(id: string): Promise<StoredApproval | undefined>;
+    /** Record the answer. False when there's no such request, or it was already answered or closed. */
+    answer(id: string, answer: ClaudeApprovalAnswer): Promise<boolean>;
+    /** Mark that it can't be answered any more. False when it was answered first. */
+    close(id: string, reason: string): Promise<boolean>;
+    /**
+     * Resolves with the answer once there is one, or undefined once it's closed or `signal` aborts. When `signal`
+     * aborts first, close the request in the same step ("The run was stopped."), so an answer arriving just after is
+     * refused instead of recorded for a tool that never ran. A store with no way to push can poll with waitByPolling.
+     */
+    wait(id: string, signal: AbortSignal): Promise<ClaudeApprovalAnswer | undefined>;
+    /** Requests still waiting, oldest first, for one run or all: what to show again after a reload. */
+    pending(runId?: string): Promise<StoredApproval[]>;
+}
+/**
+ * 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 declare function memoryApprovalStore({ keepMs }?: {
+    keepMs?: number;
+}): ApprovalStore;
+/** A `wait` for stores that can't push: reads the request every `intervalMs` (1s) until it's answered or closed. */
+export declare function waitByPolling(get: (id: string) => Promise<StoredApproval | undefined>, id: string, signal: AbortSignal, intervalMs?: number): Promise<ClaudeApprovalAnswer | undefined>;
+export type ClaudeCanUseToolOptions = {
+    /** Where requests wait. Defaults to this process's memory. */
+    approvals?: ApprovalStore;
+    /** Sends each request, and its closing, to whoever shows it (the browser, your event log). */
+    emit: (event: AgentEvent) => void;
+    /** Who may answer. */
+    owner?: string;
+    /** The run's id, kept with each request. */
+    runId?: string;
+    /** The run's permission mode now, recorded on each request. */
+    mode?: () => ClaudePermissionMode | undefined;
+    /** Called with each request's id as it starts waiting and once it's settled, e.g. to close the rest when the run ends. */
+    track?: {
+        add(id: string): void;
+        delete(id: string): void;
+    };
+    /**
+     * Which tools' input a person may edit before allowing it (`updatedInput`). Every tool by default, as in 1.5.0;
+     * an answer that edits a tool this refuses is rejected by answerClaudeApproval, whatever the browser sends.
+     */
+    editable?: (tool: string, input: unknown) => boolean;
+    /** Close a request nobody answered after this long, as expired: the tool is denied, never allowed. No limit by default. */
+    approvalTimeoutMs?: number;
+};
+/**
+ * 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 declare function claudeCanUseTool({ approvals, emit, owner, runId, mode, track, editable, approvalTimeoutMs }: ClaudeCanUseToolOptions): CanUseTool;
+/**
+ * A run's events, kept so a browser can re-attach after a reload and a finished run can be replayed. `read` returns
+ * the events from index `from` on, and whether the run has ended.
+ */
+export interface ClaudeRunStore {
+    /**
+     * Begin a run, with who started it. streamClaudeAgent calls it first. An append, end or subscribe for a run that
+     * was never started (or was already forgotten) must do nothing rather than create it, so a forgotten run can't
+     * come back without its owner.
+     */
+    start?(runId: string, owner?: string): Promise<void>;
+    append(runId: string, event: AgentEvent): Promise<void>;
+    end(runId: string): Promise<void>;
+    read(runId: string, from: number): Promise<{
+        events: AgentEvent[];
+        ended: boolean;
+    } | undefined>;
+    /** Called when the run has new events or ends. Optional: without it, attaching polls `read`. */
+    subscribe?(runId: string, listener: () => void): () => void;
+    /** Who started the run, when it was started with an owner; attachClaudeAgentRun checks it. */
+    ownerOf?(runId: string): Promise<string | undefined>;
+    /** Record the run's owner. Kept from 1.5.0; prefer `start`. */
+    setOwner?(runId: string, owner: string): Promise<void>;
+}
+/**
+ * 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 declare function memoryRunStore({ maxRuns, maxEvents }?: {
+    maxRuns?: number;
+    maxEvents?: number;
+}): ClaudeRunStore;
+/** Which permission modes a run may be switched to: a list, or a test. */
+export type ModePolicy = readonly PermissionMode[] | ((mode: PermissionMode) => boolean);
 export type RunClaudeAgent = (tools: {
     /** Pass to query()'s `canUseTool`, so permission requests reach the person. */
     canUseTool: CanUseTool;
@@ -10,11 +128,13 @@ export type RunClaudeAgent = (tools: {
      * It renders through the app's card registry, in the reply where it was sent.
      */
     emit: (event: AgentEvent) => void;
+    /** This run's id: the same one the response's `x-candor-run-id` header carries. */
+    runId: string;
 }) => Query;
 export type StreamClaudeAgentOptions = {
-    /** The incoming request's signal (`request.signal`): the agent stops when the browser goes away. */
+    /** The incoming request's signal (`request.signal`): the agent stops when the browser goes away, unless `detach`. */
     signal?: AbortSignal;
-    /** Who may answer this run's permission requests, e.g. the signed-in user's id. Checked by answerClaudeAgentApproval. */
+    /** Who may answer this run's permission requests, e.g. the signed-in user's id. Checked when they're answered. */
     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;
@@ -24,6 +144,36 @@ export type StreamClaudeAgentOptions = {
      * in hand is still sent, and nothing after it.
      */
     onMessage?: (message: SDKMessage) => void | Promise<void>;
+    /** Called with every event the browser gets, in order, e.g. to keep the whole conversation for replay. */
+    onEvent?: (event: AgentEvent) => void | Promise<void>;
+    /** Where permission requests wait. Defaults to this process's memory. */
+    approvals?: ApprovalStore;
+    /** Keeps the run's events so a browser can re-attach (attachClaudeAgentRun). Without it, a reload loses the run. */
+    runs?: ClaudeRunStore;
+    /** The run's id; a new one by default. Sent back in the `x-candor-run-id` header. */
+    runId?: string;
+    /**
+     * Keep running when the browser goes away (a reload, a closed tab), so it can re-attach. Stop it with
+     * stopClaudeAgentRun. Needs a process that outlives the response: not a serverless function that's frozen when
+     * the response ends.
+     */
+    detach?: boolean;
+    /**
+     * What the person sent, recorded as the run's first event in `runs`, so a re-attached browser shows it. Pass the
+     * `promptId` useClaudeAgent sends as `id`: a browser that re-attaches with `initialEvents` then replaces the run's
+     * events instead of adding them again.
+     */
+    prompt?: {
+        id: string;
+        text: string;
+        references?: EntityRef[];
+    };
+    /** Which tools' input a person may edit before allowing it. Every tool by default. See claudeCanUseTool. */
+    editable?: ClaudeCanUseToolOptions["editable"];
+    /** Close a permission request nobody answered after this long, as expired (denied). No limit by default; set one with `detach`. */
+    approvalTimeoutMs?: number;
+    /** The permission modes setClaudeAgentPermissionMode may switch this run to. Any mode by default. */
+    modes?: ModePolicy;
 };
 /**
  * Run an agent and stream it to useClaudeAgent.
@@ -38,16 +188,51 @@ export type StreamClaudeAgentOptions = {
  *     )
  *   }
  */
-export declare function streamClaudeAgent(run: RunClaudeAgent, { signal, owner, describeError, onMessage }?: StreamClaudeAgentOptions): Response;
+export declare function streamClaudeAgent(run: RunClaudeAgent, { signal, owner, describeError, onMessage, onEvent, approvals, runs, runId, detach, prompt, editable, approvalTimeoutMs, modes }?: StreamClaudeAgentOptions): Response;
+/**
+ * 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 declare function attachClaudeAgentRun(runs: ClaudeRunStore, runId: string, { from, owner, signal, pollMs }?: {
+    from?: number;
+    owner?: string;
+    signal?: AbortSignal;
+    pollMs?: number;
+}): Promise<Response>;
+/** Stop a run this process is running. False when it isn't running here, or `owner` didn't start it. */
+export declare function stopClaudeAgentRun(runId: string, owner?: string): boolean;
 /**
- * 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.
+ * 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 declare function setClaudeAgentPermissionMode(runId: string, mode: PermissionMode, owner?: string, { allowed }?: {
+    allowed?: ModePolicy;
+}): Promise<boolean>;
+/**
+ * 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 declare function answerClaudeApproval(approvals: ApprovalStore, id: string, answer: ClaudeApprovalAnswer, { owner }?: {
+    owner?: string;
+}): Promise<boolean>;
+/**
+ * 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 declare function answerClaudeAgentApproval(id: string, approved: boolean, reason?: string, owner?: string): boolean;