@cygnuxlabs/tracekit 0.0.0-stage → 1.2.1

package/dist/v2/adapters/claude-agent-sdk.js

@@ -0,0 +1,142 @@
+/**
+ * Claude Agent SDK (TS): every tool call is decided by the signer before it runs and recorded after, as
+ * tracekit/integrations/claude_agent_sdk.py does in Python.
+ *
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   import { Client } from "@cygnuxlabs/tracekit/v2";
+ *   import { tracekitHooks, tracekitSessionStore } from "@cygnuxlabs/tracekit/v2/claude-agent-sdk";
+ *   const run = await new Client().registerRun("my-agent");
+ *   query({ prompt, options: { hooks: tracekitHooks(run), sessionStore: tracekitSessionStore(myStore, run) } });
+ *
+ * The gate is the PreToolUse hook, not `canUseTool`: the CLI skips `canUseTool` for every call its permission mode or
+ * allow rules approve, while PreToolUse runs for every call. `deny` blocks the call with the reason, which the model
+ * gets as the tool's error result, and the session goes on. `ask` holds the call in the hook until a person decides in
+ * the signer, for at most APPROVAL_WAIT_MS, below the hook's own timeout (HOOK_TIMEOUT_S, set on the matcher); a call
+ * not approved by then is blocked. An approval with a T2 executor runs the signer's copy of the arguments (the hook's
+ * `updatedInput`). PostToolUse and PostToolUseFailure complete the call; SessionEnd closes the run. The tools of an MCP
+ * server named SERVER (`tracekit-executor`), whose handlers call a tool executor, are left to the executor.
+ * The tools run in the CLI subprocess, so the signer's coding packs apply to them.
+ */
+import { randomUUID } from "node:crypto";
+import { RPCError, SignerUnavailable } from "../client.js";
+import { SERVER } from "../executor.js";
+import { digest } from "../jcs.js";
+import { BLOCKED, Gate, failure, warn } from "./gate.js";
+export const HOOK_TIMEOUT_S = 600; // the SDK's default (60 s) is too short to wait for a person
+export const APPROVAL_WAIT_MS = 540_000; // below HOOK_TIMEOUT_S, so the hook answers before the CLI gives up on it
+const deny = (why) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: why } });
+/** The `hooks` option of `query()`. To add hooks of your own, extend the lists. */
+export function tracekitHooks(run) {
+    const gate = new Gate(run);
+    async function pre(inp, toolUseID) {
+        const id = inp.tool_use_id ?? toolUseID;
+        if (!id)
+            return deny(BLOCKED + "the hook got no tool_use_id"); // never defaulted: a result could not be bound to its decision
+        if (String(inp.tool_name ?? "").startsWith(`mcp__${SERVER}__`))
+            return {}; // the executor decides and records it (T2)
+        const why = await gate.admit(id, inp.tool_name ?? "?", inp.tool_input, { waitMs: APPROVAL_WAIT_MS });
+        if (why !== null)
+            return deny(why);
+        const input = gate.input(id, inp.tool_input);
+        return input === inp.tool_input ? {} : { hookSpecificOutput: { hookEventName: "PreToolUse", updatedInput: input } };
+    }
+    async function post(inp, toolUseID) {
+        const id = inp.tool_use_id ?? toolUseID, resp = inp.tool_response;
+        if (inp.hook_event_name === "PostToolUseFailure")
+            await gate.complete(id, "error", { error: String(inp.error ?? "").slice(0, 4096) });
+        else
+            await gate.complete(id, resp?.is_error || resp?.interrupted ? "error" : "ok", gate.result(id, resp));
+        return {};
+    }
+    async function end(inp) {
+        try {
+            await run.close(String(inp.reason ?? "session end").slice(0, 256));
+        }
+        catch (e) {
+            // the session is over either way: the signer closes the run on its idle timeout
+            if (!(e instanceof RPCError && e.code === "run_closed"))
+                warn(`tracekit: could not close the run: ${e.message}`);
+        }
+        return {};
+    }
+    return { PreToolUse: [{ hooks: [pre], timeout: HOOK_TIMEOUT_S }], PostToolUse: [{ hooks: [post] }],
+        PostToolUseFailure: [{ hooks: [post] }], SessionEnd: [{ hooks: [end] }] };
+}
+/** A SessionStore that commits each saved transcript to the signer (L1): after every append a `state_write` of the
+ * transcript's digest, from the digest it had when this process last saw it. A transcript changed in the store
+ * between two writes (seen on `load`, when a session resumes) makes the signer record a `state_tamper` gap. */
+export function tracekitSessionStore(store, run) {
+    // lean: a new stream per process, so each process that resumes the run opens one (the signer allows 64 per run);
+    // reuse one per run if resumes run into that cap
+    const stream = "claude-agent-sdk-" + randomUUID().replaceAll("-", "");
+    let seq = 0, queue = Promise.resolve();
+    // lean: one digest per transcript for the store's life; prune at session end if one process serves many
+    const digests = new Map(); // what the store holds now; null once an entry is not canonical JSON
+    const acked = new Map(); // what the signer last recorded: the next state_write's prev_digest
+    const lost = new Map(); // the state_write whose answer was lost, sent again before the next
+    const keyOf = (k) => "claude-agent-sdk:" + k.sessionId + (k.subpath ? "/" + k.subpath : "");
+    /** The digest of a transcript after `entries`, from its digest before them; canonical JSON per entry, as a store
+     * may give entries back with their keys reordered. */
+    const chain = (k, entries, d = digest([])) => {
+        try {
+            for (const e of entries)
+                d = digest([d, e]);
+            return d;
+        }
+        catch (e) { // e.g. a number JSON can't hold: no digest to commit
+            warn(`transcript ${k} is not canonical JSON (${failure(e)}); not committed`);
+            return null;
+        }
+    };
+    const load = async (key) => {
+        const entries = await store.load(key), k = keyOf(key), d = chain(k, entries ?? []);
+        digests.set(k, d);
+        acked.set(k, d);
+        return entries;
+    };
+    /** False when the signer could not be reached: it may have recorded the write, so the same request (request_id and
+     * client_seq) goes again before the next one, and a write it recorded never reads as tampering. */
+    const write = async (k, req, d) => {
+        try {
+            await run.call("state_write", req);
+        }
+        catch (e) {
+            warn(`transcript commitment for ${k} not recorded: ${failure(e)}`);
+            if (!(e instanceof SignerUnavailable))
+                return true;
+            lost.set(k, [req, d]);
+            return false;
+        }
+        acked.set(k, d);
+        return true;
+    };
+    const append = async (key, entries) => {
+        const k = keyOf(key);
+        if (!digests.has(k))
+            await load(key); // the first write this process makes to it: from what the store holds
+        await store.append(key, entries); // never throw after this: the SDK would append the entries again
+        const d = digests.get(k) === null ? null : chain(k, entries, digests.get(k));
+        digests.set(k, d);
+        if (d === null)
+            return;
+        // one write at a time, so client_seq reaches the signer in order
+        await (queue = queue.then(async () => {
+            const l = lost.get(k);
+            lost.delete(k);
+            if (l && !(await write(k, ...l)))
+                return; // the signer is still away: the next write commits these entries too
+            await write(k, { request_id: randomUUID().replaceAll("-", ""), stream, client_seq: seq++, key: k, value_digest: d,
+                prev_digest: acked.get(k) ?? null }, d);
+        }));
+    };
+    return new Proxy(store, {
+        get(t, p) {
+            if (p === "append")
+                return append;
+            if (p === "load")
+                return load;
+            const v = Reflect.get(t, p, t);
+            return typeof v === "function" ? v.bind(t) : v;
+        },
+    });
+}

