@candor-ui/react 1.1.0 → 1.5.0

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

@@ -1,5 +1,6 @@
-import { type Event } from "@ag-ui/core";
+import { type Event, type JsonPatch } from "@ag-ui/core";
 import type { AgentIdentity, EntityRef, Message } from "../lib/chat.js";
+import type { RunStatus } from "../lib/status.js";
 /** Events of Candor's own, mixed into the AG-UI stream by useAgUi. */
 export type CandorAgUiEvent = 
 /** What the user sent. Added in the browser, with the same id as the AG-UI user message. */
@@ -57,6 +58,49 @@ export type FromAgUiOptions = {
     toolTitle?: (tool: string, input: unknown) => string | undefined;
     /** The time to judge interrupt expiry by. Defaults to now. */
     now?: Date;
+    /** The state the first run started with; the first STATE_DELTA patches it. Defaults to `{}`, as AG-UI clients send. */
+    initialState?: unknown;
+    /** Other agents the app knows, by id. An activity naming an agent id not here (or `agent`) isn't mapped to an agent entry. */
+    agents?: AgentIdentity[];
+};
+/**
+ * A plan step read from an activity whose content has `steps: [{ title, status }]`.
+ * The same shape as PlanStep, so it can go straight to a plan view.
+ */
+export type AgUiPlanStep = {
+    id: string;
+    title: string;
+    status: RunStatus;
+    /** The step's own summary, when it sent one as text. */
+    summary?: string;
+    /** Why it failed: the agent's words, or a plain sentence saying it didn't say. Set only when status is "failed". */
+    failure?: string;
+};
+/**
+ * What an agent is doing, read from an activity whose content has `status`
+ * (and optionally `doing`, `since`, `agentId`). The same shape as AgentActivityEntry.
+ */
+export type AgUiAgentActivityEntry = {
+    /** The app's own identity for the agent, never one taken from the content. */
+    agent: AgentIdentity;
+    doing?: string;
+    status: RunStatus;
+    since?: string;
+};
+/** An activity the agent reported: structured progress that isn't part of a reply. */
+export type AgUiActivity = {
+    /** The activity message's id. */
+    id: string;
+    /** The agent's own kind for it, e.g. "plan" or "search". An open string. */
+    type: string;
+    /** Its content as the agent sent it, after any patches. Data, never markup. */
+    content: Record<string, unknown>;
+    /** Set when an update to it couldn't be applied: the content is the last good one, and may be behind. */
+    outOfDate?: string;
+    /** Its `steps` as plan steps, when every step has a title and a status Candor knows. */
+    plan?: AgUiPlanStep[];
+    /** Its `status`/`doing` as an agent entry, when the status is one Candor knows and the agent is one the app named. */
+    agentActivity?: AgUiAgentActivityEntry;
 };
 export type AgUiState = {
     messages: Message[];
@@ -67,9 +111,30 @@ export type AgUiState = {
     usage?: AgUiUsage;
     /** Something the person should know that isn't part of a reply, such as an expired request. */
     notice?: string;
+    /** The agent's shared state from STATE_SNAPSHOT and STATE_DELTA; undefined until the agent sends one. */
+    state?: unknown;
+    /** Set when a state update couldn't be applied: `state` is the last good value and may be behind. Cleared by the next snapshot. */
+    stateOutOfDate?: string;
+    /** The activities the agent reported, in the order they first arrived. */
+    activities: AgUiActivity[];
 };
 /**
  * Turns AG-UI events into Candor messages, waiting approvals and usage.
  * Pure (given `now`), so it can run on every render; useAgUi calls it for you.
  */
 export declare function fromAgUiEvents(events: AgUiEvent[], options: FromAgUiOptions): AgUiState;
+/** What applying a JSON Patch gave: the new document, or why it didn't apply (and then nothing changed). */
+export type JsonPatchResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Applies an RFC 6902 JSON Patch to a JSON document, all or nothing. Pure: the
+ * document passed in is never changed, and the result shares nothing with the
+ * patch's values. A patch that fails (a path that doesn't resolve, a failed
+ * `test`, a malformed operation) returns `ok: false` with a plain reason.
+ */
+export declare function applyJsonPatch(document: unknown, patch: JsonPatch | unknown): JsonPatchResult;

