@writ-agent/sdk 0.1.0

package/dist/cjs/client.js

@@ -0,0 +1,387 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WritClient = void 0;
+exports.shouldDispatch = shouldDispatch;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors.js");
+const locate_js_1 = require("./locate.js");
+const protocol_js_1 = require("./protocol.js");
+const DECISIONS = new Set(["allow", "deny", "ask", "redact"]);
+const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
+/** True only when a decision says the tool may run. */
+function shouldDispatch(decision) {
+    return decision.dispatch === true && decision.decision !== "deny";
+}
+/**
+ * A long-lived `writ check --stdio` child process speaking protocol v1.
+ * Every failure (missing binary, crash, timeout, malformed line, `error`
+ * response) rejects with a `WritError`; callers must then not run the tool.
+ */
+class WritClient {
+    askMode;
+    sessionId;
+    caller;
+    options;
+    timeoutMs;
+    maxLineBytes;
+    proc;
+    queue = [];
+    buffer = "";
+    seq = 0;
+    closed = false;
+    broken;
+    stderrTail = "";
+    constructor(options = {}) {
+        this.options = options;
+        this.askMode = options.ask ?? "deny";
+        if (this.askMode !== "deny" && this.askMode !== "defer") {
+            throw new errors_js_1.WritError("bad_option", `ask must be "deny" or "defer", got ${String(options.ask)}`);
+        }
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxLineBytes = options.maxLineBytes ?? 16 * 1024 * 1024;
+        this.sessionId = options.sessionId ?? (0, node_crypto_1.randomUUID)();
+        this.caller = options.caller;
+    }
+    /** The argv (after the program) passed to writ. */
+    gatewayArgs() {
+        const args = [];
+        if (this.options.policy !== undefined)
+            args.push("--policy", this.options.policy);
+        if (this.options.ledger !== undefined)
+            args.push("--ledger", this.options.ledger);
+        args.push("check", "--stdio", "--ask", this.askMode);
+        return args;
+    }
+    /** Ask writ for a verdict. Rejects on any gateway failure. */
+    async decide(call) {
+        const body = {
+            op: "decide",
+            call: {
+                ...call,
+                session_id: call.session_id || this.sessionId,
+                caller: call.caller ?? this.caller ?? { agent: "unknown" },
+                server: call.server ?? null,
+                trust: call.trust ?? null,
+            },
+        };
+        return parseDecision(await this.request(body), "decide");
+    }
+    /** Resolve a deferred ask. The response is a final decision. */
+    async resolve(ref, approved, approver) {
+        const body = { op: "resolve", ref, approved };
+        if (approver !== undefined)
+            body.approver = approver;
+        const decision = parseDecision(await this.request(body), "resolve");
+        if (!approved && shouldDispatch(decision)) {
+            throw new errors_js_1.WritProtocolError("gateway returned dispatch:true for a rejected ask");
+        }
+        return decision;
+    }
+    /** Record the execution of a dispatched call. For redact, `output` in the result is the redacted text. */
+    async complete(ref, input) {
+        const body = { op: "complete", ref, ok: input.ok };
+        if (input.exit !== undefined)
+            body.exit = input.exit;
+        if (input.output !== undefined)
+            body.output = input.output;
+        const res = await this.request(body);
+        if (res.recorded !== true) {
+            throw new errors_js_1.WritProtocolError("complete response is missing recorded:true");
+        }
+        if (res.output !== undefined && typeof res.output !== "string") {
+            throw new errors_js_1.WritProtocolError("complete response output is not a string");
+        }
+        return typeof res.output === "string" ? { recorded: true, output: res.output } : { recorded: true };
+    }
+    /**
+     * decide, and for a deferred ask obtain an answer from `approver` and
+     * `resolve` it. Returns the final decision; check `shouldDispatch`.
+     * A missing, throwing, late or non-approving approver is a denial.
+     */
+    async authorize(call, options = {}) {
+        const decision = await this.decide(call);
+        if (decision.decision !== "ask" || decision.approval !== "required")
+            return decision;
+        if (decision.ref === undefined)
+            throw new errors_js_1.WritProtocolError("deferred ask is missing ref");
+        const { approved, approver } = await runApprover(call, decision, options);
+        return this.resolve(decision.ref, approved, approver);
+    }
+    /** Close stdin, wait briefly for writ to exit, then kill it. Idempotent. */
+    async close() {
+        this.closed = true;
+        const proc = this.proc;
+        if (proc === undefined)
+            return;
+        await new Promise((done) => {
+            if (proc.exitCode !== null || proc.signalCode !== null)
+                return done();
+            const timer = setTimeout(() => {
+                proc.kill();
+                done();
+            }, 2000);
+            proc.once("exit", () => {
+                clearTimeout(timer);
+                done();
+            });
+            proc.stdin?.end();
+        });
+        this.failAll(new errors_js_1.WritError("closed", "writ client closed"));
+        this.proc = undefined;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    // --- transport -----------------------------------------------------------
+    request(body) {
+        if (this.closed)
+            return Promise.reject(new errors_js_1.WritError("closed", "writ client is closed"));
+        if (this.broken !== undefined && this.options.respawn === false)
+            return Promise.reject(this.broken);
+        let proc;
+        try {
+            proc = this.ensureProcess();
+        }
+        catch (err) {
+            return Promise.reject(toWritError(err));
+        }
+        const id = `r${++this.seq}`;
+        const op = String(body.op);
+        const line = JSON.stringify({ v: protocol_js_1.PROTOCOL_VERSION, id, ...body }) + "\n";
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.poison(new errors_js_1.WritTimeoutError(`writ check did not answer ${op} ${id} within ${this.timeoutMs} ms`));
+            }, this.timeoutMs);
+            this.queue.push({ id, op, resolve, reject, timer });
+            this.setRef(true);
+            const stdin = proc.stdin;
+            if (stdin === null || !stdin.writable) {
+                this.poison(new errors_js_1.WritProtocolError("writ check stdin is not writable"));
+                return;
+            }
+            stdin.write(line);
+        });
+    }
+    ensureProcess() {
+        if (this.proc !== undefined)
+            return this.proc;
+        const launch = this.resolveLaunch();
+        const args = [...launch.args, ...this.gatewayArgs()];
+        const proc = (0, node_child_process_1.spawn)(launch.command, args, {
+            cwd: this.options.cwd,
+            env: this.options.env ?? process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: false,
+            windowsHide: true,
+        });
+        this.proc = proc;
+        this.broken = undefined;
+        this.buffer = "";
+        this.stderrTail = "";
+        proc.stdout?.setEncoding("utf8");
+        proc.stderr?.setEncoding("utf8");
+        proc.stdout?.on("data", (chunk) => {
+            if (this.proc === proc)
+                this.onData(chunk);
+        });
+        proc.stderr?.on("data", (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk).slice(-4096);
+            this.options.onStderr?.(chunk);
+        });
+        proc.stdin?.on("error", (err) => {
+            if (this.proc === proc)
+                this.poison(new errors_js_1.WritProtocolError(`writ check stdin failed: ${err.message}`, { cause: err }));
+        });
+        proc.on("error", (err) => {
+            if (this.proc !== proc)
+                return;
+            const code = err.code;
+            this.poison(code === "ENOENT" || code === "EACCES"
+                ? new errors_js_1.WritUnavailableError(`cannot start writ (${launch.command}): ${err.message}`, { cause: err })
+                : new errors_js_1.WritProtocolError(`writ check failed: ${err.message}`, { cause: err }));
+        });
+        // "close" fires after stdout/stderr are drained, so the stderr tail is complete.
+        proc.on("close", (code, signal) => {
+            if (this.proc !== proc)
+                return;
+            const how = signal !== null ? `signal ${signal}` : `code ${String(code)}`;
+            const tail = this.stderrTail.trim();
+            this.poison(new errors_js_1.WritProtocolError(`writ check exited (${how})${tail ? `: ${tail}` : ""}`));
+        });
+        return proc;
+    }
+    resolveLaunch() {
+        if (this.options.command !== undefined) {
+            return { command: this.options.command, args: [...(this.options.args ?? [])] };
+        }
+        const launch = this.options.bin !== undefined ? (0, locate_js_1.launchFor)(this.options.bin) : (0, locate_js_1.locateWrit)(undefined, this.options.env ?? process.env);
+        return { command: launch.command, args: [...launch.args, ...(this.options.args ?? [])] };
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let nl;
+        while ((nl = this.buffer.indexOf("\n")) >= 0) {
+            const raw = this.buffer.slice(0, nl).replace(/\r$/, "");
+            this.buffer = this.buffer.slice(nl + 1);
+            if (raw.trim() === "")
+                continue;
+            this.onLine(raw);
+            if (this.proc === undefined)
+                return;
+        }
+        if (Buffer.byteLength(this.buffer, "utf8") > this.maxLineBytes) {
+            this.poison(new errors_js_1.WritProtocolError(`writ check response line exceeds ${this.maxLineBytes} bytes`));
+        }
+    }
+    onLine(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            this.poison(new errors_js_1.WritProtocolError(`malformed line from writ check: ${truncate(raw)}`));
+            return;
+        }
+        const head = this.queue[0];
+        if (head === undefined) {
+            this.poison(new errors_js_1.WritProtocolError(`unsolicited line from writ check: ${truncate(raw)}`));
+            return;
+        }
+        if (!isObject(msg) || msg.v !== protocol_js_1.PROTOCOL_VERSION || msg.id !== head.id) {
+            this.poison(new errors_js_1.WritProtocolError(`unexpected response (wanted v:1 id:${head.id}): ${truncate(raw)}`));
+            return;
+        }
+        this.queue.shift();
+        clearTimeout(head.timer);
+        if (this.queue.length === 0)
+            this.setRef(false);
+        if (msg.error !== undefined) {
+            const e = isObject(msg.error) ? msg.error : {};
+            const code = typeof e.code === "string" ? e.code : "error";
+            const message = typeof e.message === "string" ? e.message : "writ check returned an error";
+            head.reject(new errors_js_1.WritError(code, `writ ${head.op} failed (${code}): ${message}`));
+            return;
+        }
+        head.resolve(msg);
+    }
+    /** Fail every in-flight request and drop the process (fail closed). */
+    poison(error) {
+        const proc = this.proc;
+        this.proc = undefined;
+        this.broken = error;
+        this.buffer = "";
+        if (proc !== undefined && proc.exitCode === null && proc.signalCode === null) {
+            proc.kill();
+        }
+        this.failAll(error);
+    }
+    failAll(error) {
+        const pending = this.queue;
+        this.queue = [];
+        for (const p of pending) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+    }
+    /** Keep the event loop alive only while requests are in flight. */
+    setRef(on) {
+        const proc = this.proc;
+        if (proc === undefined)
+            return;
+        const method = on ? "ref" : "unref";
+        proc[method]();
+        for (const s of [proc.stdin, proc.stdout, proc.stderr]) {
+            const handle = s;
+            handle?.[method]?.();
+        }
+    }
+}
+exports.WritClient = WritClient;
+// --- helpers ---------------------------------------------------------------
+async function runApprover(call, decision, options) {
+    const approver = options.approver;
+    if (approver === undefined)
+        return { approved: false, approver: "adapter:no-approver" };
+    const limit = decision.timeout_ms ?? options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((done) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            done("timeout");
+        }, limit);
+    });
+    try {
+        const answer = await Promise.race([
+            Promise.resolve().then(() => approver({ call, decision, signal: controller.signal })),
+            timeout,
+        ]);
+        if (answer === "timeout")
+            return { approved: false, approver: "adapter:approval-timeout" };
+        if (answer === true)
+            return { approved: true, approver: "adapter:approver" };
+        if (isObject(answer) && answer.approved === true) {
+            return { approved: true, approver: typeof answer.approver === "string" ? answer.approver : "adapter:approver" };
+        }
+        const who = isObject(answer) && typeof answer.approver === "string" ? answer.approver : "adapter:approver";
+        return { approved: false, approver: who };
+    }
+    catch {
+        return { approved: false, approver: "adapter:approver-error" };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function parseDecision(msg, op) {
+    const kind = msg.decision;
+    if (typeof kind !== "string" || !DECISIONS.has(kind)) {
+        throw new errors_js_1.WritProtocolError(`${op} response has no valid decision`);
+    }
+    if (typeof msg.dispatch !== "boolean") {
+        throw new errors_js_1.WritProtocolError(`${op} response has no boolean dispatch`);
+    }
+    const decision = { decision: kind, dispatch: msg.dispatch };
+    // A decision that contradicts itself is not trusted.
+    if (kind === "deny" && msg.dispatch)
+        throw new errors_js_1.WritProtocolError(`${op}: deny with dispatch:true`);
+    if (op === "decide" && kind === "ask" && msg.dispatch)
+        throw new errors_js_1.WritProtocolError("decide: ask with dispatch:true");
+    if (op === "decide" && (kind === "allow" || kind === "redact") && !msg.dispatch) {
+        throw new errors_js_1.WritProtocolError(`decide: ${kind} with dispatch:false`);
+    }
+    if (typeof msg.ref === "string")
+        decision.ref = msg.ref;
+    if (typeof msg.rule_id === "string")
+        decision.rule_id = msg.rule_id;
+    if (typeof msg.reason === "string")
+        decision.reason = msg.reason;
+    if (typeof msg.location === "string")
+        decision.location = msg.location;
+    if (msg.approval === "required")
+        decision.approval = "required";
+    if (typeof msg.irreversible === "boolean")
+        decision.irreversible = msg.irreversible;
+    if (typeof msg.timeout_ms === "number")
+        decision.timeout_ms = msg.timeout_ms;
+    if (Array.isArray(msg.patterns))
+        decision.patterns = msg.patterns.filter((p) => typeof p === "string");
+    if (decision.dispatch && decision.ref === undefined) {
+        throw new errors_js_1.WritProtocolError(`${op}: dispatching decision is missing ref`);
+    }
+    return decision;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function truncate(s) {
+    return s.length > 200 ? `${s.slice(0, 200)}...` : s;
+}
+function toWritError(err) {
+    if (err instanceof errors_js_1.WritError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new errors_js_1.WritUnavailableError(`cannot start writ: ${message}`, { cause: err });
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,35 @@
+import type { Decision } from "./protocol.js";
+/**
+ * Base class for every writ failure. Any `WritError` means the tool call must
+ * not run (fail closed).
+ */
+export declare class WritError extends Error {
+    /** Machine-readable code, e.g. `unavailable`, `timeout`, `protocol`, or a gateway `error.code`. */
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The writ binary could not be found or started. */
+export declare class WritUnavailableError extends WritError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The gateway did not answer within the per-request timeout. */
+export declare class WritTimeoutError extends WritError {
+    constructor(message: string);
+}
+/** The gateway wrote something that is not a valid protocol v1 response, or exited. */
+export declare class WritProtocolError extends WritError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** writ decided the call must not run (deny, rejected or unresolved ask). */
+export declare class WritBlockedError extends WritError {
+    readonly decision: Decision;
+    constructor(decision: Decision, tool: string);
+}
+/** Human-readable reason for a non-dispatching decision, naming the rule. */
+export declare function describeBlock(decision: Decision, tool: string): string;

package/dist/cjs/errors.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WritBlockedError = exports.WritProtocolError = exports.WritTimeoutError = exports.WritUnavailableError = exports.WritError = void 0;
+exports.describeBlock = describeBlock;
+/**
+ * Base class for every writ failure. Any `WritError` means the tool call must
+ * not run (fail closed).
+ */
+class WritError extends Error {
+    /** Machine-readable code, e.g. `unavailable`, `timeout`, `protocol`, or a gateway `error.code`. */
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "WritError";
+        this.code = code;
+    }
+}
+exports.WritError = WritError;
+/** The writ binary could not be found or started. */
+class WritUnavailableError extends WritError {
+    constructor(message, options) {
+        super("unavailable", message, options);
+        this.name = "WritUnavailableError";
+    }
+}
+exports.WritUnavailableError = WritUnavailableError;
+/** The gateway did not answer within the per-request timeout. */
+class WritTimeoutError extends WritError {
+    constructor(message) {
+        super("timeout", message);
+        this.name = "WritTimeoutError";
+    }
+}
+exports.WritTimeoutError = WritTimeoutError;
+/** The gateway wrote something that is not a valid protocol v1 response, or exited. */
+class WritProtocolError extends WritError {
+    constructor(message, options) {
+        super("protocol", message, options);
+        this.name = "WritProtocolError";
+    }
+}
+exports.WritProtocolError = WritProtocolError;
+/** writ decided the call must not run (deny, rejected or unresolved ask). */
+class WritBlockedError extends WritError {
+    decision;
+    constructor(decision, tool) {
+        super("blocked", describeBlock(decision, tool));
+        this.name = "WritBlockedError";
+        this.decision = decision;
+    }
+}
+exports.WritBlockedError = WritBlockedError;
+/** Human-readable reason for a non-dispatching decision, naming the rule. */
+function describeBlock(decision, tool) {
+    const rule = decision.rule_id ? `rule '${decision.rule_id}'` : "policy default";
+    const where = decision.location ? ` (${decision.location})` : "";
+    const why = decision.reason ? `: ${decision.reason}` : "";
+    const verb = decision.decision === "ask" ? "needs approval and was not approved" : "was blocked";
+    return `writ: '${tool}' ${verb} by ${rule}${where}${why}`;
+}

package/dist/cjs/guard.d.ts

@@ -0,0 +1,56 @@
+import { type Approver, type WritClient } from "./client.js";
+import type { CallerIdentity, ServerIdentity, TrustVerdict } from "./protocol.js";
+export interface GuardOptions<A extends unknown[]> {
+    client: WritClient;
+    /** Tool name as writ policies see it, e.g. `bash`, `fs.read`, `postgres.query`. */
+    tool: string;
+    /**
+     * Build the policy-visible `args` from the call's parameters. Default: the
+     * first parameter when it is a plain object, else `{ args: [...params] }`.
+     * Never include credentials.
+     */
+    args?: (...params: A) => Record<string, unknown>;
+    /** Stable id for this call (default: writ generates one). */
+    callId?: (...params: A) => string | undefined;
+    /** Default: the client's session id. */
+    sessionId?: string;
+    caller?: CallerIdentity;
+    server?: ServerIdentity | null;
+    trust?: TrustVerdict | null;
+    /** Decides deferred asks (client with `ask: "defer"`). Default: reject. */
+    approver?: Approver;
+    approvalTimeoutMs?: number;
+}
+/**
+ * Wrap a tool function so every invocation is decided by writ first and its
+ * execution recorded afterwards.
+ *
+ * - deny, rejected or unresolved ask: throws `WritBlockedError`; `fn` never runs.
+ * - any gateway failure before dispatch: throws `WritError`; `fn` never runs.
+ * - redact: returns writ's redacted output instead of the raw result.
+ * - `complete` failure after `fn` ran: throws `WritError` (the result is withheld).
+ */
+export declare function guard<A extends unknown[], R>(fn: (...params: A) => R | Promise<R>, options: GuardOptions<A>): (...params: A) => Promise<Awaited<R>>;
+/** A `{ description, parameters, execute }` tool object (Vercel AI SDK and similar). */
+export interface ExecutableTool {
+    execute?: (...params: never[]) => unknown;
+    [key: string]: unknown;
+}
+export interface GuardToolsOptions {
+    client: WritClient;
+    /** Map a tool key to the writ tool name (default: the key itself). */
+    toolName?: (key: string) => string;
+    /** Build policy-visible args from the tool's first parameter (default: the parameter itself). */
+    args?: (key: string, input: unknown) => Record<string, unknown>;
+    sessionId?: string;
+    caller?: CallerIdentity;
+    approver?: Approver;
+    approvalTimeoutMs?: number;
+}
+/**
+ * Wrap the `execute` of every tool in a record of tool objects (for example
+ * Vercel AI SDK `tools`). Tools without `execute` are returned unchanged.
+ * Extra `execute` parameters (e.g. the AI SDK's `{ toolCallId }`) are passed
+ * through, and `toolCallId` becomes writ's `call_id` when present.
+ */
+export declare function guardTools<T extends Record<string, ExecutableTool>>(tools: T, options: GuardToolsOptions): T;

package/dist/cjs/guard.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guard = guard;
+exports.guardTools = guardTools;
+const client_js_1 = require("./client.js");
+const errors_js_1 = require("./errors.js");
+const output_js_1 = require("./output.js");
+function defaultArgs(params) {
+    const first = params[0];
+    if (params.length === 1 && typeof first === "object" && first !== null && !Array.isArray(first)) {
+        return { ...first };
+    }
+    return { args: params };
+}
+/**
+ * Wrap a tool function so every invocation is decided by writ first and its
+ * execution recorded afterwards.
+ *
+ * - deny, rejected or unresolved ask: throws `WritBlockedError`; `fn` never runs.
+ * - any gateway failure before dispatch: throws `WritError`; `fn` never runs.
+ * - redact: returns writ's redacted output instead of the raw result.
+ * - `complete` failure after `fn` ran: throws `WritError` (the result is withheld).
+ */
+function guard(fn, options) {
+    const { client, tool } = options;
+    return async (...params) => {
+        const call = {
+            session_id: options.sessionId ?? client.sessionId,
+            tool,
+            args: options.args ? options.args(...params) : defaultArgs(params),
+        };
+        const callId = options.callId?.(...params);
+        if (callId !== undefined)
+            call.call_id = callId;
+        if (options.caller !== undefined)
+            call.caller = options.caller;
+        if (options.server !== undefined)
+            call.server = options.server;
+        if (options.trust !== undefined)
+            call.trust = options.trust;
+        const authorizeOptions = {
+            ...(options.approver !== undefined ? { approver: options.approver } : {}),
+            ...(options.approvalTimeoutMs !== undefined ? { approvalTimeoutMs: options.approvalTimeoutMs } : {}),
+        };
+        const decision = await client.authorize(call, authorizeOptions);
+        if (!(0, client_js_1.shouldDispatch)(decision))
+            throw new errors_js_1.WritBlockedError(decision, tool);
+        const ref = decision.ref;
+        if (ref === undefined)
+            throw new errors_js_1.WritError("protocol", "dispatching decision is missing ref");
+        let result;
+        try {
+            result = await fn(...params);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await client.complete(ref, { ok: false, output: message }).catch(() => undefined);
+            throw err;
+        }
+        const text = (0, output_js_1.outputText)(result);
+        const recorded = await client.complete(ref, text === undefined ? { ok: true } : { ok: true, output: text });
+        if (decision.decision === "redact") {
+            if (text === undefined)
+                return result;
+            if (recorded.output === undefined) {
+                throw new errors_js_1.WritError("redaction_missing", `writ: redact verdict for '${tool}' but no redacted output was returned; result withheld`);
+            }
+            return (0, output_js_1.fromRedacted)(recorded.output, result);
+        }
+        return result;
+    };
+}
+/**
+ * Wrap the `execute` of every tool in a record of tool objects (for example
+ * Vercel AI SDK `tools`). Tools without `execute` are returned unchanged.
+ * Extra `execute` parameters (e.g. the AI SDK's `{ toolCallId }`) are passed
+ * through, and `toolCallId` becomes writ's `call_id` when present.
+ */
+function guardTools(tools, options) {
+    const out = {};
+    for (const [key, tool] of Object.entries(tools)) {
+        const execute = tool.execute;
+        if (typeof execute !== "function") {
+            out[key] = tool;
+            continue;
+        }
+        const wrapped = guard((...params) => execute.apply(tool, params), {
+            client: options.client,
+            tool: options.toolName ? options.toolName(key) : key,
+            args: (...params) => {
+                const input = params[0];
+                if (options.args)
+                    return options.args(key, input);
+                return typeof input === "object" && input !== null && !Array.isArray(input)
+                    ? { ...input }
+                    : { input };
+            },
+            callId: (...params) => {
+                const ctx = params[1];
+                if (typeof ctx === "object" && ctx !== null && typeof ctx.toolCallId === "string") {
+                    return ctx.toolCallId;
+                }
+                return undefined;
+            },
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+            ...(options.caller !== undefined ? { caller: options.caller } : {}),
+            ...(options.approver !== undefined ? { approver: options.approver } : {}),
+            ...(options.approvalTimeoutMs !== undefined ? { approvalTimeoutMs: options.approvalTimeoutMs } : {}),
+        });
+        out[key] = { ...tool, execute: wrapped };
+    }
+    return out;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,9 @@
+export { WritClient, shouldDispatch } from "./client.js";
+export type { ApprovalAnswer, ApprovalRequest, Approver, AskMode, AuthorizeOptions, WritClientOptions, } from "./client.js";
+export { guard, guardTools } from "./guard.js";
+export type { ExecutableTool, GuardOptions, GuardToolsOptions } from "./guard.js";
+export { WritBlockedError, WritError, WritProtocolError, WritTimeoutError, WritUnavailableError, describeBlock, } from "./errors.js";
+export { findOnPath, locateWrit } from "./locate.js";
+export type { Launch } from "./locate.js";
+export { PROTOCOL_VERSION } from "./protocol.js";
+export type { CallerIdentity, CompleteInput, CompleteResult, Decision, DecisionKind, ServerIdentity, ToolCallInput, TrustVerdict, } from "./protocol.js";