@candor-ui/react 0.0.0-stage → 1.0.1

package/dist/adapters/ag-ui.js

@@ -0,0 +1,441 @@
+import { EventType } from "@ag-ui/core";
+import { markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+/**
+ * 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 function fromAgUiEvents(events, options) {
+    const now = options.now ?? new Date();
+    let turns = [];
+    let threadId;
+    let usage;
+    /** Interrupts from the latest run that ended on one, until the next run starts. */
+    let open = [];
+    const answers = new Map();
+    // Subagent traffic, by what it opened. Continuations may omit the tag, so ownership is remembered.
+    const subMessages = new Set();
+    const subTools = new Set();
+    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();
+    const current = (id) => {
+        let turn = turns.at(-1);
+        if (!turn)
+            turns.push((turn = {}));
+        return (turn.reply ??= emptyReply(id));
+    };
+    const findCall = (id) => {
+        for (let i = turns.length - 1; i >= 0; i--) {
+            const call = turns[i].reply?.tools.get(id);
+            if (call)
+                return call;
+        }
+        return undefined;
+    };
+    const addUsage = (entries, r) => {
+        for (const u of entries ?? []) {
+            usage ??= {};
+            if (u.inputTokens !== undefined)
+                usage.inputTokens = (usage.inputTokens ?? 0) + u.inputTokens;
+            if (u.outputTokens !== undefined)
+                usage.outputTokens = (usage.outputTokens ?? 0) + u.outputTokens;
+            if (r && u.model)
+                r.model ??= u.model;
+        }
+    };
+    for (const e of events) {
+        if (e.type === EventType.SUBAGENT_ERROR) {
+            // A subagent that failed is reported where it started: on its parent tool call.
+            const parent = subParents.get(e.subagentRunId);
+            const call = parent ? findCall(parent) : undefined;
+            if (call && call.status === "running") {
+                call.status = "failed";
+                call.error = `A subagent failed: ${(firstLine(e.message) ?? "it didn’t say why").replace(/[.!]$/, "")}.`;
+            }
+            continue;
+        }
+        if (isSubagent(e, subMessages, subTools, subParents))
+            continue;
+        switch (e.type) {
+            case "candor_user":
+                turns.push({ user: { id: e.id, author: { role: "user" }, status: "complete", blocks: plainBlocks(e.text) } });
+                break;
+            case "candor_answer": {
+                answers.set(e.interruptId, { approved: e.approved, reason: e.reason });
+                const interrupt = open.find((i) => i.id === e.interruptId);
+                const call = interrupt?.toolCallId ? findCall(interrupt.toolCallId) : undefined;
+                if (call && call.status === "waiting") {
+                    call.status = e.approved ? "running" : "cancelled";
+                    if (!e.approved)
+                        call.error = e.reason ? `Denied: ${e.reason}` : "Denied.";
+                }
+                break;
+            }
+            case "candor_error":
+                // The first failure is the one that explains what happened.
+                current(`error-${turns.length}`).failure ??= e.message;
+                break;
+            case EventType.RUN_STARTED: {
+                threadId = e.threadId;
+                open = [];
+                const r = current(e.runId);
+                r.outcome = undefined;
+                r.aborted = false;
+                break;
+            }
+            case EventType.RUN_FINISHED: {
+                threadId = e.threadId;
+                const r = current(e.runId);
+                const outcome = e.outcome?.type ?? "success";
+                r.outcome = outcome;
+                addUsage(e.usage, r);
+                if (e.outcome?.type === "interrupt") {
+                    open = e.outcome.interrupts;
+                    for (const i of open) {
+                        const call = i.toolCallId ? findCall(i.toolCallId) : undefined;
+                        if (call && (call.status === "running" || call.status === "waiting")) {
+                            call.status = "waiting";
+                            call.interruptId = i.id;
+                        }
+                    }
+                }
+                break;
+            }
+            case EventType.RUN_ERROR: {
+                const r = current(`error-${turns.length}`);
+                addUsage(e.usage, r);
+                // @ag-ui/client reports a stopped request as a RUN_ERROR with code "abort": that's the person stopping it, not a failure.
+                if (e.code === "abort")
+                    r.aborted = true;
+                else
+                    r.failure ??= runError(e.message);
+                break;
+            }
+            case EventType.TEXT_MESSAGE_START:
+                if (e.role && e.role !== "assistant")
+                    skipped.add(e.messageId);
+                else
+                    addText(current(e.messageId), e.messageId, "");
+                break;
+            case EventType.TEXT_MESSAGE_CONTENT:
+                if (!skipped.has(e.messageId))
+                    addText(current(e.messageId), e.messageId, e.delta);
+                break;
+            case EventType.TEXT_MESSAGE_CHUNK: {
+                if ((e.role && e.role !== "assistant") || (e.messageId && skipped.has(e.messageId))) {
+                    if (e.messageId)
+                        skipped.add(e.messageId);
+                    break;
+                }
+                const r = current(e.messageId ?? `text-${turns.length}`);
+                // A chunk without an id continues the last text message.
+                const id = e.messageId ?? [...r.texts.keys()].at(-1) ?? `${r.id}-text`;
+                addText(r, id, e.delta ?? "");
+                break;
+            }
+            case EventType.TOOL_CALL_START:
+                addTool(current(e.parentMessageId ?? e.toolCallId), e.toolCallId, e.toolCallName);
+                break;
+            case EventType.TOOL_CALL_ARGS: {
+                const call = findCall(e.toolCallId);
+                if (call)
+                    call.args += e.delta;
+                break;
+            }
+            case EventType.TOOL_CALL_CHUNK: {
+                if (!e.toolCallId)
+                    break;
+                const call = findCall(e.toolCallId) ?? addTool(current(e.parentMessageId ?? e.toolCallId), e.toolCallId, e.toolCallName ?? "tool");
+                call.args += e.delta ?? "";
+                break;
+            }
+            case EventType.TOOL_CALL_RESULT: {
+                const call = findCall(e.toolCallId);
+                // A denied or expired call stays as the person left it, whatever the agent reports afterwards.
+                if (!call || call.status === "cancelled")
+                    break;
+                call.output = resultText(e.content) || undefined;
+                call.status = "succeeded";
+                break;
+            }
+            case EventType.REASONING_MESSAGE_START:
+                current(e.messageId).reasoning.set(e.messageId, "");
+                break;
+            case EventType.REASONING_MESSAGE_CONTENT: {
+                const r = current(e.messageId);
+                r.reasoning.set(e.messageId, (r.reasoning.get(e.messageId) ?? "") + e.delta);
+                break;
+            }
+            case EventType.REASONING_MESSAGE_CHUNK: {
+                const r = current(e.messageId ?? `reasoning-${turns.length}`);
+                const id = e.messageId ?? [...r.reasoning.keys()].at(-1) ?? `${r.id}-reasoning`;
+                r.reasoning.set(id, (r.reasoning.get(id) ?? "") + (e.delta ?? ""));
+                break;
+            }
+            case EventType.MESSAGES_SNAPSHOT:
+                turns = applySnapshot(turns, e.messages);
+                break;
+            case EventType.CUSTOM: {
+                if (e.name !== "candor_card")
+                    break;
+                const card = cardValue(e.value);
+                if (card)
+                    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.
+            default:
+                break;
+        }
+    }
+    const lastReply = turns.findLastIndex((t) => t.reply);
+    const isOpen = (i) => !answers.has(i.id) && !expired(i, now);
+    const messages = [];
+    turns.forEach((t, i) => {
+        if (t.user)
+            messages.push(t.user);
+        if (t.reply)
+            messages.push(render(t.reply, { ...options, now, last: i === lastReply, open: open.filter(isOpen) }));
+    });
+    const waiting = options.running ? [] : open.filter(isOpen);
+    const lapsed = options.running ? [] : open.filter((i) => !answers.has(i.id) && expired(i, now));
+    return {
+        messages,
+        approvals: waiting.map((i) => approval(i, findCall, options)),
+        threadId,
+        usage,
+        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,
+    };
+}
+/* ---------------------------------------------------------------- building a reply */
+const emptyReply = (id) => ({ id, parts: [], texts: new Map(), reasoning: new Map(), tools: new Map() });
+function addText(r, id, delta) {
+    if (!r.texts.has(id))
+        r.parts.push({ kind: "text", id });
+    r.texts.set(id, (r.texts.get(id) ?? "") + delta);
+}
+function addTool(r, id, tool) {
+    const existing = r.tools.get(id);
+    if (existing)
+        return existing;
+    const call = { id, tool, args: "", status: "running" };
+    r.tools.set(id, call);
+    r.parts.push({ kind: "tool", id });
+    return call;
+}
+/** True for anything a subagent sent, tagged or continuing something a subagent opened. */
+function isSubagent(e, messages, tools, parents) {
+    if (e.type === EventType.SUBAGENT_STARTED) {
+        if (e.parentToolCallId)
+            parents.set(e.subagentRunId, e.parentToolCallId);
+        return true;
+    }
+    if (e.type === EventType.SUBAGENT_FINISHED)
+        return true;
+    const tagged = "subagentRunId" in e && !!e.subagentRunId;
+    const messageId = "messageId" in e ? e.messageId : undefined;
+    const toolCallId = "toolCallId" in e ? e.toolCallId : undefined;
+    const parent = "parentMessageId" in e ? e.parentMessageId : undefined;
+    if (tagged || (messageId && messages.has(messageId)) || (toolCallId && tools.has(toolCallId)) || (parent && messages.has(parent))) {
+        if (messageId && e.type !== EventType.TOOL_CALL_RESULT)
+            messages.add(messageId);
+        if (toolCallId)
+            tools.add(toolCallId);
+        return true;
+    }
+    return false;
+}
+/**
+ * A snapshot is the agent's own record of the thread, so it replaces what the
+ * stream built: its user messages start turns, everything after each one is
+ * that turn's reply. What only Candor knew about a reply (its cards, how its
+ * run ended, a denial) is kept when the snapshot still has the same user message.
+ */
+function applySnapshot(previous, snapshot) {
+    const byUser = new Map(previous.filter((t) => t.user).map((t) => [t.user.id, t.reply]));
+    const turns = previous[0] && !previous[0].user ? [{ reply: previous[0].reply }] : [];
+    const seen = new Set();
+    for (const m of snapshot) {
+        if (m.subagentRunId)
+            continue;
+        if (m.role === "user") {
+            turns.push({ user: { id: m.id, author: { role: "user" }, status: "complete", blocks: plainBlocks(resultText(m.content)) }, reply: byUser.get(m.id) });
+            continue;
+        }
+        if (m.role !== "assistant" && m.role !== "tool" && m.role !== "reasoning")
+            continue;
+        let t = turns.at(-1);
+        if (!t)
+            turns.push((t = {}));
+        // A reply the stream never saw is history the agent already finished.
+        const r = (t.reply ??= { ...emptyReply(m.id), outcome: "success" });
+        if (m.role === "assistant") {
+            if (m.content !== undefined) {
+                if (!r.texts.has(m.id))
+                    r.parts.push({ kind: "text", id: m.id });
+                r.texts.set(m.id, m.content);
+                seen.add(m.id);
+            }
+            for (const tc of m.toolCalls ?? []) {
+                const call = addTool(r, tc.id, tc.function.name);
+                call.tool = tc.function.name;
+                call.args = tc.function.arguments;
+                seen.add(tc.id);
+            }
+        }
+        else if (m.role === "tool") {
+            const call = r.tools.get(m.toolCallId);
+            if (!call || call.status === "cancelled")
+                continue;
+            const output = resultText(m.content);
+            call.output = output || undefined;
+            call.status = m.error ? "failed" : "succeeded";
+            call.error = m.error ? (firstLine(m.error) ?? "The tool failed and didn’t say why.") : undefined;
+        }
+        else {
+            r.reasoning.set(m.id, m.content);
+            seen.add(m.id);
+        }
+    }
+    // Drop what the snapshot no longer has; cards are Candor's own and stay.
+    for (const { reply: r } of turns) {
+        if (!r)
+            continue;
+        r.parts = r.parts.filter((p) => p.kind === "card" || seen.has(p.id));
+        for (const id of r.texts.keys())
+            if (!seen.has(id))
+                r.texts.delete(id);
+        for (const id of r.reasoning.keys())
+            if (!seen.has(id))
+                r.reasoning.delete(id);
+        for (const id of r.tools.keys())
+            if (!seen.has(id))
+                r.tools.delete(id);
+    }
+    return turns;
+}
+/* ---------------------------------------------------------------- rendering */
+function render(r, o) {
+    const live = o.last && !!o.running;
+    // A run that ended can't finish the tool calls it left running.
+    const ended = !live;
+    const blocks = [];
+    let calls = [];
+    const flush = () => {
+        if (calls.length)
+            blocks.push({ kind: "tools", calls });
+        calls = [];
+    };
+    for (const p of r.parts) {
+        if (p.kind === "tool") {
+            calls.push(toolCall(r.tools.get(p.id), o, ended));
+            continue;
+        }
+        flush();
+        if (p.kind === "card")
+            blocks.push({ kind: "card", card: p.card, props: p.props, summary: p.summary });
+        else {
+            const text = r.texts.get(p.id) ?? "";
+            if (text.trim())
+                blocks.push(...markdownBlocks(text));
+        }
+    }
+    flush();
+    if (r.failure)
+        blocks.push({ kind: "degraded", reason: r.failure });
+    const reasoning = [...r.reasoning]
+        .filter(([, text]) => text.trim())
+        .map(([id, text], i, all) => reasoningEntry(`${r.id}-${id}`, text, live && i === all.length - 1));
+    const finished = r.outcome === "success" || r.outcome === "interrupt";
+    return {
+        id: r.id,
+        author: { role: "agent", agent: o.agent },
+        status: live ? "streaming" : r.failure ? "failed" : finished && !r.aborted ? "complete" : "interrupted",
+        blocks,
+        reasoning: reasoning.length ? reasoning : undefined,
+        attribution: r.model && finished ? { model: r.model } : undefined,
+    };
+}
+function toolCall(c, o, ended) {
+    const input = parseArgs(c.args);
+    const call = {
+        id: c.id,
+        tool: c.tool,
+        title: o.toolTitle?.(c.tool, input) ?? c.tool,
+        status: c.status,
+        input: c.args ? (input === undefined ? c.args : json(input)) : undefined,
+        output: c.output,
+        outputLanguage: c.output === undefined ? undefined : "text",
+        error: c.error,
+    };
+    if (c.status === "waiting") {
+        const asking = o.open.some((i) => i.id === c.interruptId);
+        if (!asking)
+            return { ...call, status: "cancelled", error: "Nobody answered before the request closed." };
+        return call;
+    }
+    if (ended && c.status === "running")
+        return { ...call, status: "cancelled", error: "The run ended before this tool returned a result." };
+    return call;
+}
+function approval(i, findCall, o) {
+    const call = i.toolCallId ? findCall(i.toolCallId) : undefined;
+    const input = call ? parseArgs(call.args) : undefined;
+    const named = call ? (o.toolTitle?.(call.tool, input) ?? call.tool) : undefined;
+    return {
+        id: i.id,
+        reason: i.reason,
+        message: i.message,
+        title: i.message ?? (named ? `The agent wants to use ${named}.` : "The agent is waiting for your answer."),
+        toolCallId: i.toolCallId,
+        tool: call?.tool,
+        input,
+        expiresAt: i.expiresAt,
+        responseSchema: i.responseSchema,
+    };
+}
+/* ---------------------------------------------------------------- helpers */
+const expired = (i, now) => i.expiresAt !== undefined && new Date(i.expiresAt).getTime() <= now.getTime();
+function runError(message) {
+    const line = firstLine(message);
+    return line ? `The agent stopped because of an error: ${line}` : "The agent stopped because of an error.";
+}
+function cardValue(v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const { card, props, summary } = v;
+    return typeof card === "string" && typeof summary === "string" ? { card, props, summary } : undefined;
+}
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content.map((c) => (c.type === "text" ? c.text : `[${c.type}]`)).join("\n");
+}
+function parseArgs(args) {
+    if (!args.trim())
+        return undefined;
+    try {
+        return JSON.parse(args);
+    }
+    catch {
+        // Still streaming, or not JSON: show it as it came.
+        return undefined;
+    }
+}
+const firstLine = (text) => text.trim().split("\n")[0] || undefined;
+const json = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 2));
+function reasoningEntry(id, text, streaming) {
+    const first = text.trim().split(/\n|(?<=[.!?])\s/)[0] ?? "";
+    return {
+        id,
+        title: first.length > 90 ? `${first.slice(0, 87)}…` : first,
+        body: text.trim(),
+        streaming,
+        basis: "believed",
+        assumption: "The model’s own reasoning; nothing checked it.",
+    };
+}

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