package/dist/adapters/ag-ui.js

@@ -18,6 +18,10 @@ export function fromAgUiEvents(events, options) {
     const subParents = new Map();
     /** Text messages from roles Candor doesn't show as the agent's (an echoed user, system or developer message). */
     const skipped = new Set();
+    let state;
+    let stateKnown = false;
+    let stateOutOfDate;
+    const activities = new Map();
     const current = (id) => {
         let turn = turns.at(-1);
         if (!turn)
@@ -174,7 +178,56 @@ export function fromAgUiEvents(events, options) {
             }
             case EventType.MESSAGES_SNAPSHOT:
                 turns = applySnapshot(turns, e.messages);
+                // Activities are part of the agent's record too; a snapshot's version of one replaces ours.
+                for (const m of e.messages) {
+                    if (m.role === "activity" && !m.subagentRunId && isRecord(m.content))
+                        activities.set(m.id, { type: m.activityType, content: m.content });
+                }
+                break;
+            case EventType.STATE_SNAPSHOT:
+                state = e.snapshot;
+                stateKnown = true;
+                stateOutOfDate = undefined;
                 break;
+            case EventType.STATE_DELTA: {
+                // After a patch that failed, later ones would patch the wrong base; wait for a snapshot.
+                if (stateOutOfDate)
+                    break;
+                const patched = applyJsonPatch(stateKnown ? state : (options.initialState ?? {}), e.delta);
+                if (patched.ok) {
+                    state = patched.value;
+                    stateKnown = true;
+                }
+                else
+                    stateOutOfDate = `An update to the agent’s state couldn’t be applied (${patched.reason}), so it may be out of date.`;
+                break;
+            }
+            case EventType.ACTIVITY_SNAPSHOT: {
+                const existing = activities.get(e.messageId);
+                // `replace: false` asks to keep what's there; it isn't a merge.
+                if (existing && e.replace === false)
+                    break;
+                if (isRecord(e.content))
+                    activities.set(e.messageId, { type: e.activityType, content: e.content });
+                break;
+            }
+            case EventType.ACTIVITY_DELTA: {
+                const existing = activities.get(e.messageId);
+                if (!existing) {
+                    activities.set(e.messageId, { type: e.activityType, content: {}, outOfDate: "An update arrived for an activity the agent never described." });
+                    break;
+                }
+                if (existing.outOfDate)
+                    break;
+                const patched = applyJsonPatch(existing.content, e.patch);
+                if (patched.ok && isRecord(patched.value))
+                    activities.set(e.messageId, { ...existing, content: patched.value });
+                else {
+                    const reason = patched.ok ? "the content stopped being an object" : patched.reason;
+                    activities.set(e.messageId, { ...existing, outOfDate: `An update to this activity couldn’t be applied (${reason}), so it may be out of date.` });
+                }
+                break;
+            }
             case EventType.CUSTOM: {
                 if (e.name !== "candor_card")
                     break;
@@ -183,7 +236,7 @@ export function fromAgUiEvents(events, options) {
                     current(`card-${turns.length}`).parts.push({ kind: "card", ...card });
                 break;
             }
-            // Steps, state, activity, raw events and encrypted reasoning are the app's or the agent's own business; nothing to show.
+            // Steps, raw events and encrypted reasoning are the app's or the agent's own business; nothing to show.
             default:
                 break;
         }
@@ -207,6 +260,9 @@ export function fromAgUiEvents(events, options) {
         notice: lapsed.length
             ? `${lapsed.length === 1 ? "A request" : `${lapsed.length} requests`} for your answer expired before anyone answered. Send a message to carry on; the agent will be told ${lapsed.length === 1 ? "it was" : "they were"} cancelled.`
             : undefined,
+        state,
+        stateOutOfDate,
+        activities: [...activities].map(([id, a]) => activity(id, a, options)),
     };
 }
 /* ---------------------------------------------------------------- building a reply */
@@ -396,6 +452,257 @@ function approval(i, findCall, o) {
         responseSchema: i.responseSchema,
     };
 }
