underwrit-client 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Underwrit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# underwrit-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client for an [Underwrit](https://underwrit.io) data plane, for agent runtimes in TypeScript
+and JavaScript. `fetch`-based, no dependencies, Node 18+ or any modern runtime.
+
+Underwrit decides whether an agent's tool call may run, holds it for a person when it should, and hands
+back hash-chained, signed evidence of what happened. This package is the twenty lines between your
+runtime and that API.
+
+```ts
+import { Underwrit, Held } from "underwrit-client";
+
+const underwrit = new Underwrit("https://underwrit.example.com", process.env.UNDERWRIT_AGENT_TOKEN!);
+const s = await underwrit.session({ agent: "ops-assistant", environment: "production",
+                               intent: "Restart api during incident 4417" });
+
+const logs = await s.call("k8s/get_k8s_logs", getLogs, { pod: "api-1" });
+try {
+  await s.call("k8s/rollout_restart", restart, { deployment: "api", namespace: "prod" });
+} catch (e) {
+  if (e instanceof Held) {
+    park(e.decision.id);            // a person answers in the console, then:
+    await s.resume(e.decision.id, restart, { deployment: "api", namespace: "prod" },
+                   { verify: (r) => ({ status: "passed", checks: [{ name: "rollout", ok: true }] }) });
+  } else throw e;
+}
+await s.close();
+```
+
+- `call()` decides, runs the function, and records the outcome. It throws `Held` when the data
+  plane says `act: "hold"` (enforcement on, verdict held or denied). In shadow mode nothing is
+  thrown and the verdict is still recorded.
+- `resume()` claims an approval with the same arguments immediately before executing. The claim is
+  refused if the arguments or stated preconditions changed, the approval expired, the policy now
+  refuses it, or it was already used.
+- Errors whose message says "timeout" are recorded as `uncertain`; the data plane refuses a blind
+  retry until someone reconciles it.
+- `verify` records what was observed afterwards, separately from whether the call succeeded.
+- 429 and 503 are retried honouring `Retry-After` (three times, capped at thirty seconds).
+- `decide(..., { signals: { taint: true, risk: 80, source: "my-classifier" } })` lets an external
+  classifier raise taint or risk; it can never lower them.
+- Every decision carries `receipt.seq`; `underwrit.receipt(seq)` returns the Merkle inclusion proof and
+  the signed checkpoint once one covers the entry.
+
+- `decide(..., { usage, delegation, components })` carries the 1.0 inputs; `preview()` asks the
+  gate without recording; `gates()` lists the stages and codes.
+- `verify()`, `verificationsDue()`, `approvalLoad()`, `scopeHolds()` and `probeScopeHold()` map to
+  their routes one for one.
+- `compensate(id, tool, args, reason)` proposes an undo for an action whose outcome is unknown. It
+  always goes to a person and does not clear the original's scope hold.
+
+`underwrit-client/vercel` is a policy adapter for the Vercel AI SDK. The Python client, the MCP stdio
+server and the REST reference are documented at https://underwrit.io.
+
+MIT.

