@candor-ui/react 1.3.0 → 1.7.0

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

@@ -1,5 +1,46 @@
-import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
-import type { AgentIdentity, EntityRef, Message } from "../lib/chat.js";
+import type { PermissionResult, PermissionUpdate, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentIdentity, EntityRef, Message, ToolSource } from "../lib/chat.js";
+/**
+ * How the agent's tool calls are approved, as the SDK names it: "default" (ask for anything not allowed already),
+ * "acceptEdits", "plan", "auto" (a classifier decides), "dontAsk" (deny what isn't allowed already) and
+ * "bypassPermissions". Kept open: a newer SDK's mode passes through as its name.
+ */
+export type ClaudePermissionMode = "default" | "acceptEdits" | "plan" | "auto" | "dontAsk" | "bypassPermissions" | (string & {});
+/** One of the agent's questions (the SDK's AskUserQuestion), shaped for ClarifyingQuestions. Options' ids are their labels. */
+export type ClaudeQuestion = {
+    /** The question's text, which is also how its answer is keyed back to the SDK. */
+    id: string;
+    kind: "choice";
+    prompt: string;
+    /** The SDK's short header ("Library", "Approach"). */
+    tag?: string | undefined;
+    options: {
+        id: string;
+        label: string;
+        detail?: string | undefined;
+    }[];
+    multiple: boolean;
+    /** The SDK always lets the person answer in their own words. */
+    other: true;
+};
+/** A person's answer to one ClaudeQuestion: the chosen labels, their own words, or both. Same shape as ClarifyingAnswer. */
+export type ClaudeQuestionAnswer = {
+    questionId: string;
+    choice?: string[] | undefined;
+    text?: string | undefined;
+};
+/** How a person answered a permission request. */
+export type ClaudeApprovalAnswer = {
+    approved: boolean;
+    /** Why it was denied, sent to the agent. */
+    reason?: string | undefined;
+    /** The tool's input as the person edited it before allowing it. The tool runs with exactly this. */
+    updatedInput?: Record<string, unknown> | undefined;
+    /** Answers to the agent's questions, when the request is one (`questions`). */
+    answers?: ClaudeQuestionAnswer[] | undefined;
+    /** Which of the request's `suggestions` the person chose to keep ("always allow"), by index. None unless they choose. */
+    alwaysAllow?: number[] | undefined;
+};
 /** Events of Candor's own, mixed into the SDK's stream. */
 export type CandorAgentEvent = 
 /** What the user sent. Added in the browser; the SDK doesn't echo a plain prompt back. */
@@ -7,7 +48,7 @@ export type CandorAgentEvent =
     type: "candor_user";
     id: string;
     text: string;