+/* ---------------------------------------------------------------- activities */
+function activity(id, a, o) {
+    const out = { id, type: a.type, content: a.content };
+    if (a.outOfDate)
+        out.outOfDate = a.outOfDate;
+    const plan = planSteps(id, a.content);
+    if (plan)
+        out.plan = plan;
+    const entry = agentEntry(a.content, o);
+    if (entry)
+        out.agentActivity = entry;
+    return out;
+}
+/** Status words agents commonly send, as Candor's. Anything else is unknown and isn't mapped. */
+const statusWords = {
+    idle: "idle",
+    queued: "queued",
+    running: "running",
+    waiting: "waiting",
+    blocked: "blocked",
+    succeeded: "succeeded",
+    failed: "failed",
+    cancelled: "cancelled",
+    skipped: "skipped",
+    pending: "idle",
+    in_progress: "running",
+    "in-progress": "running",
+    completed: "succeeded",
+    complete: "succeeded",
+    done: "succeeded",
+    error: "failed",
+    canceled: "cancelled",
+};
+const runStatus = (v) => typeof v === "string" && Object.prototype.hasOwnProperty.call(statusWords, v.trim().toLowerCase()) ? statusWords[v.trim().toLowerCase()] : undefined;
+const textOf = (v) => (typeof v === "string" && v.trim() ? v : undefined);
+/** Plan steps, only when every step has a title and a known status: a plan with a step dropped would mislead. */
+function planSteps(id, content) {
+    const steps = content.steps;
+    if (!Array.isArray(steps) || !steps.length)
+        return undefined;
+    const out = [];
+    for (const [i, s] of steps.entries()) {
+        if (!isRecord(s))
+            return undefined;
+        const title = textOf(s.title);
+        const status = runStatus(s.status);
+        if (!title || !status)
+            return undefined;
+        const step = { id: textOf(s.id) ?? `${id}-${i}`, title, status };
+        const summary = textOf(s.summary);
+        if (summary)
+            step.summary = summary;
+        if (status === "failed")
+            step.failure = textOf(s.failure) ?? textOf(s.error) ?? "The agent didn’t say why this step failed.";
+        out.push(step);
+    }
+    return out;
+}
+/** An agent entry, only for a known status and an agent the app named. */
+function agentEntry(content, o) {
+    if (Array.isArray(content.steps))
+        return undefined;
+    const status = runStatus(content.status);
+    if (!status)
+        return undefined;
+    let agent = o.agent;
+    if (content.agentId !== undefined) {
+        agent = typeof content.agentId === "string" ? [o.agent, ...(o.agents ?? [])].find((a) => a.id === content.agentId) : undefined;
+        if (!agent)
+            return undefined;
+    }
+    const entry = { agent, status };
+    const doing = textOf(content.doing);
+    if (doing)
+        entry.doing = doing;
+    const since = textOf(content.since);
+    if (since && !Number.isNaN(Date.parse(since)))
+        entry.since = since;
+    return entry;
+}
+class PatchError extends Error {
+}
+/**
+ * Applies an RFC 6902 JSON Patch to a JSON document, all or nothing. Pure: the
+ * document passed in is never changed, and the result shares nothing with the
+ * patch's values. A patch that fails (a path that doesn't resolve, a failed
+ * `test`, a malformed operation) returns `ok: false` with a plain reason.
+ */
+export function applyJsonPatch(document, patch) {
+    if (!Array.isArray(patch))
+        return { ok: false, reason: "the patch isn’t a list of operations" };
+    let doc;
+    try {
+        doc = clone(document);
+        for (const [i, op] of patch.entries())
+            doc = applyOp(doc, op, i);
+    }
+    catch (err) {
+        if (err instanceof PatchError)
+            return { ok: false, reason: err.message };
+        // A document or value nested too deep to copy: refused like any other patch that can't apply.
+        if (err instanceof RangeError)
+            return { ok: false, reason: "the document is nested too deeply to patch" };
+        throw err;
+    }
+    return { ok: true, value: doc };
+}
+function applyOp(doc, op, i) {
+    const fail = (why) => {
+        throw new PatchError(`operation ${i + 1}: ${why}`);
+    };
+    if (!isRecord(op) || typeof op.op !== "string" || typeof op.path !== "string")
+        return fail("not an operation");
+    const path = pointer(op.path, fail);
+    const needsValue = op.op === "add" || op.op === "replace" || op.op === "test";
+    if (needsValue && !("value" in op))
+        return fail(`${op.op} has no value`);
+    switch (op.op) {
+        case "add":
+            return add(doc, path, clone(op.value), fail);
+        case "remove":
+            return remove(doc, path, fail).doc;
+        case "replace":
+            return replace(doc, path, clone(op.value), fail);
+        case "test":
+            if (!equal(get(doc, path, fail), op.value))
+                fail(`test failed at "${op.path}"`);
+            return doc;
+        case "move":
+        case "copy": {
+            if (typeof op.from !== "string")
+                return fail(`${op.op} has no from`);
+            const from = pointer(op.from, fail);
+            if (op.op === "move") {
+                if (op.from === op.path) {
+                    get(doc, from, fail);
+                    return doc;
+                }
+                if (op.path.startsWith(`${op.from}/`))
+                    fail("can’t move a value into itself");
+                const taken = remove(doc, from, fail);
+                return add(taken.doc, path, taken.value, fail);
+            }
+            return add(doc, path, clone(get(doc, from, fail)), fail);
+        }
+        default:
+            return fail(`unknown op "${op.op}"`);
+    }
+}
+/** RFC 6901: "" is the whole document; otherwise slash-separated tokens with ~1 for "/" and ~0 for "~". */
+function pointer(p, fail) {
+    if (p === "")
+        return [];
+    if (!p.startsWith("/"))
+        fail(`"${p}" isn’t a JSON Pointer`);
+    return p
+        .slice(1)
+        .split("/")
+        .map((t) => {
+        if (/~[^01]|~$/.test(t))
+            fail(`"${p}" has a bad escape`);
+        return t.replace(/~1/g, "/").replace(/~0/g, "~");
+    });
+}
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+/** Sets an own property even for keys like "__proto__", so a patch can't reach a prototype. */
+const put = (o, k, v) => Object.defineProperty(o, k, { value: v, writable: true, enumerable: true, configurable: true });
+function arrayIndex(a, token, adding, fail) {
+    if (adding && token === "-")
+        return a.length;
+    if (!/^(0|[1-9]\d*)$/.test(token))
+        fail(`"${token}" isn’t an array index`);
+    const n = Number(token);
+    if (n > a.length || (!adding && n === a.length))
+        fail(`index ${n} is past the end of the list`);
+    return n;
+}
+/** The container holding the last token, and that token. */
+function parentOf(doc, path, fail) {
+    const container = get(doc, path.slice(0, -1), fail);
+    if (!isRecord(container) && !Array.isArray(container))
+        fail(`"/${path.slice(0, -1).join("/")}" isn’t an object or a list`);
+    return { container: container, key: path.at(-1) };
+}
+function get(doc, path, fail) {
+    let at = doc;
+    for (const token of path) {
+        if (Array.isArray(at))
+            at = at[arrayIndex(at, token, false, fail)];
+        else if (isRecord(at) && own(at, token))
+            at = at[token];
+        else
+            fail(`nothing at "/${path.join("/")}"`);
+    }
+    return at;
+}
+function add(doc, path, value, fail) {
+    if (!path.length)
+        return value;
+    const { container, key } = parentOf(doc, path, fail);
+    if (Array.isArray(container))
+        container.splice(arrayIndex(container, key, true, fail), 0, value);
+    else
+        put(container, key, value);
+    return doc;
+}
+function replace(doc, path, value, fail) {
+    if (!path.length)
+        return value;
+    get(doc, path, fail);
+    const { container, key } = parentOf(doc, path, fail);
+    if (Array.isArray(container))
+        container[arrayIndex(container, key, false, fail)] = value;
+    else
+        put(container, key, value);
+    return doc;
+}
+function remove(doc, path, fail) {
+    if (!path.length)
+        return fail("can’t remove the whole document");
+    const { container, key } = parentOf(doc, path, fail);
+    if (Array.isArray(container))
+        return { doc, value: container.splice(arrayIndex(container, key, false, fail), 1)[0] };
+    if (!own(container, key))
+        fail(`nothing at "/${path.join("/")}"`);
+    const value = container[key];
+    delete container[key];
+    return { doc, value };
+}
+function clone(v) {
+    if (Array.isArray(v))
+        return v.map(clone);
+    if (isRecord(v)) {
+        const out = {};
+        for (const k of Object.keys(v))
+            put(out, k, clone(v[k]));
+        return out;
+    }
+    return v;
+}
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b))
+        return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => equal(x, b[i]));
+    if (!isRecord(a) || !isRecord(b))
+        return false;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((k) => own(b, k) && equal(a[k], b[k]));
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /* ---------------------------------------------------------------- helpers */
 const expired = (i, now) => i.expiresAt !== undefined && new Date(i.expiresAt).getTime() <= now.getTime();
 function runError(message) {

package/dist/adapters/ai-sdk.d.ts

@@ -1,5 +1,5 @@
 import type { UIMessage } from "ai";
-import type { AgentIdentity, Message } from "../lib/chat.js";
+import type { AgentIdentity, Message, ToolSource } from "../lib/chat.js";
 import { inline, markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
 export { inline, markdownBlocks, plainBlocks };
 export type FromAiSdkOptions = {
@@ -13,6 +13,11 @@ export type FromAiSdkOptions = {
     toolTitle?: (tool: string, input: unknown) => string | undefined;
     /** The text version of a data part, used when its card can't be shown. */
     summarize?: (name: string, data: unknown) => string;
+    /**
+     * The sources a tool's result supports, added to the reply's sources after the SDK's own source parts:
+     * `(tool, input, output) => [{ kind: "document", label: "Refund policy v2" }]`. Read only from the tool's output.
+     */
+    sourcesFrom?: (tool: string, input: unknown, output: unknown) => ToolSource[] | undefined;
 };
 /** Convert a whole useChat message list. */
 export declare function fromAiSdkMessages(messages: UIMessage[], options: FromAiSdkOptions): Message[];

package/dist/adapters/ai-sdk.js

@@ -11,6 +11,8 @@ export function fromAiSdkMessage(message, options) {
     const blocks = [];
     const reasoning = [];
     const sources = [];
+    const toolSources = [];
+    const toolSourceKeys = new Set();
     let tools = null;
     const flushTools = () => {
         if (tools?.length)
@@ -20,7 +22,18 @@ export function fromAiSdkMessage(message, options) {
     for (const part of message.parts) {
         if (part.type === "dynamic-tool" || part.type.startsWith("tool-")) {
             tools ??= [];
-            tools.push(toolCall(part, options));
+            const call = toolCall(part, options);
+            tools.push(call);
+            const p = part;
+            if (call.status === "succeeded" && options.sourcesFrom) {
+                for (const { key, ...found } of options.sourcesFrom(call.tool, p.input, p.output) ?? []) {
+                    const k = key ?? `${found.kind}:${found.label}`;
+                    if (toolSourceKeys.has(k))
+                        continue;
+                    toolSourceKeys.add(k);
+                    toolSources.push(found);
+                }
+            }
             continue;
         }
         flushTools();
@@ -55,6 +68,8 @@ export function fromAiSdkMessage(message, options) {
         }
     }
     flushTools();
+    for (const [i, found] of toolSources.entries())
+        sources.push({ ...found, id: `${message.id}-tool-s${i + 1}`, marker: sources.length + 1 });
     const author = message.role === "assistant" ? { role: "agent", agent: options.agent } : message.role === "user" ? { role: "user" } : { role: "system" };
     return {
         id: message.id,
@@ -104,6 +119,8 @@ function toolCall(p, options) {
         output: p.output === undefined ? undefined : json(p.output),
         outputLanguage: p.output === undefined || typeof p.output === "string" ? "text" : "json",
         error: status === "failed" ? (p.errorText ?? "The tool failed and didn’t say why.") : status === "cancelled" && p.approval?.reason ? `Denied: ${p.approval.reason}` : undefined,
+        // Only a decided approval says who decided; one still waiting is the person's to make.
+        approval: p.approval?.approved === true ? { by: p.approval.isAutomatic ? "automatic" : "person", note: p.approval.reason || undefined } : undefined,
     };
 }
 const json = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 2));

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;
+    options: {
+        id: string;
+        label: string;
+        detail?: string;
+    }[];
+    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[];
+    text?: string;
+};
+/** How a person answered a permission request. */
+export type ClaudeApprovalAnswer = {
+    approved: boolean;
+    /** Why it was denied, sent to the agent. */
+    reason?: string;
+    /** The tool's input as the person edited it before allowing it. The tool runs with exactly this. */
+    updatedInput?: Record<string, unknown>;
+    /** Answers to the agent's questions, when the request is one (`questions`). */
+    answers?: ClaudeQuestionAnswer[];
+    /** Which of the request's `suggestions` the person chose to keep ("always allow"), by index. None unless they choose. */
+    alwaysAllow?: number[];
+};
 /** 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. */
@@ -24,6 +65,28 @@ export type CandorAgentEvent =
     blockedPath?: string;
     /** Open on "Deny" and offer no one-key approve: the request grants more than it looks. */
     defaultToNo?: boolean;
+    /** A short name for the action: "Edit file". */
+    displayName?: string;
+    /**
+     * 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[];
+    /** Offer no "always allow" for this request: its rule would grant more than this one action. */
+    noAlwaysAllow?: boolean;
+    /** The permission mode the run was in when it asked. */
+    mode?: ClaudePermissionMode;
+    /** The agent's questions, when the tool is AskUserQuestion: answer them instead of allowing a tool. */
+    questions?: ClaudeQuestion[];
+    /** Set when a subagent asked, with its id. */
+    agentId?: string;
+    /** For an MCP tool: its server's name and where that server was configured, as the SDK reports them. */
+    mcpServer?: {
+        name: string;
+        source: string;
+    };
+    /** 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;
 }
 /** The request was answered, or the run ended before anyone did. */
  | {
@@ -31,6 +94,19 @@ export type CandorAgentEvent =
     id: string;
     approved: boolean;
     reason?: string;
+    /** The person changed the input before allowing it. */
+    edited?: boolean;
+    /** The input the tool ran with, when the person edited it. */
+    input?: unknown;
+    /** Nobody answered in time (the server's `approvalTimeoutMs`). */
+    expired?: boolean;
+    /** How many "always allow" rules the person kept. */
+    kept?: number;
+}
+/** 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). */
  | {
@@ -62,6 +138,12 @@ export type FromClaudeAgentOptions = {
     running?: boolean;
     /** A plain-words title for a tool call: "Read notes.md". */
     toolTitle?: (tool: string, input: unknown) => string | 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;
 };
 export type ClaudeAgentState = {
     messages: Message[];
@@ -72,9 +154,36 @@ export type ClaudeAgentState = {
     usage?: ClaudeAgentUsage;
     /** A passing problem the agent is handling itself, such as a retried API call. */
     notice?: string;
+    /** The permission mode last reported, by the SDK or the app. Absent until one is. */
+    permissionMode?: ClaudePermissionMode;
 };
 /**
  * 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;
+};
+/**
+ * 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 {};