package/dist/durable.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Durable suspension for TypeScript workflow engines: a held step stops the run instead of holding
+ * a process open, and the plane's signed resume wakes it.
+ *
+ *   import { verifyResume, Resumer, proposeDurable, restateResolver, inngestSender } from "underwrit-client/durable";
+ *
+ *   // In a step: decide, and on a hold park it under the engine's key.
+ *   const d = await proposeDurable(session, "bank/send_money", args, { kind: "inngest", key: runId, resumeUrl });
+ *   if (d.act === "hold") {
+ *     const ev = await step.waitForEvent("underwrit", { event: INNGEST_EVENT, timeout: "24h",
+ *                                                       if: `async.data.decision == '${d.id}'` });
+ *   }
+ *
+ *   // In the web handler the plane calls (UNDERWRIT_RESUME_ALLOW):
+ *   const resumer = new Resumer(uw, process.env.UNDERWRIT_RESUME_WEBHOOK_SECRET!)
+ *     .on("restate", restateResolver("http://restate:8080"))
+ *     .on("inngest", inngestSender(process.env.INNGEST_EVENT_KEY!));
+ *   await resumer.handle(rawBody, headers);
+ *
+ * A resume is acknowledged after its handler returns, so one delivered twice resumes once, and the
+ * executing step claims the approval with the same arguments before it runs. MIT, like the client.
+ */
+import type { Session, Underwrit } from "./index.js";
+export declare const INNGEST_EVENT = "underwrit/decision.resolved";
+export interface Resume {
+    event: "decision.resume";
+    decision: string;
+    kind: string;
+    key: string;
+    state?: Record<string, unknown>;
+    outcome: "approved" | "denied" | "expired";
+}
+export declare class BadResume extends Error {
+}
+/** The resume, if the plane signed it (HMAC-SHA256 over `timestamp.body`) within `toleranceS`. */
+export declare function verifyResume(body: string, headers: Record<string, string | undefined>, secret: string, toleranceS?: number, nowS?: number): Promise<Resume>;
+export type Handler = (resume: Resume) => unknown | Promise<unknown>;
+export declare class Resumer {
+    private client;
+    private secret;
+    private handlers;
+    constructor(client: Underwrit, secret?: string);
+    on(kind: string, handler: Handler): this;
+    dispatch(resume: Resume): Promise<{
+        result: unknown;
+        alreadyAcked: boolean;
+    }>;
+    handle(body: string, headers: Record<string, string | undefined>): Promise<{
+        result: unknown;
+        alreadyAcked: boolean;
+    }>;
+    /** On start-up: every settled, unacknowledged park, for resumes whose webhook was lost. */
+    catchUp(): Promise<{
+        result: unknown;
+        alreadyAcked: boolean;
+    }[]>;
+}
+/** Decide; on a hold, park it under the engine's key and return at once. */
+export declare function proposeDurable(session: Session, tool: string, args: Record<string, unknown>, park: {
+    kind: string;
+    key: string;
+    resumeUrl?: string;
+}): Promise<import("./index.js").Decision>;
+/** Restate: resolve the awakeable the handler is suspended on (`key` is the awakeable id). */
+export declare function restateResolver(ingress: string, fetchImpl?: typeof fetch): Handler;
+/** Inngest: send the event `step.waitForEvent` matches on `async.data.decision`. */
+export declare function inngestSender(eventKey: string, base?: string, fetchImpl?: typeof fetch): Handler;
+/** Temporal (TypeScript SDK): signal the workflow; `client` is a `@temporalio/client` Client. */
+export declare function temporalSignaller(client: {
+    workflow: {
+        getHandle(id: string): {
+            signal(name: string, arg: unknown): Promise<void>;
+        };
+    };
+}, signal?: string): Handler;

package/dist/durable.js

