@writ-agent/sdk 0.1.0

package/dist/esm/guard.js

@@ -0,0 +1,109 @@
+import { shouldDispatch } from "./client.js";
+import { WritBlockedError, WritError } from "./errors.js";
+import { fromRedacted, outputText } from "./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).
+ */
+export 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 (!shouldDispatch(decision))
+            throw new WritBlockedError(decision, tool);
+        const ref = decision.ref;
+        if (ref === undefined)
+            throw new 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 = 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 WritError("redaction_missing", `writ: redact verdict for '${tool}' but no redacted output was returned; result withheld`);
+            }
+            return 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.
+ */
+export 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/esm/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";

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { WritClient, shouldDispatch } from "./client.js";
+export { guard, guardTools } from "./guard.js";
+export { WritBlockedError, WritError, WritProtocolError, WritTimeoutError, WritUnavailableError, describeBlock, } from "./errors.js";
+export { findOnPath, locateWrit } from "./locate.js";
+export { PROTOCOL_VERSION } from "./protocol.js";

package/dist/esm/locate.d.ts

@@ -0,0 +1,18 @@
+/** A resolved program + leading arguments to spawn. */
+export interface Launch {
+    command: string;
+    args: string[];
+}
+/**
+ * Turn an explicit binary path into a launch. A `.js`/`.mjs`/`.cjs` path runs
+ * under the current Node executable (useful for test gateways on Windows,
+ * where scripts are not directly executable).
+ */
+export declare function launchFor(bin: string): Launch;
+/** Search PATH for `writ` (`writ.exe` / `writ.com` on Windows). */
+export declare function findOnPath(name?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Locate writ: explicit `bin`, then `WRIT_BIN`, then PATH. Throws
+ * `WritUnavailableError` when nothing is found.
+ */
+export declare function locateWrit(bin?: string, env?: NodeJS.ProcessEnv): Launch;

package/dist/esm/locate.js

@@ -0,0 +1,59 @@
+import { statSync } from "node:fs";
+import { delimiter, extname, isAbsolute, join, resolve } from "node:path";
+import { WritUnavailableError } from "./errors.js";
+const SCRIPT_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
+function isFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Turn an explicit binary path into a launch. A `.js`/`.mjs`/`.cjs` path runs
+ * under the current Node executable (useful for test gateways on Windows,
+ * where scripts are not directly executable).
+ */
+export function launchFor(bin) {
+    const full = isAbsolute(bin) ? bin : resolve(bin);
+    if (!isFile(full)) {
+        throw new WritUnavailableError(`writ binary not found at '${full}' (fail closed: no tool call will run)`);
+    }
+    if (SCRIPT_EXTENSIONS.has(extname(full).toLowerCase())) {
+        return { command: process.execPath, args: [full] };
+    }
+    return { command: full, args: [] };
+}
+/** Search PATH for `writ` (`writ.exe` / `writ.com` on Windows). */
+export function findOnPath(name = "writ", env = process.env, platform = process.platform) {
+    const pathVar = env.PATH ?? env.Path ?? env.path ?? "";
+    const dirs = pathVar.split(platform === "win32" ? ";" : delimiter).filter((d) => d.length > 0);
+    // Batch files (.cmd/.bat) need a shell to run; they are not accepted.
+    const names = platform === "win32" ? [`${name}.exe`, `${name}.com`] : [name];
+    for (const dir of dirs) {
+        const clean = dir.replace(/^"(.*)"$/, "$1");
+        for (const n of names) {
+            const candidate = join(clean, n);
+            if (isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Locate writ: explicit `bin`, then `WRIT_BIN`, then PATH. Throws
+ * `WritUnavailableError` when nothing is found.
+ */
+export function locateWrit(bin, env = process.env) {
+    if (bin !== undefined && bin !== "")
+        return launchFor(bin);
+    const fromEnv = env.WRIT_BIN;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return launchFor(fromEnv);
+    const found = findOnPath("writ", env);
+    if (found === undefined) {
+        throw new WritUnavailableError("writ binary not found: set WRIT_BIN or put writ on PATH (fail closed: no tool call will run)");
+    }
+    return { command: found, args: [] };
+}

package/dist/esm/output.d.ts

@@ -0,0 +1,10 @@
+/** Render a tool result as the text writ hashes (and redacts). */
+export declare function outputText(result: unknown): string | undefined;
+/**
+ * Map writ's redacted text back onto the original result's shape: strings stay
+ * strings; structured results are re-parsed from the redacted JSON when that
+ * still parses, otherwise the redacted text itself is returned.
+ */
+export declare function fromRedacted(redacted: string, original: unknown): unknown;
+/** Replacement text when a result must be withheld (redaction could not be applied). */
+export declare const WITHHELD_OUTPUT = "[writ: tool output withheld because redaction could not be applied]";

package/dist/esm/output.js

@@ -0,0 +1,33 @@
+/** Render a tool result as the text writ hashes (and redacts). */
+export function outputText(result) {
+    if (result === undefined)
+        return undefined;
+    if (typeof result === "string")
+        return result;
+    if (result instanceof Uint8Array)
+        return Buffer.from(result).toString("utf8");
+    try {
+        const json = JSON.stringify(result);
+        return json === undefined ? String(result) : json;
+    }
+    catch {
+        return String(result);
+    }
+}
+/**
+ * Map writ's redacted text back onto the original result's shape: strings stay
+ * strings; structured results are re-parsed from the redacted JSON when that
+ * still parses, otherwise the redacted text itself is returned.
+ */
+export function fromRedacted(redacted, original) {
+    if (typeof original === "string" || original === undefined || original instanceof Uint8Array)
+        return redacted;
+    try {
+        return JSON.parse(redacted);
+    }
+    catch {
+        return redacted;
+    }
+}
+/** Replacement text when a result must be withheld (redaction could not be applied). */
+export const WITHHELD_OUTPUT = "[writ: tool output withheld because redaction could not be applied]";

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/protocol.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Wire types for the writ hook gateway (`writ check --stdio`), protocol v1.
+ * Source of truth: docs/INTERFACES.md, Contract 6 (and Contract 1 for the
+ * `call` envelope). Additive-only: unknown response fields are ignored.
+ */
+export declare const PROTOCOL_VERSION: 1;
+/** Who is making the call (Contract 1 `CallerIdentity`). */
+export interface CallerIdentity {
+    agent: string;
+    agent_version?: string | null;
+    user?: string | null;
+    non_human_id?: string | null;
+}
+/** Identity of the (MCP) server a call targets (Contract 1 `ServerIdentity`). */
+export interface ServerIdentity {
+    name: string;
+    /** "stdio" | "sse" | "http", or another transport label. */
+    transport: string;
+    version?: string | null;
+}
+/** External scanner verdict (Contract 1 `TrustVerdict`). */
+export type TrustVerdict = "verified" | "unverified" | "malicious";
+/**
+ * The `call` object of a `decide` request. writ sets `mode = SdkHook` and
+ * `captured_at` itself. Credentials must never appear in `args`.
+ */
+export interface ToolCallInput {
+    /** Optional; writ generates one when omitted. */
+    call_id?: string;
+    session_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    /** Defaults to the client's `caller`, then `{ agent: "unknown" }`. */
+    caller?: CallerIdentity;
+    server?: ServerIdentity | null;
+    trust?: TrustVerdict | null;
+}
+export type DecisionKind = "allow" | "deny" | "ask" | "redact";
+/** A validated `decide` or `resolve` response. */
+export interface Decision {
+    decision: DecisionKind;
+    /** True only for allow / redact / approved ask. */
+    dispatch: boolean;
+    /** Opaque handle to pass back to `resolve` / `complete`. */
+    ref?: string;
+    rule_id?: string;
+    reason?: string;
+    location?: string;
+    /** "required" when `--ask defer` deferred the ask to the adapter. */
+    approval?: "required";
+    irreversible?: boolean;
+    timeout_ms?: number;
+    /** Redaction patterns (writ applies them on `complete`). */
+    patterns?: string[];
+}
+/** A validated `complete` response. */
+export interface CompleteResult {
+    recorded: true;
+    /** Redacted output; present only for a redact verdict. */
+    output?: string;
+}
+export interface CompleteInput {
+    ok: boolean;
+    exit?: number;
+    /** Tool result as text. Hashed into the ledger, never stored. */
+    output?: string;
+}

package/dist/esm/protocol.js

@@ -0,0 +1,6 @@
+/**
+ * Wire types for the writ hook gateway (`writ check --stdio`), protocol v1.
+ * Source of truth: docs/INTERFACES.md, Contract 6 (and Contract 1 for the
+ * `call` envelope). Additive-only: unknown response fields are ignored.
+ */
+export const PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@writ-agent/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript/Node client for the writ hook gateway: policy-checked, ledger-recorded tool calls for AI agents (Claude Agent SDK hooks, generic tool wrappers).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/writ-agent/writ.git",
+    "directory": "adapters/typescript"
+  },
+  "keywords": [
+    "writ",
+    "ai-agents",
+    "authorization",
+    "policy",
+    "audit-ledger",
+    "claude-agent-sdk",
+    "tool-calls"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./claude-agent-sdk": {
+      "import": {
+        "types": "./dist/esm/claude-agent-sdk.d.ts",
+        "default": "./dist/esm/claude-agent-sdk.js"
+      },
+      "require": {
+        "types": "./dist/cjs/claude-agent-sdk.d.ts",
+        "default": "./dist/cjs/claude-agent-sdk.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "claude-agent-sdk": [
+        "./dist/cjs/claude-agent-sdk.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node scripts/clean.mjs dist build-test",
+    "build": "node scripts/clean.mjs dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "node scripts/lint.mjs",
+    "build:test": "node scripts/clean.mjs build-test && tsc -p tsconfig.test.json",
+    "test": "npm run build:test && node --test --test-concurrency=1 \"build-test/test/*.test.js\"",
+    "test:e2e": "npm run build:test && node --test \"build-test/test/e2e.test.js\"",
+    "prepublishOnly": "npm run build && npm run typecheck && npm run lint && npm test"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.280"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.280",
+    "@types/node": "^24.13.6",
+    "typescript": "~5.9",
+    "zod": "^4.6.5"
+  },
+  "author": "Bhaskar Gurram <gurrambhaskar.ai@gmail.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/writ-agent/writ/tree/main/adapters/typescript#readme",
+  "bugs": {
+    "url": "https://github.com/writ-agent/writ/issues"
+  }
+}