package/dist/v2/adapters/gate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What every framework adapter does with a tool call (04-design §7.3), over one run: decide on the model's arguments,
+ * have the signer consume an approval (or agree that none is needed), run the call, complete it against its decision.
+ * An approval with a T2 executor makes the consume return the signer's copy of the arguments: the call runs those
+ * (`input()`), not the framework's, and completes for them.
+ *
+ * A signer that cannot be reached when a call is decided: the call runs unrecorded if register_run's `fail_modes` say
+ * `open`, else it is refused. Any other failure to decide or approve (a refusal, a run the signer closed after its idle
+ * timeout) refuses the call. A failure to record an outcome warns and changes nothing the framework sees.
+ */
+import { type Decision, type Frame, type RunHandle } from "../client.js";
+export declare const BLOCKED = "Tool call blocked by policy: ";
+/** Sets m[k]; drops the oldest entry past MAX_OPEN_CALLS. */
+export declare function keep<K, V>(m: Map<K, V>, k: K, v: V): void;
+/** m[k], removed. */
+export declare function take<K, V>(m: Map<K, V>, k: K): V | undefined;
+export declare const refusal: (ruleIds: string[], reason?: string) => string;
+export declare const failure: (e: unknown) => string;
+/** The run's approvals by tool call id: requested, approved, rejected or expired. */
+export declare function approvalStates(run: RunHandle): Promise<Map<string, string>>;
+export declare class Gate {
+    private readonly base;
+    private attempts;
+    private passed;
+    private send;
+    private t2;
+    private runs;
+    constructor(base: RunHandle);
+    /** The current run (withRun) while one is set, else the run the adapter was built with. */
+    get run(): RunHandle;
+    /** The run the call was decided in. */
+    runOf(id: string): RunHandle;
+    attempt(id: string): number;
+    /** The signer's decision for the call's next attempt; a refusal rejects (RPCError). */
+    decide(id: string, tool: string, args: unknown): Promise<Decision>;
+    /** Null when the call may run now, else the refusal the model gets instead of its result. `d` is the decision made
+     * for it earlier in this process, `hint` the approval id the framework carried; `waitMs` holds an `ask` until a
+     * person decides, for at most that long. */
+    admit(id: string, tool: string, args: unknown, { d, hint, waitMs }?: {
+        d?: Decision;
+        hint?: string;
+        waitMs?: number;
+    }): Promise<string | null>;
+    /** The arguments a call admit() let through runs with: the signer's copy (T2), else `input`. */
+    input(id: string | undefined, input: unknown): unknown;
+    /** Records the outcome of a call admit() let through. Never rejects. */
+    complete(id: string, status: "ok" | "error", fields?: Frame): Promise<void>;
+    /** Runs `fn` for a call admit() let through and completes it; its result or exception reaches the caller unchanged. */
+    execute<T>(id: string | undefined, fn: () => T | Promise<T>): Promise<T>;
+    /** `complete`'s result for a call admit() let through: the result itself when its decision said `send_result` (an
+     * untrusted tool: the signer redacts it, commits to it and indexes its values for provenance) and it fits in a
+     * frame, else its digest (for an untrusted tool, the signer then marks the run's index partial). */
+    result(id: string, out: unknown): Frame;
+}
+/** A `tool_uses` entry of a model_event: a call the model asked for, run by this process or by the provider. */
+export declare function toolUse(id: string, name: string, input: unknown, byProvider?: boolean): Frame;
+export declare function warn(message: string): void;
+/** `o` without its undefined fields and empty arrays. */
+export declare const defined: (o: Frame) => Frame;
+/** A model response as a model_event (T3: what the model asked for, hosted tool calls included), with the fields
+ * `fields()` returns. Never rejects. */
+export declare function recordResponse(run: RunHandle, provider: string, model: string, fields: () => Frame): Promise<void>;

