@writ-agent/sdk 0.1.0

package/dist/cjs/claude-agent-sdk.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapClaudeTool = mapClaudeTool;
+exports.createWritIntegration = createWritIntegration;
+exports.writHooks = writHooks;
+exports.mergeHooks = mergeHooks;
+const client_js_1 = require("./client.js");
+const errors_js_1 = require("./errors.js");
+const output_js_1 = require("./output.js");
+const SHELL_TOOLS = new Set(["Bash", "PowerShell"]);
+const READ_TOOLS = new Set(["Read", "Glob", "Grep", "LS", "NotebookRead"]);
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+function asRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input)
+        ? { ...input }
+        : { input };
+}
+function firstString(args, keys) {
+    for (const k of keys) {
+        const v = args[k];
+        if (typeof v === "string")
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Map a Claude tool name + input to writ's policy vocabulary. Kept identical
+ * to `writ check --format claude-code` (crates/writ-cli/src/hook.rs):
+ * - `Bash` / `PowerShell` → `bash` (with `command`)
+ * - `Read` / `Glob` / `Grep` / `LS` / `NotebookRead` → `fs.read`; `Write` / `Edit` / `MultiEdit` / `NotebookEdit` → `fs.write` (with `path`)
+ * - `WebFetch` → `http` (with `url`); `WebSearch` → `web.search` (with `query`)
+ * - `mcp__<server>__<tool>` → tool `<tool>` with `server: { name: <server> }`
+ * - anything else keeps its SDK name.
+ * The original input fields are kept; normalized keys are added alongside.
+ */
+function mapClaudeTool(toolName, input, mcpServer) {
+    const args = asRecord(input);
+    if (SHELL_TOOLS.has(toolName)) {
+        const command = firstString(args, ["command"]);
+        return { tool: "bash", args: command === undefined ? args : { ...args, command } };
+    }
+    if (READ_TOOLS.has(toolName) || WRITE_TOOLS.has(toolName)) {
+        // An explicit string `path` wins; otherwise the tool's native key.
+        const path = firstString(args, ["path", "file_path", "notebook_path"]);
+        const tool = WRITE_TOOLS.has(toolName) ? "fs.write" : "fs.read";
+        return { tool, args: path === undefined ? args : { ...args, path } };
+    }
+    if (toolName === "WebFetch")
+        return { tool: "http", args };
+    if (toolName === "WebSearch")
+        return { tool: "web.search", args };
+    if (toolName.startsWith("mcp__")) {
+        const rest = toolName.slice("mcp__".length);
+        const sep = rest.indexOf("__");
+        if (sep > 0 && sep < rest.length - 2) {
+            const serverName = mcpServer?.name ?? rest.slice(0, sep);
+            return {
+                tool: rest.slice(sep + 2),
+                args,
+                server: { name: serverName, transport: "unknown" },
+            };
+        }
+    }
+    return { tool: toolName, args };
+}
+const MAX_TRACKED = 10_000;
+function preOutput(permissionDecision, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason: reason,
+        },
+    };
+}
+function allowReason(d) {
+    const rule = d.rule_id ? `rule '${d.rule_id}'` : "policy default";
+    return d.decision === "redact" ? `writ: allowed with redaction by ${rule}` : `writ: allowed by ${rule}`;
+}
+function askReason(d, tool) {
+    const rule = d.rule_id ? `rule '${d.rule_id}'` : "policy default";
+    const where = d.location ? ` (${d.location})` : "";
+    const why = d.reason ? `: ${d.reason}` : "";
+    return `writ: '${tool}' needs approval by ${rule}${where}${why}`;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sameJson(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build writ hooks and a `canUseTool` callback for the Claude Agent SDK.
+ * Every failure path denies the tool (fail closed): a hook never throws.
+ */
+function createWritIntegration(options) {
+    const { client } = options;
+    const caller = options.caller ?? client.caller ?? { agent: "claude-agent-sdk" };
+    const mapTool = options.mapTool ?? mapClaudeTool;
+    const onAllow = options.onAllow ?? "allow";
+    const dispatched = new Map();
+    const pendingAsks = new Map();
+    const track = (map, key, value) => {
+        if (map.size >= MAX_TRACKED) {
+            const oldest = map.keys().next();
+            if (oldest.done !== true)
+                map.delete(oldest.value);
+        }
+        map.set(key, value);
+    };
+    const buildCall = (input, toolUseID) => {
+        const mapped = mapTool(input.tool_name, input.tool_input, input.mcp_server);
+        const call = {
+            session_id: input.session_id || client.sessionId,
+            tool: mapped.tool,
+            args: mapped.args,
+            // Subagent tool calls carry the subagent id as the non-human identity.
+            caller: input.agent_id ? { ...caller, non_human_id: input.agent_id } : caller,
+        };
+        const id = input.tool_use_id || toolUseID;
+        if (id)
+            call.call_id = id;
+        if (mapped.server !== undefined)
+            call.server = mapped.server;
+        return call;
+    };
+    const preToolUse = async (input, toolUseID, { signal }) => {
+        if (input.hook_event_name !== "PreToolUse")
+            return {};
+        const key = input.tool_use_id || toolUseID || "";
+        try {
+            if (signal.aborted)
+                return preOutput("deny", "writ: aborted before a decision (fail closed)");
+            const call = buildCall(input, toolUseID);
+            let decision;
+            if (options.approver !== undefined) {
+                decision = await client.authorize(call, {
+                    approver: options.approver,
+                    ...(options.approvalTimeoutMs !== undefined ? { approvalTimeoutMs: options.approvalTimeoutMs } : {}),
+                });
+            }
+            else {
+                decision = await client.decide(call);
+                if (decision.decision === "ask" && decision.approval === "required") {
+                    if (decision.ref === undefined)
+                        throw new errors_js_1.WritError("protocol", "deferred ask is missing ref");
+                    if (options.canUseTool !== undefined && key !== "") {
+                        track(pendingAsks, key, { ref: decision.ref, decision });
+                        return preOutput("ask", askReason(decision, input.tool_name));
+                    }
+                    decision = await client.resolve(decision.ref, false, "adapter:no-approver");
+                }
+            }
+            if (!(0, client_js_1.shouldDispatch)(decision) || decision.ref === undefined) {
+                return preOutput("deny", (0, errors_js_1.describeBlock)(decision, input.tool_name));
+            }
+            if (key === "" && decision.decision === "redact") {
+                return preOutput("deny", `writ: redact verdict for '${input.tool_name}' needs a tool_use_id to apply (fail closed)`);
+            }
+            if (key !== "")
+                track(dispatched, key, { ref: decision.ref, decision });
+            return onAllow === "passthrough" ? {} : preOutput("allow", allowReason(decision));
+        }
+        catch (err) {
+            return preOutput("deny", `writ: cannot authorize '${input.tool_name}' (fail closed): ${errorText(err)}`);
+        }
+    };
+    const postToolUse = async (input, toolUseID) => {
+        if (input.hook_event_name !== "PostToolUse")
+            return {};
+        const post = input;
+        const key = post.tool_use_id || toolUseID || "";
+        const tracked = dispatched.get(key);
+        if (tracked === undefined) {
+            const unresolved = pendingAsks.get(key);
+            if (unresolved !== undefined) {
+                // The tool ran although its writ ask was never resolved: record the
+                // rejection and keep the output away from the model.
+                pendingAsks.delete(key);
+                await client.resolve(unresolved.ref, false, "adapter:unresolved-ask").catch(() => undefined);
+                return {
+                    systemMessage: `writ: '${post.tool_name}' ran without a resolved writ approval; output withheld`,
+                    hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: output_js_1.WITHHELD_OUTPUT },
+                };
+            }
+            return {};
+        }
+        dispatched.delete(key);
+        const text = (0, output_js_1.outputText)(post.tool_response);
+        const redact = tracked.decision.decision === "redact";
+        try {
+            const recorded = await client.complete(tracked.ref, text === undefined ? { ok: true } : { ok: true, output: text });
+            if (!redact || text === undefined)
+                return {};
+            if (recorded.output === undefined) {
+                return {
+                    systemMessage: "writ: redact verdict but no redacted output was returned; output withheld",
+                    hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: output_js_1.WITHHELD_OUTPUT },
+                };
+            }
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PostToolUse",
+                    updatedToolOutput: (0, output_js_1.fromRedacted)(recorded.output, post.tool_response),
+                },
+            };
+        }
+        catch (err) {
+            const message = `writ: could not record '${post.tool_name}' execution: ${errorText(err)}`;
+            if (!redact)
+                return { systemMessage: message };
+            return {
+                systemMessage: `${message}; output withheld`,
+                hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: output_js_1.WITHHELD_OUTPUT },
+            };
+        }
+    };
+    const postToolUseFailure = async (input, toolUseID) => {
+        if (input.hook_event_name !== "PostToolUseFailure")
+            return {};
+        const failed = input;
+        const key = failed.tool_use_id || toolUseID || "";
+        const tracked = dispatched.get(key);
+        if (tracked === undefined)
+            return {};
+        dispatched.delete(key);
+        await client.complete(tracked.ref, { ok: false, output: failed.error }).catch(() => undefined);
+        return {};
+    };
+    const canUseTool = async (toolName, input, opts) => {
+        const pending = pendingAsks.get(opts.toolUseID);
+        if (pending === undefined) {
+            if (options.canUseTool !== undefined) {
+                try {
+                    const res = await options.canUseTool(toolName, input, opts);
+                    return res ?? { behavior: "deny", message: "writ: permission callback returned no result (fail closed)" };
+                }
+                catch (err) {
+                    return { behavior: "deny", message: `writ: permission callback failed (fail closed): ${errorText(err)}` };
+                }
+            }
+            return { behavior: "deny", message: `writ: no approver for '${toolName}' (fail closed)` };
+        }
+        pendingAsks.delete(opts.toolUseID);
+        let approved = false;
+        try {
+            const res = options.canUseTool !== undefined && !opts.signal.aborted ? await options.canUseTool(toolName, input, opts) : null;
+            // writ decided on the original input; an edited input is not what was approved.
+            approved = res?.behavior === "allow" && (res.updatedInput === undefined || sameJson(res.updatedInput, input));
+        }
+        catch {
+            approved = false;
+        }
+        try {
+            const decision = await client.resolve(pending.ref, approved, "sdk:canUseTool");
+            if (!(0, client_js_1.shouldDispatch)(decision)) {
+                return { behavior: "deny", message: (0, errors_js_1.describeBlock)({ ...pending.decision, ...decision }, toolName) };
+            }
+            track(dispatched, opts.toolUseID, { ref: decision.ref ?? pending.ref, decision });
+            // No updatedPermissions: a persistent SDK allow rule would bypass future writ asks.
+            return { behavior: "allow", updatedInput: input };
+        }
+        catch (err) {
+            return { behavior: "deny", message: `writ: cannot resolve approval for '${toolName}' (fail closed): ${errorText(err)}` };
+        }
+    };
+    const matcher = (hook) => {
+        const m = { hooks: [hook] };
+        if (options.matcher !== undefined)
+            m.matcher = options.matcher;
+        if (options.hookTimeoutSec !== undefined)
+            m.timeout = options.hookTimeoutSec;
+        return m;
+    };
+    return {
+        hooks: {
+            PreToolUse: [matcher(preToolUse)],
+            PostToolUse: [matcher(postToolUse)],
+            PostToolUseFailure: [matcher(postToolUseFailure)],
+        },
+        canUseTool,
+        preToolUse,
+        postToolUse,
+        postToolUseFailure,
+    };
+}
+/** Just the `hooks` option. Deferred asks need `approver` (or use `createWritIntegration` for `canUseTool`). */
+function writHooks(options) {
+    return createWritIntegration(options).hooks;
+}
+/**
+ * Merge writ's hooks with your own `hooks` option. writ's matchers come first
+ * for each event; yours are kept.
+ */
+function mergeHooks(...sets) {
+    const out = {};
+    for (const set of sets) {
+        if (set === undefined)
+            continue;
+        for (const [event, matchers] of Object.entries(set)) {
+            if (matchers === undefined)
+                continue;
+            out[event] = [...(out[event] ?? []), ...matchers];
+        }
+    }
+    return out;
+}