-    references?: EntityRef[];
+    references?: EntityRef[] | undefined;
 }
 /** A tool call is waiting for a person to allow or deny it. */
  | {
@@ -17,20 +58,55 @@ export type CandorAgentEvent =
     tool: string;
     input: unknown;
     /** The SDK's own sentence for the request, e.g. "Claude wants to edit notes.md". */
-    title?: string;
-    description?: string;
+    title?: string | undefined;
+    description?: string | undefined;
     /** Why the SDK asked, when it says. */
-    reason?: string;
-    blockedPath?: string;
+    reason?: string | undefined;
+    blockedPath?: string | undefined;
     /** Open on "Deny" and offer no one-key approve: the request grants more than it looks. */
-    defaultToNo?: boolean;
+    defaultToNo?: boolean | undefined;
+    /** A short name for the action: "Edit file". */
+    displayName?: string | undefined;
+    /**
+     * Rules the SDK suggests so this isn't asked again ("always allow"), as the SDK sends them. Offer them as a
+     * choice the person makes; never keep one unless they pick it.
+     */
+    suggestions?: PermissionUpdate[] | undefined;
+    /** Offer no "always allow" for this request: its rule would grant more than this one action. */
+    noAlwaysAllow?: boolean | undefined;
+    /** The permission mode the run was in when it asked. */
+    mode?: ClaudePermissionMode | undefined;
+    /** The agent's questions, when the tool is AskUserQuestion: answer them instead of allowing a tool. */
+    questions?: ClaudeQuestion[] | undefined;
+    /** Set when a subagent asked, with its id. */
+    agentId?: string | undefined;
+    /** For an MCP tool: its server's name and where that server was configured, as the SDK reports them. */
+    mcpServer?: {
+        name: string;
+        source: string;
+    } | undefined;
+    /** Whether the server lets a person edit this call's input before allowing it. False means no; left out means yes (1.5.0). */
+    editable?: boolean | undefined;
 }
 /** The request was answered, or the run ended before anyone did. */
  | {
     type: "candor_approval_closed";
     id: string;
     approved: boolean;
-    reason?: string;
+    reason?: string | undefined;
+    /** The person changed the input before allowing it. */
+    edited?: boolean | undefined;
+    /** The input the tool ran with, when the person edited it. */
+    input?: unknown;
+    /** Nobody answered in time (the server's `approvalTimeoutMs`). */
+    expired?: boolean | undefined;
+    /** How many "always allow" rules the person kept. */
+    kept?: number | undefined;
+}
+/** The run's permission mode changed, by the app (`setPermissionMode`). The SDK's own mode reports also count. */
+ | {
+    type: "candor_mode";
+    mode: ClaudePermissionMode;
 }
 /** A typed card for the app's card registry, sent by your server (a tool's result as a diff, a plan, a table). */
  | {
@@ -59,22 +135,55 @@ export type FromClaudeAgentOptions = {
     /** Who the agent is. Candor always names the agent. */
     agent: AgentIdentity;
     /** A request is open now: the last reply is still streaming and its approvals can be answered. */
-    running?: boolean;
+    running?: boolean | undefined;
     /** A plain-words title for a tool call: "Read notes.md". */
-    toolTitle?: (tool: string, input: unknown) => string | undefined;
+    toolTitle?: ((tool: string, input: unknown) => string | undefined) | undefined;
+    /**
+     * The sources a tool's result supports, for the reply's source list: `(tool, input, output) => [{ kind: "document",
+     * label: "Pricing policy v3" }]`. Read only from what the tool returned, never from numbers in the agent's text.
+     * Claude's own citations and web search results are read without it.
+     */
+    sourcesFrom?: ((tool: string, input: unknown, output: string) => ToolSource[] | undefined) | undefined;
 };
 export type ClaudeAgentState = {
     messages: Message[];
     /** Tool calls waiting on a person, oldest first. Empty once the request has ended. */
     approvals: ClaudeApproval[];
     /** Send it back with the next message to continue the same session (the SDK's `resume`). */
-    sessionId?: string;
-    usage?: ClaudeAgentUsage;
+    sessionId?: string | undefined;
+    usage?: ClaudeAgentUsage | undefined;
     /** A passing problem the agent is handling itself, such as a retried API call. */
-    notice?: string;
+    notice?: string | undefined;
+    /** The permission mode last reported, by the SDK or the app. Absent until one is. */
+    permissionMode?: ClaudePermissionMode | undefined;
 };
 /**
  * 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 declare function fromClaudeAgentEvents(events: AgentEvent[], options: FromClaudeAgentOptions): ClaudeAgentState;
+/**
+ * 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 declare function claudeQuestions(input: unknown): ClaudeQuestion[] | undefined;
+type Answerable = Pick<ClaudeApproval, "input" | "suggestions" | "noAlwaysAllow" | "questions">;
+/**
+ * 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 declare function claudePermissionResult(request: Answerable, answer: ClaudeApprovalAnswer): PermissionResult;
+/** A "don't ask again" rule in plain parts, for PermissionPrompt's `suggestions`. */
+export type ClaudeSuggestion = {
+    action: "allow" | "deny" | "ask" | "remove" | "mode" | "directories" | "other";
+    what: string;
+    scope?: string | undefined;
+};
+/**
+ * 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 declare function claudeSuggestions(updates: PermissionUpdate[] | undefined): ClaudeSuggestion[];
+export {};

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 };
+    });
+}