@candor-ui/react 1.3.0 → 1.7.0

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

@@ -1,5 +1,123 @@
-import type { CanUseTool, Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
-import type { AgentEvent } from "./claude-agent-sdk.js";
+import type { CanUseTool, PermissionMode, Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type AgentEvent, type ClaudeApproval, type ClaudeApprovalAnswer, type ClaudePermissionMode } from "./claude-agent-sdk.js";
+import type { EntityRef } from "../lib/chat.js";
+/** A permission request as a store keeps it. */
+export type StoredApproval = {
+    id: string;
+    /** The run it belongs to, when the run has an id. */
+    runId?: string | undefined;
+    /** Who may answer it; checked by answerClaudeApproval. */
+    owner?: string | undefined;
+    request: ClaudeApproval;
+    createdAt: string;
+    /** Set once answered. Recorded, not necessarily used: a run that stopped at the same moment still denies the tool. */
+    answer?: ClaudeApprovalAnswer & {
+        at: string;
+    } | undefined;
+    /** Set when nobody can answer any more (the run ended or stopped), with why. */
+    closed?: {
+        at: string;
+        reason: string;
+    } | undefined;
+};
+/**
+ * Where waiting permission requests live. Answering and closing each happen once: whichever comes first wins, so a
+ * late answer to a run that already ended returns false instead of being lost. A store backed by a database does
+ * both as one conditional update (`… where answered_at is null and closed_at is null`).
+ */
+export interface ApprovalStore {
+    /** Record a request that waits on a person. */
+    put(approval: StoredApproval): Promise<void>;
+    get(id: string): Promise<StoredApproval | undefined>;
+    /** Record the answer. False when there's no such request, or it was already answered or closed. */
+    answer(id: string, answer: ClaudeApprovalAnswer): Promise<boolean>;
+    /** Mark that it can't be answered any more. False when it was answered first. */
+    close(id: string, reason: string): Promise<boolean>;
+    /**
+     * Resolves with the answer once there is one, or undefined once it's closed or `signal` aborts. When `signal`
+     * aborts first, close the request in the same step ("The run was stopped."), so an answer arriving just after is
+     * refused instead of recorded for a tool that never ran. A store with no way to push can poll with waitByPolling.
+     */
+    wait(id: string, signal: AbortSignal): Promise<ClaudeApprovalAnswer | undefined>;
+    /** Requests still waiting, oldest first, for one run or all: what to show again after a reload. */
+    pending(runId?: string): Promise<StoredApproval[]>;
+}
+/**
+ * The default ApprovalStore: this process's memory. Answered and closed requests are forgotten after `keepMs`
+ * (10 minutes), so it doesn't grow without bound.
+ */
+export declare function memoryApprovalStore({ keepMs }?: {
+    keepMs?: number | undefined;
+}): ApprovalStore;
+/** A `wait` for stores that can't push: reads the request every `intervalMs` (1s) until it's answered or closed. */
+export declare function waitByPolling(get: (id: string) => Promise<StoredApproval | undefined>, id: string, signal: AbortSignal, intervalMs?: number): Promise<ClaudeApprovalAnswer | undefined>;
+export type ClaudeCanUseToolOptions = {
+    /** Where requests wait. Defaults to this process's memory. */
+    approvals?: ApprovalStore | undefined;
+    /** Sends each request, and its closing, to whoever shows it (the browser, your event log). */
+    emit: (event: AgentEvent) => void;
+    /** Who may answer. */
+    owner?: string | undefined;
+    /** The run's id, kept with each request. */
+    runId?: string | undefined;
+    /** The run's permission mode now, recorded on each request. */
+    mode?: (() => ClaudePermissionMode | undefined) | undefined;
+    /** Called with each request's id as it starts waiting and once it's settled, e.g. to close the rest when the run ends. */
+    track?: {
+        add(id: string): void;
+        delete(id: string): void;
+    } | undefined;
+    /**
+     * Which tools' input a person may edit before allowing it (`updatedInput`). Every tool by default, as in 1.5.0;
+     * an answer that edits a tool this refuses is rejected by answerClaudeApproval, whatever the browser sends.
+     */
+    editable?: ((tool: string, input: unknown) => boolean) | undefined;
+    /** Close a request nobody answered after this long, as expired: the tool is denied, never allowed. No limit by default. */
+    approvalTimeoutMs?: number | undefined;
+};
+/**
+ * A canUseTool that keeps each request in an ApprovalStore and waits for its answer from wherever it's given: your
+ * route, a queue, a workflow signal (`approvals.answer(id, { approved: true })`). Use it on its own when your agent
+ * runs somewhere other than streamClaudeAgent. When the SDK stops waiting, the request is closed, so a late answer
+ * is refused rather than lost.
+ */
+export declare function claudeCanUseTool({ approvals, emit, owner, runId, mode, track, editable, approvalTimeoutMs }: ClaudeCanUseToolOptions): CanUseTool;
+/**
+ * A run's events, kept so a browser can re-attach after a reload and a finished run can be replayed. `read` returns
+ * the events from index `from` on, and whether the run has ended.
+ */
+export interface ClaudeRunStore {
+    /**
+     * Begin a run, with who started it. streamClaudeAgent calls it first. An append, end or subscribe for a run that
+     * was never started (or was already forgotten) must do nothing rather than create it, so a forgotten run can't
+     * come back without its owner.
+     */
+    start?(runId: string, owner?: string): Promise<void>;
+    append(runId: string, event: AgentEvent): Promise<void>;
+    end(runId: string): Promise<void>;
+    read(runId: string, from: number): Promise<{
+        events: AgentEvent[];
+        ended: boolean;
+    } | undefined>;
+    /** Called when the run has new events or ends. Optional: without it, attaching polls `read`. */
+    subscribe?(runId: string, listener: () => void): () => void;
+    /** Who started the run, when it was started with an owner; attachClaudeAgentRun checks it. */
+    ownerOf?(runId: string): Promise<string | undefined>;
+    /** Record the run's owner. Kept from 1.5.0; prefer `start`. */
+    setOwner?(runId: string, owner: string): Promise<void>;
+}
+/**
+ * The default ClaudeRunStore: this process's memory. It keeps at most `maxRuns` finished runs (100), forgetting the
+ * oldest finished one first; a run still going is never forgotten. Each run keeps at most `maxEvents` events
+ * (5,000): past that, partial-text events are no longer kept (the finished message still is), so a re-attached
+ * browser sees text arrive a message at a time instead of as it streams.
+ */
+export declare function memoryRunStore({ maxRuns, maxEvents }?: {
+    maxRuns?: number | undefined;
+    maxEvents?: number | undefined;
+}): ClaudeRunStore;
+/** Which permission modes a run may be switched to: a list, or a test. */
+export type ModePolicy = readonly PermissionMode[] | ((mode: PermissionMode) => boolean);
 export type RunClaudeAgent = (tools: {
     /** Pass to query()'s `canUseTool`, so permission requests reach the person. */
     canUseTool: CanUseTool;
@@ -10,20 +128,52 @@ export type RunClaudeAgent = (tools: {
      * It renders through the app's card registry, in the reply where it was sent.
      */
     emit: (event: AgentEvent) => void;
+    /** This run's id: the same one the response's `x-candor-run-id` header carries. */
+    runId: string;
 }) => Query;
 export type StreamClaudeAgentOptions = {
-    /** The incoming request's signal (`request.signal`): the agent stops when the browser goes away. */
-    signal?: AbortSignal;
-    /** Who may answer this run's permission requests, e.g. the signed-in user's id. Checked by answerClaudeAgentApproval. */
-    owner?: string;
+    /** The incoming request's signal (`request.signal`): the agent stops when the browser goes away, unless `detach`. */
+    signal?: AbortSignal | undefined;
+    /** Who may answer this run's permission requests, e.g. the signed-in user's id. Checked when they're answered. */
+    owner?: string | undefined;
     /** The sentence shown when the run fails. Defaults to a generic one, so server errors don't leak to the browser. */
-    describeError?: (error: unknown) => string;
+    describeError?: ((error: unknown) => string) | undefined;
     /**
      * Called with every SDK message just before it's sent to the browser, e.g. to record usage and cost from
      * `assistant` and `result` messages. To stop the run from here, abort the run's abortController: the message
      * in hand is still sent, and nothing after it.
      */
-    onMessage?: (message: SDKMessage) => void | Promise<void>;
+    onMessage?: ((message: SDKMessage) => void | Promise<void>) | undefined;
+    /** Called with every event the browser gets, in order, e.g. to keep the whole conversation for replay. */
+    onEvent?: ((event: AgentEvent) => void | Promise<void>) | undefined;
+    /** Where permission requests wait. Defaults to this process's memory. */
+    approvals?: ApprovalStore | undefined;
+    /** Keeps the run's events so a browser can re-attach (attachClaudeAgentRun). Without it, a reload loses the run. */
+    runs?: ClaudeRunStore | undefined;
+    /** The run's id; a new one by default. Sent back in the `x-candor-run-id` header. */
+    runId?: string | undefined;
+    /**
+     * Keep running when the browser goes away (a reload, a closed tab), so it can re-attach. Stop it with
+     * stopClaudeAgentRun. Needs a process that outlives the response: not a serverless function that's frozen when
+     * the response ends.
+     */
+    detach?: boolean | undefined;
+    /**
+     * What the person sent, recorded as the run's first event in `runs`, so a re-attached browser shows it. Pass the
+     * `promptId` useClaudeAgent sends as `id`: a browser that re-attaches with `initialEvents` then replaces the run's
+     * events instead of adding them again.
+     */
+    prompt?: {
+        id: string;
+        text: string;
+        references?: EntityRef[] | undefined;
+    } | undefined;
+    /** Which tools' input a person may edit before allowing it. Every tool by default. See claudeCanUseTool. */
+    editable?: ClaudeCanUseToolOptions["editable"] | undefined;
+    /** Close a permission request nobody answered after this long, as expired (denied). No limit by default; set one with `detach`. */
+    approvalTimeoutMs?: number | undefined;
+    /** The permission modes setClaudeAgentPermissionMode may switch this run to. Any mode by default. */
+    modes?: ModePolicy | undefined;
 };
 /**
  * Run an agent and stream it to useClaudeAgent.
@@ -38,16 +188,51 @@ export type StreamClaudeAgentOptions = {
  *     )
  *   }
  */
-export declare function streamClaudeAgent(run: RunClaudeAgent, { signal, owner, describeError, onMessage }?: StreamClaudeAgentOptions): Response;
+export declare function streamClaudeAgent(run: RunClaudeAgent, { signal, owner, describeError, onMessage, onEvent, approvals, runs, runId, detach, prompt, editable, approvalTimeoutMs, modes }?: StreamClaudeAgentOptions): Response;
 /**
- * Answer a waiting permission request. Returns false when there's no such
- * request (already answered, the run ended, or it ran in another process) or
- * `owner` doesn't match the run's owner.
+ * Stream a run's events again, from index `from`, then live until it ends: for a browser re-attaching after a
+ * reload. 404 when the store doesn't know the run, 403 when `owner` isn't who started it.
+ *
+ *   // app/api/agent/[runId]/route.ts
+ *   export async function GET(request: Request, { params }) {
+ *     const from = Number(new URL(request.url).searchParams.get("from") ?? 0)
+ *     return attachClaudeAgentRun(runs, (await params).runId, { from, owner: userId, signal: request.signal })
+ *   }
+ */
+export declare function attachClaudeAgentRun(runs: ClaudeRunStore, runId: string, { from, owner, signal, pollMs }?: {
+    from?: number | undefined;
+    owner?: string | undefined;
+    signal?: AbortSignal | undefined;
+    pollMs?: number | undefined;
+}): Promise<Response>;
+/** Stop a run this process is running. False when it isn't running here, or `owner` didn't start it. */
+export declare function stopClaudeAgentRun(runId: string, owner?: string): boolean;
+/**
+ * Change a running agent's permission mode (the SDK's `setPermissionMode`), and tell the browser. Only for a query
+ * in streaming input mode, as the SDK requires. False when the run isn't here, `owner` didn't start it, the mode
+ * isn't allowed, or the SDK refused. The route is where policy is enforced: a mode PermissionMode shows as locked
+ * must be left out of `allowed` (or the run's `modes`) too, since anyone can post to the route directly.
+ */
+export declare function setClaudeAgentPermissionMode(runId: string, mode: PermissionMode, owner?: string, { allowed }?: {
+    allowed?: ModePolicy | undefined;
+}): Promise<boolean>;
+/**
+ * Check an answer from the browser against the request it answers, and record it. False when there's no such
+ * request, it's already settled, `owner` isn't the run's owner, or the answer doesn't fit the request (an edited
+ * input that isn't an object, answers to a request that isn't a question, a suggestion that wasn't offered).
  *
  *   // app/api/agent/approve/route.ts
  *   export async function POST(request: Request) {
- *     const { id, approved, reason } = await request.json()
- *     return Response.json({ ok: answerClaudeAgentApproval(id, approved, reason, userId) })
+ *     const { id, ...answer } = await request.json()
+ *     return Response.json({ ok: await answerClaudeApproval(approvals, id, answer, { owner: userId }) })
  *   }
  */
+export declare function answerClaudeApproval(approvals: ApprovalStore, id: string, answer: ClaudeApprovalAnswer, { owner }?: {
+    owner?: string | undefined;
+}): Promise<boolean>;
+/**
+ * Answer a waiting permission request in the default, in-memory store. Kept from 1.4; answerClaudeApproval takes a
+ * store and the full answer (an edited input, answers to questions, "always allow"). Returns false when there's no
+ * such request, or `owner` doesn't match the run's owner.
+ */
 export declare function answerClaudeAgentApproval(id: string, approved: boolean, reason?: string, owner?: string): boolean;