@candor-ui/react 1.3.0 → 1.7.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. */
@@ -7,14 +8,14 @@ export type CandorAgUiEvent =
     type: "candor_user";
     id: string;
     text: string;
-    references?: EntityRef[];
+    references?: EntityRef[] | undefined;
 }
 /** A person answered an interrupt; the next run resumes with it. */
  | {
     type: "candor_answer";
     interruptId: string;
     approved: boolean;
-    reason?: string;
+    reason?: string | undefined;
 }
 /** The run failed outside the protocol's own events (the request, the stream). */
  | {
@@ -29,47 +30,111 @@ export type AgUiApproval = {
     /** The agent's machine-readable reason, e.g. "tool_approval". */
     reason: string;
     /** The agent's own sentence for the request, when it sent one. */
-    message?: string;
+    message?: string | undefined;
     /** A sentence to show: the agent's message, or a plain one naming the tool. */
     title: string;
     /** Set when the interrupt asks to run a tool call. */
-    toolCallId?: string;
+    toolCallId?: string | undefined;
     /** The tool's name, when the tool call is in the thread. */
-    tool?: string;
+    tool?: string | undefined;
     /** The tool call's arguments, when they arrived and parse. */
     input?: unknown;
     /** When the agent stops waiting (ISO 8601). */
-    expiresAt?: string;
+    expiresAt?: string | undefined;
     /** The shape the agent expects an answer in, when it says. */
-    responseSchema?: Record<string, unknown>;
+    responseSchema?: Record<string, unknown> | undefined;
 };
 /** Tokens the runs reported, summed. A count no run reported stays unknown. AG-UI reports no cost. */
 export type AgUiUsage = {
-    inputTokens?: number;
-    outputTokens?: number;
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
 };
 export type FromAgUiOptions = {
     /** Who the agent is. Candor always names the agent. */
     agent: AgentIdentity;
     /** A run is open now: the last reply is still streaming, and no interrupt can be answered yet. */
-    running?: boolean;
+    running?: boolean | undefined;
     /** A plain-words title for a tool call: "Read notes.md". `input` is undefined until the arguments arrive. */
-    toolTitle?: (tool: string, input: unknown) => string | undefined;
+    toolTitle?: ((tool: string, input: unknown) => string | undefined) | undefined;
     /** The time to judge interrupt expiry by. Defaults to now. */
-    now?: Date;
+    now?: Date | undefined;
+    /** 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[] | undefined;
+};
+/**
+ * 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 | undefined;
+    /** Why it failed: the agent's words, or a plain sentence saying it didn't say. Set only when status is "failed". */
+    failure?: string | undefined;
+};
+/**
+ * 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 | undefined;
+    status: RunStatus;
+    since?: string | undefined;
+};
+/** 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 | undefined;
+    /** Its `steps` as plan steps, when every step has a title and a status Candor knows. */
+    plan?: AgUiPlanStep[] | undefined;
+    /** Its `status`/`doing` as an agent entry, when the status is one Candor knows and the agent is one the app named. */
+    agentActivity?: AgUiAgentActivityEntry | undefined;
 };
 export type AgUiState = {
     messages: Message[];
     /** Interrupts waiting on a person, oldest first. Empty while a run is open; expired ones are left out. */
     approvals: AgUiApproval[];
     /** The thread the runs belong to. Send it back to continue the conversation. */
-    threadId?: string;
-    usage?: AgUiUsage;
+    threadId?: string | undefined;
+    usage?: AgUiUsage | undefined;
     /** Something the person should know that isn't part of a reply, such as an expired request. */
-    notice?: string;
+    notice?: string | undefined;
+    /** 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 | undefined;
+    /** 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,22 +1,27 @@
 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 = {
     /** 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";
+    chatStatus?: "submitted" | "streaming" | "ready" | "error" | undefined;
     /** When a message was sent, if your metadata says. Without it, no time is shown. */
-    createdAt?: (message: UIMessage) => string | undefined;
+    createdAt?: ((message: UIMessage) => string | undefined) | undefined;
     /** A plain-words title for a tool call: "Searched the docs for “region”". */
-    toolTitle?: (tool: string, input: unknown) => string | undefined;
+    toolTitle?: ((tool: string, input: unknown) => string | undefined) | undefined;
     /** The text version of a data part, used when its card can't be shown. */
-    summarize?: (name: string, data: unknown) => string;
+    summarize?: ((name: string, data: unknown) => string) | undefined;
+    /**
+     * 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) | undefined;
 };
 /** 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;
+    last?: boolean | undefined;
 }): 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));