@@ -0,0 +1,118 @@
+export const INNGEST_EVENT = "underwrit/decision.resolved";
+export class BadResume extends Error {
+}
+async function subtle() {
+    const g = globalThis.crypto;
+    if (g?.subtle)
+        return g.subtle;
+    const mod = await import("node:" + "crypto"); // Node 18 without the global
+    return mod.webcrypto.subtle;
+}
+function hex(buf) {
+    return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function same(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** The resume, if the plane signed it (HMAC-SHA256 over `timestamp.body`) within `toleranceS`. */
+export async function verifyResume(body, headers, secret, toleranceS = 300, nowS = Date.now() / 1000) {
+    const h = {};
+    for (const [k, v] of Object.entries(headers))
+        if (v !== undefined)
+            h[k.toLowerCase()] = String(v);
+    if (secret) {
+        const ts = h["x-underwrit-timestamp"] ?? "", sig = h["x-underwrit-signature"] ?? "";
+        if (!ts || !sig.startsWith("sha256="))
+            throw new BadResume("unsigned resume");
+        const s = await subtle();
+        const key = await s.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const want = hex(await s.sign("HMAC", key, new TextEncoder().encode(`${ts}.${body}`)));
+        if (!same(want, sig.slice(7)))
+            throw new BadResume("signature does not verify");
+        if (!(Math.abs(nowS - Number(ts)) <= toleranceS))
+            throw new BadResume("resume is too old");
+    }
+    const doc = JSON.parse(body);
+    if (doc.event !== "decision.resume")
+        throw new BadResume("not a resume");
+    return doc;
+}
+export class Resumer {
+    client;
+    secret;
+    handlers = new Map();
+    constructor(client, secret = "") {
+        this.client = client;
+        this.secret = secret;
+    }
+    on(kind, handler) { this.handlers.set(kind, handler); return this; }
+    async dispatch(resume) {
+        const handler = this.handlers.get(resume.kind) ?? this.handlers.get("*");
+        if (!handler)
+            throw new Error(`no handler for ${resume.kind} resumes`);
+        const result = await handler(resume);
+        const ack = await this.client.ackParked(resume.decision);
+        return { result, alreadyAcked: Boolean(ack.alreadyAcked) };
+    }
+    async handle(body, headers) {
+        return this.dispatch(await verifyResume(body, headers, this.secret));
+    }
+    /** On start-up: every settled, unacknowledged park, for resumes whose webhook was lost. */
+    async catchUp() {
+        const { parked } = await this.client.parked({ settled: true });
+        const out = [];
+        for (const p of parked ?? []) {
+            if (p.ackedAt)
+                continue;
+            out.push(await this.dispatch({ event: "decision.resume", decision: String(p.decision), kind: String(p.kind),
+                key: String(p.key), state: p.state,
+                outcome: String(p.outcome) }));
+        }
+        return out;
+    }
+}
+/** Decide; on a hold, park it under the engine's key and return at once. */
+export async function proposeDurable(session, tool, args, park) {
+    const d = await session.underwrit.decide(session.id, tool, args);
+    if (d.act === "hold")
+        await session.underwrit.park(d.id, park);
+    return d;
+}
+/** Restate: resolve the awakeable the handler is suspended on (`key` is the awakeable id). */
+export function restateResolver(ingress, fetchImpl = fetch) {
+    const base = ingress.replace(/\/+$/, "");
+    return async (r) => {
+        const res = await fetchImpl(`${base}/restate/awakeables/${encodeURIComponent(r.key)}/resolve`, {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ decision: r.decision, outcome: r.outcome })
+        });
+        if (!res.ok)
+            throw new Error(`restate answered ${res.status}`);
+        return r.key;
+    };
+}
+/** Inngest: send the event `step.waitForEvent` matches on `async.data.decision`. */
+export function inngestSender(eventKey, base = "https://inn.gs", fetchImpl = fetch) {
+    return async (r) => {
+        const res = await fetchImpl(`${base.replace(/\/+$/, "")}/e/${eventKey}`, {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: INNGEST_EVENT, id: `underwrit-${r.decision}`,
+                data: { decision: r.decision, outcome: r.outcome, run: r.key } })
+        });
+        if (!res.ok)
+            throw new Error(`inngest answered ${res.status}`);
+        return r.key;
+    };
+}
+/** Temporal (TypeScript SDK): signal the workflow; `client` is a `@temporalio/client` Client. */
+export function temporalSignaller(client, signal = "underwrit_resume") {
+    return async (r) => {
+        await client.workflow.getHandle(r.key).signal(signal, { decision: r.decision, outcome: r.outcome });
+        return r.key;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+/** underwrit-client for TypeScript. fetch-based, no dependencies.
+ *
+ *  Mirrors the Python client: `call()` decides, runs, and records; it throws `Held` when the data
+ *  plane says `act: "hold"`. `resume()` claims an approval with the same arguments before running. */
+export interface Decision {
+    id: string;
+    session: string;
+    verdict: string;
+    reasons: string[];
+    enforced: boolean;
+    taint: string[];
+    kinds: string[];
+    act: "proceed" | "hold";
+    argsDigest: string;
+    policyVersion: number;
+    duplicate?: boolean;
+    budgeted?: boolean;
+    risk?: number;
+    authority?: {
+        status: string;
+        fields: string[];
+    };
+    receipt?: {
+        seq: number;
+        hash: string;
+        prevHash?: string;
+        proof: string;
+    };
+    codes?: string[];
+    scope?: string;
+    hold?: string | null;
+    compensates?: string;
+    basis?: string;
+}
+/** The 1.0 decide inputs. Recorded as names and digests in the chain, never values. */
+export interface V1Inputs {
+    /** What this call costs, by unit: `{ usd: 0.42, tokens: 1800 }`. Spend limits sum these. */
+    usage?: Record<string, number>;
+    /** The agents that proposed the call, outermost first. */
+    delegation?: (string | Record<string, unknown>)[];
+    /** What the agent is built from: model, prompt digest, tool versions. */
+    components?: Record<string, unknown>;
+}
+export interface DecideExtra extends V1Inputs {
+    preconditions?: unknown;
+    idempotencyKey?: string;
+    signals?: Signals;
+    scope?: string;
+    toolDefinitionDigest?: string;
+}
+export interface Preview extends Omit<Decision, "id" | "session" | "argsDigest"> {
+    preview: true;
+    recorded: false;
+    stages: string[];
+}
+export interface Gates {
+    stages: {
+        stage: string;
+        asks: string;
+        codes: {
+            code: string;
+            meaning: string;
+        }[];
+    }[];
+}
+export interface Signals {
+    taint?: boolean;
+    risk?: number;
+    source?: string;
+}
+export interface Receipt {
+    seq: number;
+    pending?: boolean;
+    leafIndex?: number;
+    treeSize?: number;
+    root?: string;
+    proof?: string[];
+    checkpoint?: string;
+    keyId?: string;
+    witnessed?: boolean;
+}
+export interface Claim {
+    ok: boolean;
+    act: "proceed" | "hold";
+    enforced: boolean;
+    reason: string;
+    decision: Record<string, unknown>;
+}
+export interface Verification {
+    status: "passed" | "failed" | "not_run";
+    summary?: string;
+    checks?: {
+        name: string;
+        ok: boolean;
+    }[];
+}
+export declare class UnderwritError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export declare class Held extends Error {
+    decision: Decision | Record<string, unknown>;
+    reason: string;
+    /** What to tell the model: don't retry, tell the user it waits for approval. Safe to show it. */
+    guidance: {
+        act?: string;
+        decisionId?: string;
+        retry?: string;
+        instruction?: string;
+    };
+    constructor(decision: Decision | Record<string, unknown>, reason?: string);
+}
+export declare class Underwrit {
+    private url;
+    private token;
+    private fetchImpl;
+    private opts;
+    constructor(url: string, token: string, fetchImpl?: typeof fetch, opts?: {
+        retries?: number;
+        maxRetryWaitMs?: number;
+    });
+    /** 429 and 503 are retried, honouring Retry-After, up to `retries` (default 3) times. */
+    private call;
+    session(opts?: {
+        session?: string;
+        agent?: string;
+        environment?: string;
+        intent?: string;
+        actor?: string;
+        taskPolicy?: Record<string, unknown>;
+    }): Promise<Session>;
+    decide(session: string, tool: string, args?: Record<string, unknown>, extra?: DecideExtra): Promise<Decision>;
+    /** "Ask the gate": what this would get now, recording nothing. Against `session`, or a
+     *  hypothetical one (`environment`, `intent`, `taint`, `taskPolicy`); `policy` is a candidate. */
+    preview(tool: string, args?: Record<string, unknown>, on?: V1Inputs & {
+        session?: string;
+        environment?: string;
+        intent?: string;
+        taint?: string[];
+        taskPolicy?: Record<string, unknown>;
+        policy?: Record<string, unknown>;
+    }): Promise<Preview>;
+    /** The stages the gate asks, in order, and every code a decision can carry. */
+    gates(): Promise<Gates>;
+    /** A verification that lands after the outcome, inside the policy's post-check window. */
+    verify(decision: string, status: "passed" | "failed" | "inconclusive", opts?: {
+        checks?: {
+            name: string;
+            ok: boolean;
+        }[];
+        summary?: string;
+    }): Promise<Record<string, unknown>>;
+    verificationsDue(includeVerified?: boolean): Promise<{
+        checks: Record<string, unknown>[];
+    }>;
+    approvalLoad(days?: number): Promise<Record<string, unknown>>;
+    /** Propose an undo or repair for a decision whose outcome is uncertain, whose verification
+     *  failed, or whose target it holds. Always goes to a person; claim it with the same arguments
+     *  once approved. It does not clear the original's hold. */
+    compensate(decisionId: string, tool: string, args: Record<string, unknown>, reason: string, extra?: {
+        idempotencyKey?: string;
+        toolDefinitionDigest?: string;
+    }): Promise<Decision>;
+    scopeHolds(includeCleared?: boolean): Promise<{
+        holds: Record<string, unknown>[];
+        clearsBy: string[];
+    }>;
+    probeScopeHold(holdId: string, status: string, detail: string): Promise<Record<string, unknown>>;
+    /** The per-entry receipt: `pending` until a signed checkpoint covers the entry. */
+    receipt(seq: number): Promise<Receipt>;
+    claim(decisionId: string, args?: Record<string, unknown>, preconditions?: unknown): Promise<Claim>;
+    outcome(decision: string, status: string, detail?: string, verification?: Verification, reconcile?: boolean): Promise<{
+        seq: number;
+        hash: string;
+        taint: string[];
+    }>;
+    decision(id: string): Promise<Record<string, unknown>>;
+    /** Resolve when a held decision is answered (or expires), or after `timeoutMs`. Long-polls, at
+     *  most a minute per request. `lifecycle` on the result: `approved` → claim and run. */
+    wait(id: string, timeoutMs?: number): Promise<Record<string, unknown>>;
+    /** Hand a held decision to the plane and stop waiting: the plane calls `resumeUrl` when it is
+     *  answered (see `underwrit-client/durable`). */
+    park(decisionId: string, opts: {
+        kind: string;
+        key: string;
+        resumeUrl?: string;
+        state?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    parked(opts?: {
+        settled?: boolean;
+        kind?: string;
+    }): Promise<{
+        parked: Record<string, unknown>[];
+    }>;
+    ackParked(decisionId: string): Promise<Record<string, unknown>>;
+    close(session: string, status?: string): Promise<unknown>;
+    evidence(session: string): Promise<Record<string, unknown>>;
+}
+export declare class Session {
+    underwrit: Underwrit;
+    id: string;
+    constructor(underwrit: Underwrit, id: string);
+    call<R>(tool: string, fn: (args: Record<string, unknown>) => Promise<R> | R, args?: Record<string, unknown>, opts?: DecideExtra & {
+        verify?: (r: R) => Verification;
+    }): Promise<R>;
+    resume<R>(decisionId: string, fn: (args: Record<string, unknown>) => Promise<R> | R, args?: Record<string, unknown>, opts?: {
+        preconditions?: unknown;
+        verify?: (r: R) => Verification;
+    }): Promise<R>;
+    private run;
+    preview(tool: string, args?: Record<string, unknown>, v1?: V1Inputs): Promise<Preview>;
+    close(status?: string): Promise<unknown>;
+}

package/dist/index.js

@@ -0,0 +1,184 @@
+/** underwrit-client for TypeScript. fetch-based, no dependencies.
+ *
+ *  Mirrors the Python client: `call()` decides, runs, and records; it throws `Held` when the data
+ *  plane says `act: "hold"`. `resume()` claims an approval with the same arguments before running. */
+export class UnderwritError extends Error {
+    status;
+    constructor(status, message) {
+        super(`${status}: ${message}`);
+        this.status = status;
+    }
+}
+export class Held extends Error {
+    decision;
+    reason;
+    /** What to tell the model: don't retry, tell the user it waits for approval. Safe to show it. */
+    guidance;
+    constructor(decision, reason = "") {
+        super(reason || (decision.reasons?.[0] ?? "held for a person"));
+        this.decision = decision;
+        this.reason = reason;
+        const g = decision.agentGuidance;
+        this.guidance = g && typeof g === "object" ? g : {};
+    }
+}
+export class Underwrit {
+    url;
+    token;
+    fetchImpl;
+    opts;
+    constructor(url, token, fetchImpl = fetch, opts = {}) {
+        this.url = url;
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+        this.opts = opts;
+        this.url = url.replace(/\/+$/, "");
+    }
+    /** 429 and 503 are retried, honouring Retry-After, up to `retries` (default 3) times. */
+    async call(method, path, body) {
+        const retries = this.opts.retries ?? 3;
+        const cap = this.opts.maxRetryWaitMs ?? 30_000;
+        for (let attempt = 0;; attempt++) {
+            const r = await this.fetchImpl(`${this.url}${path}`, {
+                method,
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.token}` },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            if (r.ok)
+                return (await r.json());
+            let payload = {};
+            try {
+                payload = (await r.json());
+            }
+            catch { /* no body */ }
+            if ((r.status === 429 || r.status === 503) && attempt < retries) {
+                const header = Number(r.headers.get("Retry-After") ?? payload.retryAfterSeconds ?? 0);
+                const wait = Math.min(cap, (header > 0 ? header * 1000 : Math.min(2 ** (attempt + 1) * 1000, cap)));
+                await new Promise((res) => setTimeout(res, wait));
+                continue;
+            }
+            throw new UnderwritError(r.status, payload.error ?? r.statusText);
+        }
+    }
+    async session(opts = {}) {
+        const s = await this.call("POST", "/v1/sessions", opts);
+        return new Session(this, s.id);
+    }
+    decide(session, tool, args = {}, extra = {}) {
+        return this.call("POST", "/v1/decide", { session, tool, arguments: args, ...extra });
+    }
+    /** "Ask the gate": what this would get now, recording nothing. Against `session`, or a
+     *  hypothetical one (`environment`, `intent`, `taint`, `taskPolicy`); `policy` is a candidate. */
+    preview(tool, args = {}, on = {}) {
+        return this.call("POST", "/v1/preview", { tool, arguments: args, ...on });
+    }
+    /** The stages the gate asks, in order, and every code a decision can carry. */
+    gates() { return this.call("GET", "/v1/gates"); }
+    /** A verification that lands after the outcome, inside the policy's post-check window. */
+    verify(decision, status, opts = {}) {
+        return this.call("POST", "/v1/verify", { decision, status, ...opts });
+    }
+    verificationsDue(includeVerified = false) {
+        return this.call("GET", `/v1/verifications/due${includeVerified ? "?all=1" : ""}`);
+    }
+    approvalLoad(days = 7) { return this.call("GET", `/v1/approvals/load?days=${days}`); }
+    /** Propose an undo or repair for a decision whose outcome is uncertain, whose verification
+     *  failed, or whose target it holds. Always goes to a person; claim it with the same arguments
+     *  once approved. It does not clear the original's hold. */
+    compensate(decisionId, tool, args, reason, extra = {}) {
+        if (!reason.trim())
+            throw new Error("compensate() needs a reason; a person reads it before approving");
+        return this.call("POST", `/v1/decisions/${decisionId}/compensate`, { tool, arguments: args, reason, ...extra });
+    }
+    scopeHolds(includeCleared = false) {
+        return this.call("GET", `/v1/scope-holds${includeCleared ? "?all=1" : ""}`);
+    }
+    probeScopeHold(holdId, status, detail) {
+        return this.call("POST", `/v1/scope-holds/${holdId}/probe`, { status, detail });
+    }
+    /** The per-entry receipt: `pending` until a signed checkpoint covers the entry. */
+    receipt(seq) { return this.call("GET", `/v1/receipts/${seq}`); }
+    claim(decisionId, args, preconditions) {
+        const body = {};
+        if (args !== undefined)
+            body.arguments = args;
+        if (preconditions !== undefined)
+            body.preconditions = preconditions;
+        return this.call("POST", `/v1/decisions/${decisionId}/claim`, body);
+    }
+    outcome(decision, status, detail = "", verification, reconcile = false) {
+        return this.call("POST", "/v1/outcome", { decision, status, detail, ...(verification ? { verification } : {}), ...(reconcile ? { reconcile } : {}) });
+    }
+    decision(id) { return this.call("GET", `/v1/decisions/${id}`); }
+    /** Resolve when a held decision is answered (or expires), or after `timeoutMs`. Long-polls, at
+     *  most a minute per request. `lifecycle` on the result: `approved` → claim and run. */
+    async wait(id, timeoutMs = 300_000) {
+        const end = Date.now() + Math.max(0, timeoutMs);
+        for (;;) {
+            const step = Math.max(0, Math.min(60, Math.floor((end - Date.now()) / 1000)));
+            const d = await this.call("GET", `/v1/decisions/${id}${step ? `?wait=${step}` : ""}`);
+            if (d.lifecycle !== "held" || step <= 1)
+                return d;
+        }
+    }
+    /** Hand a held decision to the plane and stop waiting: the plane calls `resumeUrl` when it is
+     *  answered (see `underwrit-client/durable`). */
+    park(decisionId, opts) {
+        return this.call("POST", `/v1/decisions/${decisionId}/park`, { kind: opts.kind, key: opts.key, resumeUrl: opts.resumeUrl ?? "", state: opts.state ?? {} });
+    }
+    parked(opts = {}) {
+        const q = [...(opts.settled === undefined ? [] : [`settled=${opts.settled ? 1 : 0}`]), ...(opts.kind ? [`kind=${opts.kind}`] : [])];
+        return this.call("GET", `/v1/parked${q.length ? "?" + q.join("&") : ""}`);
+    }
+    ackParked(decisionId) { return this.call("POST", `/v1/parked/${decisionId}/ack`, {}); }
+    close(session, status = "succeeded") { return this.call("POST", `/v1/sessions/${session}/close`, { status }); }
+    evidence(session) { return this.call("GET", `/v1/evidence/${session}`); }
+}
+export class Session {
+    underwrit;
+    id;
+    constructor(underwrit, id) {
+        this.underwrit = underwrit;
+        this.id = id;
+    }
+    async call(tool, fn, args = {}, opts = {}) {
+        const { verify: _verify, ...extra } = opts;
+        const d = await this.underwrit.decide(this.id, tool, args, extra);
+        if (d.act === "hold")
+            throw new Held(d);
+        return this.run(d.id, fn, args, opts.verify);
+    }
+    async resume(decisionId, fn, args = {}, opts = {}) {
+        const c = await this.underwrit.claim(decisionId, args, opts.preconditions);
+        if (!c.ok && c.act === "hold")
+            throw new Held(c.decision, c.reason);
+        return this.run(decisionId, fn, args, opts.verify);
+    }
+    async run(decisionId, fn, args, verify) {
+        let result;
+        try {
+            result = await fn(args);
+        }
+        catch (e) {
+            const uncertain = e instanceof Error && /timeout|timed out/i.test(e.message);
+            await this.underwrit.outcome(decisionId, uncertain ? "uncertain" : "failed", String(e).slice(0, 2000));
+            throw e;
+        }
+        let verification;
+        if (verify) {
+            try {
+                verification = verify(result);
+            }
+            catch (e) {
+                verification = { status: "failed", summary: `verification threw ${String(e)}` };
+            }
+        }
+        const detail = typeof result === "string" ? result : JSON.stringify(result ?? null).slice(0, 2000);
+        await this.underwrit.outcome(decisionId, "succeeded", detail, verification);
+        return result;
+    }
+    preview(tool, args = {}, v1 = {}) {
+        return this.underwrit.preview(tool, args, { ...v1, session: this.id });
+    }
+    close(status = "succeeded") { return this.underwrit.close(this.id, status); }
+}

package/dist/vercel.d.ts

@@ -0,0 +1,22 @@
+/** Vercel AI SDK: a policy adapter shaped like `@ai-sdk/policy-opa`, backed by an Underwrit session.
+ *
+ *  const policy = underwritPolicy(session);
+ *  tool({ ..., needsApproval: policy.needsApproval("bank/send_money") })
+ *
+ *  `decide()` maps Underwrit's verdicts onto the four states the SDK's policy adapters use — allow,
+ *  deny, requires-approval, not-applicable — and `shadow` mirrors the SDK's shadow wrapper: every
+ *  decision is recorded, `onDecision` sees it, and nothing is blocked. */
+import type { Session, Decision } from "./index";
+export type PolicyState = "allow" | "deny" | "requires-approval" | "not-applicable";
+export declare function underwritPolicy(session: Session, opts?: {
+    shadow?: boolean;
+    onDecision?: (d: Decision, state: PolicyState) => void;
+}): {
+    decide(tool: string, args?: Record<string, unknown>): Promise<{
+        state: PolicyState;
+        decision: Decision;
+    }>;
+    needsApproval(tool: string): ({ input }: {
+        input: Record<string, unknown>;
+    }) => Promise<boolean>;
+};

package/dist/vercel.js

@@ -0,0 +1,19 @@
+export function underwritPolicy(session, opts = {}) {
+    const map = (d) => d.verdict === "deny" ? (d.act === "hold" ? "deny" : "allow")
+        : d.verdict === "require_human" ? (d.act === "hold" ? "requires-approval" : "allow")
+            : "allow";
+    return {
+        async decide(tool, args = {}) {
+            const d = await session.underwrit.decide(session.id, tool, args);
+            const state = opts.shadow ? "allow" : map(d);
+            opts.onDecision?.(d, state);
+            return { state, decision: d };
+        },
+        needsApproval(tool) {
+            return async ({ input }) => {
+                const { state } = await this.decide(tool, input);
+                return state === "requires-approval" || state === "deny";
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "underwrit-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vercel": {
+      "types": "./dist/vercel.d.ts",
+      "import": "./dist/vercel.js"
+    },
+    "./durable": {
+      "types": "./dist/durable.d.ts",
+      "import": "./dist/durable.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "approvals",
+    "audit",
+    "evidence",
+    "policy",
+    "prompt-injection"
+  ],
+  "homepage": "https://underwrit.io",
+  "bugs": {
+    "email": "admin@underwrit.io"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.7.2"
+  }
+}