@@ -0,0 +1,22 @@
+import type { UIMessage } from "ai";
+import type { AgentIdentity, Message } from "../lib/chat.js";
+import { inline, markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+export { inline, markdownBlocks, plainBlocks };
+export type FromAiSdkOptions = {
+    /** Who the assistant is. Candor always names the agent. */
+    agent: AgentIdentity;
+    /** The chat's status from useChat, so the last reply can show as streaming or failed. */
+    chatStatus?: "submitted" | "streaming" | "ready" | "error";
+    /** When a message was sent, if your metadata says. Without it, no time is shown. */
+    createdAt?: (message: UIMessage) => string | undefined;
+    /** A plain-words title for a tool call: "Searched the docs for “region”". */
+    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;
+};
+/** Convert a whole useChat message list. */
+export declare function fromAiSdkMessages(messages: UIMessage[], options: FromAiSdkOptions): Message[];
+/** Convert one message. `last` marks the reply the chat status applies to. */
+export declare function fromAiSdkMessage(message: UIMessage, options: FromAiSdkOptions & {
+    last?: boolean;
+}): Message;

package/dist/adapters/ai-sdk.js

@@ -0,0 +1,129 @@
+import { inline, markdownBlocks, plainBlocks } from "../lib/safe-markdown.js";
+// Re-exported for apps that use them from here. (Imported first: shadcn rewrites import paths, not export-from paths.)
+export { inline, markdownBlocks, plainBlocks };
+/** Convert a whole useChat message list. */
+export function fromAiSdkMessages(messages, options) {
+    const lastAssistant = messages.findLastIndex((m) => m.role === "assistant");
+    return messages.map((m, i) => fromAiSdkMessage(m, { ...options, last: i === lastAssistant }));
+}
+/** Convert one message. `last` marks the reply the chat status applies to. */
+export function fromAiSdkMessage(message, options) {
+    const blocks = [];
+    const reasoning = [];
+    const sources = [];
+    let tools = null;
+    const flushTools = () => {
+        if (tools?.length)
+            blocks.push({ kind: "tools", calls: tools });
+        tools = null;
+    };
+    for (const part of message.parts) {
+        if (part.type === "dynamic-tool" || part.type.startsWith("tool-")) {
+            tools ??= [];
+            tools.push(toolCall(part, options));
+            continue;
+        }
+        flushTools();
+        switch (part.type) {
+            case "text":
+                // A person's own words are kept as typed; only the assistant's text is read as markdown.
+                blocks.push(...(message.role === "user" ? plainBlocks(part.text) : markdownBlocks(part.text)));
+                break;
+            case "reasoning":
+                if (part.text.trim())
+                    reasoning.push(reasoningEntry(part.id ?? `r${reasoning.length}`, part.text, part.state === "streaming"));
+                break;
+            case "source-url":
+                sources.push({ id: part.sourceId, marker: sources.length + 1, kind: "web", label: part.title ?? part.url, origin: host(part.url) });
+                break;
+            case "source-document":
+                sources.push({ id: part.sourceId, marker: sources.length + 1, kind: "document", label: part.title, origin: part.filename });
+                break;
+            case "file":
+                blocks.push({ kind: "paragraph", nodes: [{ kind: "text", text: "Attached " }, { kind: "code", text: part.filename ?? part.mediaType }] });
+                break;
+            case "step-start":
+            case "custom":
+            case "reasoning-file":
+                break;
+            default:
+                if (part.type.startsWith("data-")) {
+                    const name = part.type.slice(5);
+                    const data = part.data;
+                    blocks.push({ kind: "card", card: name, props: data, summary: options.summarize?.(name, data) ?? `A “${name}” card.` });
+                }
+        }
+    }
+    flushTools();
+    const author = message.role === "assistant" ? { role: "agent", agent: options.agent } : message.role === "user" ? { role: "user" } : { role: "system" };
+    return {
+        id: message.id,
+        author,
+        createdAt: options.createdAt?.(message),
+        status: statusOf(options),
+        blocks,
+        reasoning: reasoning.length ? reasoning : undefined,
+        sources: sources.length ? sources : undefined,
+    };
+}
+function statusOf({ last, chatStatus }) {
+    if (!last)
+        return "complete";
+    if (chatStatus === "submitted" || chatStatus === "streaming")
+        return "streaming";
+    if (chatStatus === "error")
+        return "failed";
+    return "complete";
+}
+const toolStatus = (p) => {
+    switch (p.state) {
+        case "input-streaming":
+        case "input-available":
+            return "running";
+        case "approval-requested":
+            return "waiting";
+        case "approval-responded":
+            return p.approval?.approved ? "running" : "cancelled";
+        case "output-available":
+            return p.preliminary ? "running" : "succeeded";
+        case "output-error":
+            return "failed";
+        case "output-denied":
+            return "cancelled";
+    }
+};
+function toolCall(p, options) {
+    const tool = p.toolName ?? p.type.replace(/^tool-/, "");
+    const status = toolStatus(p);
+    return {
+        id: p.toolCallId,
+        tool,
+        title: options.toolTitle?.(tool, p.input) ?? p.title ?? tool,
+        status,
+        input: p.input === undefined ? undefined : json(p.input),
+        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,
+    };
+}
+const json = (v) => (typeof v === "string" ? v : JSON.stringify(v, null, 2));
+/* ---------------------------------------------------------------- reasoning */
+function reasoningEntry(id, text, streaming) {
+    const first = text.trim().split(/\n|(?<=[.!?])\s/)[0] ?? "";
+    return {
+        id,
+        title: first.length > 90 ? `${first.slice(0, 87)}…` : first,
+        body: text.trim(),
+        streaming,
+        basis: "believed",
+        assumption: "The model’s own reasoning; nothing checked it.",
+    };
+}
+const host = (url) => {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+};

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

@@ -0,0 +1,80 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { AgentIdentity, EntityRef, Message } from "../lib/chat.js";
+/** 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. */
+{
+    type: "candor_user";
+    id: string;
+    text: string;
+    references?: EntityRef[];
+}
+/** A tool call is waiting for a person to allow or deny it. */
+ | {
+    type: "candor_approval";
+    id: string;
+    toolUseId: string;
+    tool: string;
+    input: unknown;
+    /** The SDK's own sentence for the request, e.g. "Claude wants to edit notes.md". */
+    title?: string;
+    description?: string;
+    /** Why the SDK asked, when it says. */
+    reason?: string;
+    blockedPath?: string;
+    /** Open on "Deny" and offer no one-key approve: the request grants more than it looks. */
+    defaultToNo?: boolean;
+}
+/** The request was answered, or the run ended before anyone did. */
+ | {
+    type: "candor_approval_closed";
+    id: string;
+    approved: boolean;
+    reason?: string;
+}
+/** A typed card for the app's card registry, sent by your server (a tool's result as a diff, a plan, a table). */
+ | {
+    type: "candor_card";
+    card: string;
+    props: unknown;
+    summary: string;
+}
+/** The run failed outside the SDK's own messages (the request, the stream, the server). */
+ | {
+    type: "candor_error";
+    message: string;
+};
+export type AgentEvent = SDKMessage | CandorAgentEvent;
+export type ClaudeApproval = Omit<Extract<CandorAgentEvent, {
+    type: "candor_approval";
+}>, "type">;
+/** What the SDK measured for the session so far. Cost is its estimate, not a bill. */
+export type ClaudeAgentUsage = {
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    turns: number;
+};
+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;
+    /** A plain-words title for a tool call: "Read notes.md". */
+    toolTitle?: (tool: string, input: unknown) => string | 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;
+    /** A passing problem the agent is handling itself, such as a retried API call. */
+    notice?: string;
+};
+/**
+ * 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;