package/dist/cjs/client.d.ts

@@ -0,0 +1,107 @@
+import { type CallerIdentity, type CompleteInput, type CompleteResult, type Decision, type ToolCallInput } from "./protocol.js";
+/** What `writ check` does with an `ask` verdict. */
+export type AskMode = "deny" | "defer";
+export interface WritClientOptions {
+    /** Path to the writ binary. Default: `WRIT_BIN`, then `writ` on PATH. A `.js`/`.mjs`/`.cjs` path runs under Node. */
+    bin?: string;
+    /**
+     * Explicit program to spawn instead of locating writ (e.g. `process.execPath`
+     * for a test gateway). `args` are placed before writ's own arguments.
+     */
+    command?: string;
+    args?: string[];
+    /** `--policy` (default: writ's own default, `./writ.yaml`). */
+    policy?: string;
+    /** `--ledger` (default: writ's own default, `.writ/ledger.jsonl`). */
+    ledger?: string;
+    /**
+     * `--ask deny` (default, fail closed) or `--ask defer`, which hands the
+     * decision to an `approver` callback or the agent's own UI.
+     */
+    ask?: AskMode;
+    /** Per-request timeout in ms (default 30000). A timeout kills the gateway and fails closed. */
+    timeoutMs?: number;
+    /** Default caller identity for calls that do not set one. */
+    caller?: CallerIdentity;
+    /** Default session id for calls that do not set one (default: a random UUID per client). */
+    sessionId?: string;
+    /** Working directory for the gateway process. */
+    cwd?: string;
+    /** Environment for the gateway process (default: `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Start a fresh gateway after a crash or timeout (default true). In-flight requests still fail closed. */
+    respawn?: boolean;
+    /** Receives the gateway's stderr (diagnostics). */
+    onStderr?: (text: string) => void;
+    /** Longest accepted response line in bytes (default 16 MiB). */
+    maxLineBytes?: number;
+}
+/** Input to an `approver` callback for a deferred ask. */
+export interface ApprovalRequest {
+    call: ToolCallInput;
+    decision: Decision;
+    /** Aborted when the ask's `timeout_ms` elapses. */
+    signal: AbortSignal;
+}
+export type ApprovalAnswer = boolean | {
+    approved: boolean;
+    approver?: string;
+};
+/** Obtains a human decision for a deferred ask. Anything but an explicit approval is a denial. */
+export type Approver = (request: ApprovalRequest) => ApprovalAnswer | Promise<ApprovalAnswer>;
+export interface AuthorizeOptions {
+    /** Called for a deferred ask (`--ask defer`). Without one, deferred asks are rejected. */
+    approver?: Approver;
+    /** Upper bound on waiting for the approver when the ask carries no `timeout_ms` (default 5 min). */
+    approvalTimeoutMs?: number;
+}
+/** True only when a decision says the tool may run. */
+export declare function shouldDispatch(decision: Decision): boolean;
+/**
+ * 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.
+ */
+export declare class WritClient implements AsyncDisposable {
+    readonly askMode: AskMode;
+    readonly sessionId: string;
+    readonly caller: CallerIdentity | undefined;
+    private readonly options;
+    private readonly timeoutMs;
+    private readonly maxLineBytes;
+    private proc;
+    private queue;
+    private buffer;
+    private seq;
+    private closed;
+    private broken;
+    private stderrTail;
+    constructor(options?: WritClientOptions);
+    /** The argv (after the program) passed to writ. */
+    gatewayArgs(): string[];
+    /** Ask writ for a verdict. Rejects on any gateway failure. */
+    decide(call: ToolCallInput): Promise<Decision>;
+    /** Resolve a deferred ask. The response is a final decision. */
+    resolve(ref: string, approved: boolean, approver?: string): Promise<Decision>;
+    /** Record the execution of a dispatched call. For redact, `output` in the result is the redacted text. */
+    complete(ref: string, input: CompleteInput): Promise<CompleteResult>;
+    /**
+     * 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.
+     */
+    authorize(call: ToolCallInput, options?: AuthorizeOptions): Promise<Decision>;
+    /** Close stdin, wait briefly for writ to exit, then kill it. Idempotent. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private request;
+    private ensureProcess;
+    private resolveLaunch;
+    private onData;
+    private onLine;
+    /** Fail every in-flight request and drop the process (fail closed). */
+    private poison;
+    private failAll;
+    /** Keep the event loop alive only while requests are in flight. */
+    private setRef;
+}