package/dist/v2/adapters/gate.js

@@ -0,0 +1,195 @@
+/**
+ * What every framework adapter does with a tool call (04-design §7.3), over one run: decide on the model's arguments,
+ * have the signer consume an approval (or agree that none is needed), run the call, complete it against its decision.
+ * An approval with a T2 executor makes the consume return the signer's copy of the arguments: the call runs those
+ * (`input()`), not the framework's, and completes for them.
+ *
+ * A signer that cannot be reached when a call is decided: the call runs unrecorded if register_run's `fail_modes` say
+ * `open`, else it is refused. Any other failure to decide or approve (a refusal, a run the signer closed after its idle
+ * timeout) refuses the call. A failure to record an outcome warns and changes nothing the framework sees.
+ */
+import { currentRun } from "../client.js";
+import { argsDigest, canonicalize, digest } from "../jcs.js";
+export const BLOCKED = "Tool call blocked by policy: ";
+const MAX_OPEN_CALLS = 4096; // per-call entries kept between a framework's hooks for one call
+const MAX_RESULT = 1 << 19; // bytes of a result sent itself (half the signer's frame); a larger one goes as its digest
+/** Sets m[k]; drops the oldest entry past MAX_OPEN_CALLS. */
+export function keep(m, k, v) {
+    // lean: an entry for a call that never reaches its next hook (a run abandoned mid-call) stays until pushed out;
+    // drop a run's entries when it closes if long-lived processes hold many
+    m.delete(k);
+    m.set(k, v);
+    if (m.size > MAX_OPEN_CALLS)
+        m.delete(m.keys().next().value);
+}
+/** m[k], removed. */
+export function take(m, k) {
+    const v = m.get(k);
+    m.delete(k);
+    return v;
+}
+export const refusal = (ruleIds, reason) => BLOCKED + (ruleIds.join(", ") || "deny") + (reason ? `: ${reason}` : "");
+export const failure = (e) => (e instanceof Error ? `${e.name}: ${e.message}` : String(e)).slice(0, 4096);
+/** The run's approvals by tool call id: requested, approved, rejected or expired. */
+export async function approvalStates(run) {
+    // lean: the first page of approval_list (the signer's default limit); follow `cursor` if runs hold more
+    const { approvals } = await run.client.call("approval_list", { run_id: run.runId });
+    const states = new Map();
+    for (const a of approvals)
+        if (!states.has(a.tool_call_id))
+            states.set(a.tool_call_id, a.state);
+    return states;
+}
+export class Gate {
+    base;
+    attempts = new Map(); // tool_call_id -> the attempt its next execution is
+    passed = new Map(); // tool_call_id -> let through (false: unrecorded, fail open)
+    send = new Map(); // tool_call_id -> its decision said send_result (an untrusted tool)
+    t2 = new Map(); // tool_call_id -> (tool, the signer's copy of the arguments)
+    runs = new Map(); // tool_call_id -> the run it was decided in
+    constructor(base) {
+        this.base = base;
+    }
+    /** The current run (withRun) while one is set, else the run the adapter was built with. */
+    get run() {
+        return currentRun() ?? this.base;
+    }
+    /** The run the call was decided in. */
+    runOf(id) {
+        return this.runs.get(id) ?? this.run;
+    }
+    attempt(id) {
+        return this.attempts.get(id) ?? 0;
+    }
+    /** The signer's decision for the call's next attempt; a refusal rejects (RPCError). */
+    decide(id, tool, args) {
+        const run = this.run;
+        keep(this.runs, id, run);
+        return run.decide(id, tool, args, { attempt: this.attempt(id) });
+    }
+    /** Null when the call may run now, else the refusal the model gets instead of its result. `d` is the decision made
+     * for it earlier in this process, `hint` the approval id the framework carried; `waitMs` holds an `ask` until a
+     * person decides, for at most that long. */
+    async admit(id, tool, args, { d, hint, waitMs } = {}) {
+        const attempt = this.attempt(id);
+        try {
+            d ??= await this.decide(id, tool, args);
+        }
+        catch (e) {
+            return BLOCKED + `signer refused the call: ${failure(e)}`;
+        }
+        if (d.unavailable) {
+            if (d.decision !== "allow")
+                return BLOCKED + d.reason;
+            keep(this.passed, id, false);
+            return null;
+        }
+        if (d.decision === "deny")
+            return refusal(d.rule_ids);
+        keep(this.send, id, d.send_result === true);
+        try {
+            if (d.decision === "ask" && waitMs !== undefined) {
+                hint = (await this.runOf(id).approvalRequest(id, { attempt })).approval_id;
+                let state = "requested";
+                for (const end = Date.now() + waitMs; state === "requested" && Date.now() < end;)
+                    state = (await this.runOf(id).approvalWait(hint, Math.min(end - Date.now(), 300_000))).state;
+                if (state !== "approved")
+                    return refusal(d.rule_ids, `not approved: ${state}`);
+            }
+            // every call, allowed or approved: nothing the framework saved vouches that no approval is needed
+            const c = await this.runOf(id).call("approval_consume", { tool_call_id: id, attempt, tool, args,
+                args_source: typeof args === "string" ? "raw" : "parsed", ...(hint ? { approval_id_hint: hint } : {}) });
+            if (!c.ok)
+                return refusal(c.rule_ids, c.reason);
+            if ("args" in c)
+                keep(this.t2, id, [tool, c.args]);
+        }
+        catch (e) { // no fail mode once decided: a refusal or an approval that can't be had blocks
+            return BLOCKED + `signer error: ${failure(e)}`;
+        }
+        keep(this.passed, id, true);
+        return null;
+    }
+    /** The arguments a call admit() let through runs with: the signer's copy (T2), else `input`. */
+    input(id, input) {
+        const t2 = id === undefined ? undefined : this.t2.get(id);
+        return t2 ? t2[1] : input;
+    }
+    /** Records the outcome of a call admit() let through. Never rejects. */
+    async complete(id, status, fields = {}) {
+        const recorded = take(this.passed, id), t2 = take(this.t2, id);
+        this.send.delete(id);
+        if (recorded === undefined)
+            return;
+        const attempt = this.attempt(id);
+        keep(this.attempts, id, attempt + 1);
+        if (recorded)
+            await (take(this.runs, id) ?? this.run).complete(id, status, { attempt, ...(t2 ? { args_digest: argsDigest(...t2) } : {}), ...fields });
+    }
+    /** Runs `fn` for a call admit() let through and completes it; its result or exception reaches the caller unchanged. */
+    async execute(id, fn) {
+        if (id === undefined || !this.passed.has(id))
+            throw new Error(BLOCKED + "the call was not admitted");
+        let out;
+        try {
+            out = await fn();
+        }
+        catch (e) {
+            await this.complete(id, "error", { error: failure(e) });
+            throw e;
+        }
+        await this.complete(id, "ok", this.result(id, out));
+        return out;
+    }
+    /** `complete`'s result for a call admit() let through: the result itself when its decision said `send_result` (an
+     * untrusted tool: the signer redacts it, commits to it and indexes its values for provenance) and it fits in a
+     * frame, else its digest (for an untrusted tool, the signer then marks the run's index partial). */
+    result(id, out) {
+        if (!take(this.send, id))
+            return commitment(out);
+        try {
+            const c = canonicalize(out ?? null);
+            // lean: a larger result goes as its digest; send it in parts if that matters
+            return Buffer.byteLength(c, "utf8") <= MAX_RESULT ? { result: JSON.parse(c) } : commitment(out);
+        }
+        catch {
+            return {};
+        }
+    }
+}
+/** A `tool_uses` entry of a model_event: a call the model asked for, run by this process or by the provider. */
+export function toolUse(id, name, input, byProvider = false) {
+    if (byProvider)
+        return { id, name, executed_by: "provider" };
+    const args_source = typeof input === "string" ? "raw" : "parsed";
+    try {
+        return { id, name, executed_by: "client", args_source, args_digest: argsDigest(name, input) };
+    }
+    catch {
+        return { id, name, executed_by: "client", args_source, args_unparseable: true };
+    }
+}
+export function warn(message) {
+    process.emitWarning(`tracekit: ${message}`, "TracekitWarning");
+}
+/** `o` without its undefined fields and empty arrays. */
+export const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && !(Array.isArray(v) && !v.length)));
+/** A model response as a model_event (T3: what the model asked for, hosted tool calls included), with the fields
+ * `fields()` returns. Never rejects. */
+export async function recordResponse(run, provider, model, fields) {
+    try {
+        await run.modelEvent(String(provider).slice(0, 64), String(model).slice(0, 128), "response", defined(fields()));
+    }
+    catch (e) {
+        warn(`model response not recorded: ${failure(e)}`);
+    }
+}
+/** `result` as a digest (a commitment, not the result), or nothing when it is not JSON. */
+function commitment(out) {
+    try {
+        return { result: digest(out ?? null) };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/v2/adapters/openai-agents.d.ts

@@ -0,0 +1,85 @@
+/**
+ * OpenAI Agents SDK (JS): every function tool call is decided by the signer before it runs and recorded after, as
+ * tracekit/integrations/openai_agents.py does in Python.
+ *
+ *   import { Agent, Runner, tool } from "@openai/agents";
+ *   import { Client } from "@cygnuxlabs/tracekit/v2";
+ *   import { TracekitAgents } from "@cygnuxlabs/tracekit/v2/openai-agents";
+ *   const tk = new TracekitAgents(await new Client().registerRun("payer"));
+ *   const agent = new Agent({ name: "payer", model: "gpt-5", tools: [tk.tool(tool, { name: "pay", description, parameters, execute })] });
+ *   const result = await new Runner().run(agent, "pay acct-42 $15", { context: {} });
+ *   await tk.recordResponses(result.rawResponses, "gpt-5");
+ *
+ * `tk.tool(tool, options)` builds the tool with the SDK's own `tool()`; the signer's policy replaces `needsApproval`,
+ * and a tool input guardrail (after the app's own) gates the call on the model's raw arguments. `deny` gives the model a
+ * refusal as the tool output and the run goes on. `ask` interrupts the run; once a person has decided in the signer,
+ * `await tk.applyDecisions(result.state)` approves or rejects the paused calls and the app resumes with
+ * `runner.run(agent, result.state)`. The RunState JSON is not authenticated, so it carries the approval id only as a
+ * hint in `context.tracekit.approvals`: every call runs only after the signer's `approval_consume` agrees, with the
+ * signer's copy of the arguments for an approval with a T2 executor. Leave the
+ * runner's `toolExecution.preApprovalInputGuardrails` off: the guardrail consumes the approval.
+ *
+ * Not gated: hosted tools (web and file search, code interpreter, hosted MCP, hosted shell), shell, apply_patch and
+ * computer tools and handoffs run outside function tools; they are recorded (T3) only in the signed model responses
+ * that `recordResponses` writes.
+ */
+import type { RunHandle } from "../client.js";
+import { Gate } from "./gate.js";
+type Options = {
+    name?: string;
+    execute: (input: any, context?: any, details?: any) => unknown;
+    inputGuardrails?: unknown[];
+    [k: string]: unknown;
+};
+export declare class TracekitAgents {
+    readonly gate: Gate;
+    private decided;
+    constructor(run: RunHandle);
+    /** The current run (withRun) while one is set, else the run the adapter was built with. */
+    get run(): RunHandle;
+    /** `build({...options})` (the SDK's `tool`), gated by the signer. */
+    tool<T extends {
+        name: string;
+    }>(build: (options: any) => T, options: Options): T;
+    /** needsApproval: decide; on ask, open an approval and keep its id in the run context as a hint. */
+    private ask;
+    /** A call decided in needsApproval that the app's own guardrail refused: complete its decision as refused, so it
+     * isn't left decided and never completed. */
+    private refused;
+    private guard;
+    /** For a local MCP server (`new MCPServerStdio({ ..., ...tk.mcp("filesystem") })`, SSE or streamable HTTP alike):
+     * its `toolInputGuardrails` decide each call as `mcp:<server>/<tool>` and hold an `ask` until a person decides (up
+     * to `waitMs`), its `toolOutputGuardrails` complete the call with the server's output. */
+    mcp(server: string, { waitMs }?: {
+        waitMs?: number | undefined;
+    }): {
+        toolInputGuardrails: {
+            type: string;
+            name: string;
+            run: ({ toolCall }: any) => Promise<{
+                behavior: {
+                    type: string;
+                    message?: undefined;
+                } | {
+                    type: string;
+                    message: string;
+                };
+            }>;
+        }[];
+        toolOutputGuardrails: {
+            type: string;
+            name: string;
+            run: ({ toolCall, output }: any) => Promise<{
+                behavior: {
+                    type: string;
+                };
+            }>;
+        }[];
+    };
+    /** Approve or reject the paused calls of a RunState as the signer's approvers decided; returns the calls still
+     * waiting. Resuming with a call approved some other way runs nothing: the signer refuses it. */
+    applyDecisions(state: any): Promise<any[]>;
+    /** T3: each model response (`result.rawResponses`) as a signed commitment, hosted tool calls included. Never rejects. */
+    recordResponses(responses: any[], model?: string): Promise<void>;
+}
+export {};

package/dist/v2/adapters/openai-agents.js

@@ -0,0 +1,114 @@
+import { digest } from "../jcs.js";
+import { Gate, approvalStates, keep, recordResponse, take, toolUse } from "./gate.js";
+export class TracekitAgents {
+    gate;
+    decided = new Map(); // call id -> its decision, from needsApproval to the guardrail
+    constructor(run) {
+        this.gate = new Gate(run);
+    }
+    /** The current run (withRun) while one is set, else the run the adapter was built with. */
+    get run() {
+        return this.gate.run;
+    }
+    /** `build({...options})` (the SDK's `tool`), gated by the signer. */
+    tool(build, options) {
+        const name = options.name ?? options.execute.name;
+        return build({
+            ...options,
+            name,
+            needsApproval: (ctx, input, callId) => this.ask(ctx, callId, name, input),
+            inputGuardrails: [...(options.inputGuardrails ?? []).map((g) => ({ ...g, run: async (data) => {
+                        const out = await g.run(data);
+                        if (["rejectContent", "throwException"].includes(out?.behavior?.type))
+                            await this.refused(data.toolCall.callId);
+                        return out;
+                    } })), { name: "tracekit", run: (data) => this.guard(data, name) }],
+            execute: (input, ctx, details) => this.gate.execute(details?.toolCall?.callId, () => options.execute(this.gate.input(details?.toolCall?.callId, input), ctx, details)),
+        });
+    }
+    /** needsApproval: decide; on ask, open an approval and keep its id in the run context as a hint. */
+    async ask(ctx, callId, tool, input) {
+        if (!callId)
+            return false; // the guardrail decides, and refuses
+        let d;
+        try {
+            d = await this.gate.decide(callId, tool, input);
+        }
+        catch {
+            return false; // the guardrail decides again, and refuses
+        }
+        keep(this.decided, callId, d);
+        if (d.decision !== "ask")
+            return false; // a deny is refused by the guardrail, before the call runs
+        let approval_id;
+        try {
+            ({ approval_id } = await this.gate.runOf(callId).approvalRequest(callId, { attempt: this.gate.attempt(callId) }));
+        }
+        catch {
+            return false; // no approval to wait for: the guardrail's approval_consume refuses the call
+        }
+        const c = ctx?.context;
+        if (c && typeof c === "object")
+            ((c.tracekit ??= {}).approvals ??= {})[callId] = approval_id;
+        return true;
+    }
+    /** A call decided in needsApproval that the app's own guardrail refused: complete its decision as refused, so it
+     * isn't left decided and never completed. */
+    async refused(callId) {
+        const d = take(this.decided, callId);
+        if (d && d.decision !== "deny")
+            await this.gate.runOf(callId).complete(callId, "error", { attempt: this.gate.attempt(callId), error: "refused by the app's guardrail" });
+    }
+    async guard({ context, toolCall }, tool) {
+        const id = toolCall.callId, hint = context?.context?.tracekit?.approvals?.[id];
+        const why = await this.gate.admit(id, tool, toolCall.arguments, { d: take(this.decided, id), hint: typeof hint === "string" ? hint : undefined });
+        return { behavior: why === null ? { type: "allow" } : { type: "rejectContent", message: why } };
+    }
+    /** For a local MCP server (`new MCPServerStdio({ ..., ...tk.mcp("filesystem") })`, SSE or streamable HTTP alike):
+     * its `toolInputGuardrails` decide each call as `mcp:<server>/<tool>` and hold an `ask` until a person decides (up
+     * to `waitMs`), its `toolOutputGuardrails` complete the call with the server's output. */
+    mcp(server, { waitMs = 300_000 } = {}) {
+        // with the Agent's mcpConfig.includeServerInToolNames the model sees mcp_<server>__<tool>, the server name made
+        // safe as agents-core makes it; `server` must then be the MCP server's own `name`
+        const shown = `mcp_${server.replace(/[^A-Za-z0-9_-]/g, "_").replace(/^[_-]+|[_-]+$/g, "") || "server"}__`;
+        const name = (tool) => `mcp:${server.replace(/[^A-Za-z0-9_.-]+/g, "_") || "unknown"}/${tool.startsWith(shown) ? tool.slice(shown.length) : tool}`;
+        return {
+            toolInputGuardrails: [{ type: "tool_input", name: "tracekit", run: async ({ toolCall }) => {
+                        const why = await this.gate.admit(toolCall.callId, name(toolCall.name), toolCall.arguments, { waitMs });
+                        return { behavior: why === null ? { type: "allow" } : { type: "rejectContent", message: why } };
+                    } }],
+            // lean: a call the MCP server fails reaches no output guardrail: the signer records it decided, not completed;
+            // complete it from the SDK's tool-error event once the SDK exposes one
+            toolOutputGuardrails: [{ type: "tool_output", name: "tracekit", run: async ({ toolCall, output }) => {
+                        await this.gate.complete(toolCall.callId, "ok", this.gate.result(toolCall.callId, output));
+                        return { behavior: { type: "allow" } };
+                    } }],
+        };
+    }
+    /** Approve or reject the paused calls of a RunState as the signer's approvers decided; returns the calls still
+     * waiting. Resuming with a call approved some other way runs nothing: the signer refuses it. */
+    async applyDecisions(state) {
+        const states = await approvalStates(this.run), waiting = [];
+        for (const item of state.getInterruptions()) {
+            const s = states.get(item.rawItem?.callId);
+            if (s === "approved")
+                state.approve(item);
+            else if (s === "rejected" || s === "expired")
+                state.reject(item, { message: `Tool call ${s} in Tracekit` });
+            else
+                waiting.push(item);
+        }
+        return waiting;
+    }
+    /** T3: each model response (`result.rawResponses`) as a signed commitment, hosted tool calls included. Never rejects. */
+    async recordResponses(responses, model = "") {
+        for (const r of responses)
+            await recordResponse(this.run, "openai", model, () => ({
+                content_digest: digest(r.output),
+                usage: r.usage && { input_tokens: r.usage.inputTokens, output_tokens: r.usage.outputTokens },
+                // lean: function and hosted tool calls; shell, apply_patch and computer calls are in content_digest only
+                tool_uses: r.output.flatMap((i) => (i.type === "function_call" ? [toolUse(i.callId, i.name, i.arguments)]
+                    : i.type === "hosted_tool_call" && i.id ? [toolUse(i.id, i.name, null, true)] : [])).slice(0, 128),
+            }));
+    }
+}

package/dist/v2/adapters/vercel-ai.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Vercel AI SDK v7: every tool call is decided by the signer before it runs and recorded after.
+ *
+ *   import { generateText, wrapLanguageModel } from "ai";
+ *   import { Client } from "@cygnuxlabs/tracekit/v2";
+ *   import { tracekitAI } from "@cygnuxlabs/tracekit/v2/vercel-ai";
+ *   const tk = tracekitAI(await new Client().registerRun("assistant"));
+ *   const model = wrapLanguageModel({ model: openai("gpt-5"), middleware: tk.middleware });
+ *   const r = await generateText({ model, tools: tk.tools({ pay }), toolApproval: tk.toolApproval, messages });
+ *   // once a person decided the asks in the signer:
+ *   messages.push(...r.response.messages, { role: "tool", content: await tk.approvalResponses(r.content) });
+ *
+ * The same options work for `streamText` and `ToolLoopAgent`. `tk.middleware` (for `wrapLanguageModel`) records each
+ * model response as a signed model_event (V3 usage, the tool calls asked for) and keeps each call's raw arguments
+ * string by `toolCallId`, so the signer decides on what the model sent. `tk.toolApproval` decides each call: `deny`
+ * becomes a `denied` status (the model gets the refusal and the loop goes on), `ask` opens an approval in the signer
+ * and becomes `user-approval`. `tk.approvalResponses(parts)` turns the `tool-approval-request` parts the signer's
+ * approvers decided into `tool-approval-response` parts to resume with. `tk.tools(tools)` wraps each tool's `execute`:
+ * every call, allowed or approved, runs only after the signer's `approval_consume` agrees, so an approval response the
+ * client forged or replayed runs nothing, and an approval with a T2 executor runs the signer's copy of the arguments;
+ * `experimental_toolApprovalSecret` (the SDK's HMAC over its approval
+ * requests) can be set as well and does not replace this. Without `tk.toolApproval` an `ask` is refused.
+ *
+ * Tools without `execute` and provider-executed tools are not gated; they are recorded in the model responses. A tool
+ * executor's tools (`vercelTool`, marked EXECUTOR) are left to the executor, which decides and records them (T2).
+ */
+import type { Frame, RunHandle } from "../client.js";
+export declare function tracekitAI(run: RunHandle): {
+    middleware: {
+        specificationVersion: "v4";
+        wrapGenerate({ doGenerate, model }: any): Promise<any>;
+        wrapStream({ doStream, model }: any): Promise<any>;
+    };
+    toolApproval: ({ toolCall, tools }: any) => Promise<"not-applicable" | {
+        type: "denied";
+        reason: string;
+    } | {
+        type: "user-approval";
+        reason: string;
+    }>;
+    /** `toolApproval` that also asks the app's own (a function, or one per tool name): the signer's policy first; the
+     * app's answer applies only to a call the policy allows. A call the app denies is completed as refused. */
+    toolApprovalWith(app: any): (opts: any) => Promise<any>;
+    /** `tools` with each `execute` gated by the signer. With `mcp` (the server's name: `tools(await mcp.tools(),
+     * { mcp: "filesystem" })`) each is decided as `mcp:<server>/<tool>`. */
+    tools<T extends Record<string, any>>(tools: T, { mcp }?: {
+        mcp?: string;
+    }): T;
+    /** `tool-approval-response` parts for the `tool-approval-request` parts the signer's approvers decided. */
+    approvalResponses(parts: any[]): Promise<Frame[]>;
+};