@decidio/sdk 0.1.0

package/dist/resume.js

@@ -0,0 +1,301 @@
+// @decidio/sdk — durable async resume.
+//
+// The hard problem behind a "one-line" agent gate: a real human approval takes
+// minutes to days. Nobody watches a 60-second polling window. So a routed action
+// must SUSPEND (the requesting process may even exit) and RESUME later when the
+// approval arrives — and the AGENT must perform its own action on resume. Decidio
+// stays the approval layer above: it authorizes, records, and (on approval) SIGNALS
+// the agent. It never holds the agent's downstream credentials and never executes
+// the write itself. This is the same shape as HumanLayer's webhooks, Temporal
+// Signals, Inngest waitForEvent, and Decidio's own A2A `input-required` state.
+//
+// Two resume transports, same core:
+//   • webhookHandler() — production: Decidio POSTs a signed verdict to the agent's
+//     resume URL; the handler re-executes the agent's own fn and confirms.
+//   • worker()         — no inbound URL (laptop/CLI): a long-lived watcher polls
+//     /agent/status for each pending decision, then re-executes on approval.
+// Either way the args are replayed from an AGENT-SIDE store (Decidio holds none of
+// the downstream payload — only the authority decision), and execution is single-use
+// (the pending entry is deleted on completion, so a duplicate signal can't double-write).
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { signConfirm } from "./signing.js";
+export class MemoryPendingStore {
+    m = new Map();
+    claimed = new Set();
+    async put(p) { this.m.set(p.decisionId, p); }
+    async get(id) { return this.m.get(id) ?? null; }
+    async delete(id) { this.m.delete(id); this.claimed.delete(id); }
+    async list() { return [...this.m.values()].filter((p) => !this.claimed.has(p.decisionId)); }
+    async claim(id) { if (this.claimed.has(id) || !this.m.has(id))
+        return false; this.claimed.add(id); return true; }
+    async release(id) { this.claimed.delete(id); }
+}
+/** File-backed store so a COLD process (the original requester long gone) can still
+ *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
+ *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
+ *  sharing the dir can't both execute. (A stale `.claimed` from a crash mid-execute needs
+ *  TTL recovery — tracked in the backlog.) */
+export class FilePendingStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        mkdirSync(dir, { recursive: true });
+    }
+    key(id) { return id.replace(/[^\w.-]/g, "_"); }
+    path(id) { return join(this.dir, `${this.key(id)}.json`); }
+    claimedPath(id) { return join(this.dir, `${this.key(id)}.claimed`); }
+    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2)); }
+    async get(id) {
+        for (const f of [this.path(id), this.claimedPath(id)])
+            if (existsSync(f))
+                return JSON.parse(readFileSync(f, "utf8"));
+        return null;
+    }
+    async delete(id) { for (const f of [this.path(id), this.claimedPath(id)])
+        if (existsSync(f))
+            rmSync(f); }
+    async list() {
+        if (!existsSync(this.dir))
+            return [];
+        return readdirSync(this.dir).filter((f) => f.endsWith(".json")) // claimed (.claimed) excluded — in flight
+            .map((f) => JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+    }
+    async claim(id) {
+        try {
+            renameSync(this.path(id), this.claimedPath(id));
+            return true;
+        } // atomic; fails if already claimed/gone
+        catch {
+            return false;
+        }
+    }
+    async release(id) {
+        try {
+            renameSync(this.claimedPath(id), this.path(id));
+        }
+        catch { /* already released/gone */ }
+    }
+}
+/** Thrown by a `withApproval`-wrapped call when the action is routed and configured
+ *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
+ *  The caller can stop here — the process may even exit; the resume transport will
+ *  complete it later. */
+export class DecidioSuspendedError extends Error {
+    decisionId;
+    action;
+    constructor(decisionId, action) {
+        super(`Decidio suspended "${action}" for async approval (decision ${decisionId}). It will resume when a human approves.`);
+        this.decisionId = decisionId;
+        this.action = action;
+        this.name = "DecidioSuspendedError";
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function sign(secret, body) {
+    return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+}
+/** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
+ *  Exported so engine adapters (e.g. the Inngest bridge) reuse the exact check. */
+export function verifyResumeSignature(secret, body, header) {
+    if (!header)
+        return false;
+    const expected = sign(secret, body);
+    const a = Buffer.from(expected), b = Buffer.from(header);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+async function confirm(cfg, decisionId, capturedResponse) {
+    const f = cfg.fetchImpl ?? fetch;
+    // Sign the confirm so the DURABLE/resume path can earn application_confirmed too (bound to
+    // {action:"confirm", scope:decisionId}); without a key the server caps it at agent_asserted.
+    const requesterIdentity = signConfirm(decisionId, cfg);
+    await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
+        body: JSON.stringify({ decisionId, capturedResponse: capturedResponse ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
+    }).then((r) => { if (!r.ok)
+        throw new Error(`confirm ${r.status}`); });
+}
+async function statusOf(cfg, decisionId) {
+    const f = cfg.fetchImpl ?? fetch;
+    const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/status/" + encodeURIComponent(decisionId), {
+        headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
+    });
+    if (!r.ok)
+        throw new Error(`status ${r.status}`);
+    return r.json();
+}
+/**
+ * Build the resume controller. Spread it into your GuardConfig as `resume`, then
+ * either mount `webhookHandler()` (production) or run `worker()` (CLI/laptop).
+ *
+ *   const resume = createDecidioResume({ apiUrl, apiToken, store: new FilePendingStore(".decidio-pending"), resumeUrl });
+ *   const guard  = { apiUrl, agentId, apiToken, resume };
+ *   const createOpportunity = withApproval(createOpportunityRaw, describe, guard);
+ *   // production:  http.createServer(resume.webhookHandler()).listen(4100)
+ *   // or CLI:      resume.worker()
+ */
+export function createDecidioResume(opts) {
+    const registry = new Map();
+    const inFlight = new Set(); // concurrent-duplicate guard (same process)
+    const secret = opts.webhookSecret ?? opts.apiToken ?? "";
+    const ctrl = {
+        ...opts,
+        // Default the signing identity from env so a COLD resume process (a fresh worker that has
+        // the agent's env but wasn't passed config) still signs the confirm and earns the wrapper tier.
+        agentId: opts.agentId ?? process.env.DECIDIO_AGENT_ID,
+        agentKey: opts.agentKey ?? process.env.DECIDIO_AGENT_KEY,
+        agentDid: opts.agentDid ?? process.env.DECIDIO_AGENT_DID,
+        workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID, // D-B3.6: tenant-bind the cold-resume confirm proof
+        webhookSecret: secret,
+        store: opts.store,
+        register(action, fn) { registry.set(action, fn); },
+        async resolve({ decisionId, verdict, reason }) {
+            const finish = (o) => { if (o.status !== "unknown")
+                opts.onResolved?.(o); return o; };
+            const pending = await ctrl.store.get(decisionId);
+            if (!pending)
+                return { status: "unknown", decisionId }; // not ours / already resumed
+            if (verdict === "rejected") {
+                await ctrl.store.delete(decisionId);
+                return finish({ status: "rejected", decisionId, action: pending.action, reason });
+            }
+            if (verdict === "blocked") {
+                await ctrl.store.delete(decisionId);
+                return finish({ status: "blocked", decisionId, action: pending.action, reason });
+            }
+            // Fail CLOSED on any unexpected verdict — never execute on a garbage/unknown value.
+            if (verdict !== "approved" && verdict !== "auto_approved")
+                return { status: "unknown", decisionId };
+            const fn = registry.get(pending.action);
+            if (!fn)
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" — call resume.register(...) at startup` });
+            // Atomically CLAIM before executing — the cross-process single-use guarantee. If
+            // the store has no claim primitive, fall back to an in-process guard (same-process).
+            const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
+            if (!claimed)
+                return { status: "unknown", decisionId }; // another worker owns it
+            try {
+                // Approved: the AGENT performs its own action FIRST. On SUCCESS clear the parked
+                // entry (single-use) + confirm. If it throws, RELEASE the claim so the entry stays
+                // parked + retryable — an approved action is never lost.
+                const result = await fn(...pending.args);
+                await ctrl.store.delete(decisionId);
+                try {
+                    await confirm(ctrl, decisionId, result);
+                }
+                catch (e) {
+                    console.warn(`[decidio] resume confirm failed (action succeeded): ${e.message}`);
+                }
+                return finish({ status: "executed", decisionId, action: pending.action, result });
+            }
+            catch (e) {
+                if (ctrl.store.release)
+                    await ctrl.store.release(decisionId).catch(() => { });
+                throw e;
+            }
+            finally {
+                inFlight.delete(decisionId);
+            }
+        },
+        webhookHandler() {
+            return (req, res) => {
+                if (req.method !== "POST") {
+                    res.statusCode = 405;
+                    return res.end("method not allowed");
+                }
+                let raw = "";
+                req.on("data", (c) => (raw += c));
+                req.on("end", async () => {
+                    try {
+                        // Fail CLOSED when no secret is configured: an agent that forgot to set a
+                        // webhookSecret must NOT be drivable by forged callbacks. Opt out only with
+                        // allowUnsigned (trusted network boundary).
+                        if (!secret) {
+                            if (!opts.allowUnsigned) {
+                                res.statusCode = 401;
+                                return res.end(JSON.stringify({ error: "resume webhook unsigned and no secret configured (set webhookSecret or allowUnsigned)" }));
+                            }
+                        }
+                        else if (!verifyResumeSignature(secret, raw, req.headers["x-decidio-signature"])) {
+                            res.statusCode = 401;
+                            return res.end(JSON.stringify({ error: "bad signature" }));
+                        }
+                        const body = JSON.parse(raw || "{}");
+                        const verdict = body.verdict;
+                        const outcome = await ctrl.resolve({ decisionId: String(body.decisionId), verdict, reason: body.reason });
+                        res.statusCode = 200;
+                        res.setHeader("content-type", "application/json");
+                        res.end(JSON.stringify({ ok: true, outcome: { status: outcome.status, decisionId: outcome.decisionId } }));
+                    }
+                    catch (e) {
+                        res.statusCode = 500;
+                        res.end(JSON.stringify({ error: e?.message ?? "resume failed" }));
+                    }
+                });
+            };
+        },
+        fetchHandler() {
+            return async (req) => {
+                if (req.method !== "POST")
+                    return new Response("method not allowed", { status: 405 });
+                const raw = await req.text();
+                if (!secret) {
+                    if (!opts.allowUnsigned)
+                        return new Response(JSON.stringify({ error: "resume webhook unsigned and no secret configured (set webhookSecret or allowUnsigned)" }), { status: 401 });
+                }
+                else if (!verifyResumeSignature(secret, raw, req.headers.get("x-decidio-signature") ?? undefined)) {
+                    return new Response(JSON.stringify({ error: "bad signature" }), { status: 401 });
+                }
+                try {
+                    const body = JSON.parse(raw || "{}");
+                    const outcome = await ctrl.resolve({ decisionId: String(body.decisionId), verdict: body.verdict, reason: body.reason });
+                    return new Response(JSON.stringify({ ok: true, outcome: { status: outcome.status, decisionId: outcome.decisionId } }), { status: 200, headers: { "content-type": "application/json" } });
+                }
+                catch (e) {
+                    return new Response(JSON.stringify({ error: e?.message ?? "resume failed" }), { status: 500 });
+                }
+            };
+        },
+        worker(workerOpts) {
+            const interval = workerOpts?.intervalMs ?? 2_500;
+            const deadline = workerOpts?.timeoutMs ? Date.now() + workerOpts.timeoutMs : Infinity;
+            let stopped = false;
+            (async () => {
+                while (!stopped) {
+                    const pendings = await ctrl.store.list().catch(() => []);
+                    for (const p of pendings) {
+                        let st;
+                        try {
+                            st = await statusOf(ctrl, p.decisionId);
+                        }
+                        catch {
+                            continue;
+                        }
+                        const verdict = st.state === "approved" || st.state === "auto_approved" ? "approved" :
+                            st.state === "rejected" ? "rejected" :
+                                st.state === "blocked" ? "blocked" : null;
+                        if (!verdict)
+                            continue;
+                        // A throwing resolve (the agent's own fn failed) must NOT kill the watcher —
+                        // the entry stays parked and is retried on the next poll.
+                        try {
+                            const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                            workerOpts?.onResolved?.(outcome);
+                        }
+                        catch (e) {
+                            console.warn(`[decidio] resume failed for ${p.decisionId}, will retry: ${e.message}`);
+                        }
+                    }
+                    if (Date.now() > deadline)
+                        break;
+                    await sleep(interval);
+                }
+            })();
+            return { stop: () => { stopped = true; } };
+        },
+    };
+    return ctrl;
+}
+export { sign as _signResumeBody };

package/dist/signing.d.ts

@@ -0,0 +1,48 @@
+/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
+export declare function canonicalize(v: unknown): string;
+/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
+ *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
+ *  it never goes back to Decidio). */
+export declare function generateKeypair(): {
+    did: string;
+    privateKeyBase64: string;
+};
+export interface RequesterIdentity {
+    agentId: string;
+    did: string;
+    action: string;
+    amount: number;
+    scope?: string;
+    workspaceId?: string;
+    nonce: string;
+    exp: number;
+    proof: {
+        protected: string;
+        signature: string;
+    };
+}
+/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
+ *  prove the caller is the receipt's original requester before granting the wrapper tier
+ *  (application_confirmed). Returns undefined when no signing key is configured (the server
+ *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
+ *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
+ *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
+export declare function signConfirm(decisionId: string, cfg: {
+    agentId?: string;
+    agentKey?: string;
+    agentDid?: string;
+    workspaceId?: string;
+}): RequesterIdentity | undefined;
+/** Sign a request-bound identity proof. The returned object is sent verbatim as the
+ *  `requesterIdentity` field of /agent/authorize. */
+export declare function signBoundProof(privateKeyBase64: string, fields: {
+    agentId: string;
+    did: string;
+    action: string;
+    amount: number;
+    scope?: string;
+    workspaceId?: string;
+    ttlMs?: number;
+    now?: number;
+    nonce?: string;
+}): RequesterIdentity;

package/dist/signing.js

@@ -0,0 +1,83 @@
+// Client-side agent identity (§13 P0-8). The agent generates its Ed25519 keypair LOCALLY
+// (the private key never crosses the wire — `init` registers only the public did:key) and
+// signs a REQUEST-BOUND proof on each authorize: a detached Ed25519 JWS over
+// canonical({agentId,did,action,amount,scope,nonce,exp}). Decidio's floor verifies the
+// signature, binds it to the exact request, burns the single-use nonce, and checks the
+// did against the agent registry — so the gate PROVES who is calling instead of trusting a
+// label. This canonicalize + proof shape is byte-identical to apps/api (canonical.ts +
+// a2a/identity.ts), so a proof signed here verifies there.
+import { generateKeyPairSync, createPrivateKey, sign as edSign, randomUUID } from "node:crypto";
+// base58btc (Bitcoin alphabet) — for the did:key multibase 'z' prefix.
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function b58encode(buf) {
+    const digits = [0];
+    for (const byte of buf) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            carry += digits[i] << 8;
+            digits[i] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let str = "";
+    for (const b of buf) {
+        if (b === 0)
+            str += "1";
+        else
+            break;
+    }
+    for (let i = digits.length - 1; i >= 0; i--)
+        str += B58[digits[i]];
+    return str;
+}
+/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
+export function canonicalize(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalize).join(",")}]`;
+    const o = v;
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
+}
+/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
+ *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
+ *  it never goes back to Decidio). */
+export function generateKeypair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    const jwk = publicKey.export({ format: "jwk" });
+    const raw = Buffer.from(jwk.x, "base64url");
+    const did = "did:key:z" + b58encode(Buffer.concat([Buffer.from([0xed, 0x01]), raw]));
+    const privateKeyBase64 = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64");
+    return { did, privateKeyBase64 };
+}
+/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
+ *  prove the caller is the receipt's original requester before granting the wrapper tier
+ *  (application_confirmed). Returns undefined when no signing key is configured (the server
+ *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
+ *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
+ *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
+export function signConfirm(decisionId, cfg) {
+    if (!cfg.agentKey || !cfg.agentDid || !cfg.agentId)
+        return undefined;
+    return signBoundProof(cfg.agentKey, { agentId: cfg.agentId, did: cfg.agentDid, action: "confirm", amount: 0, scope: decisionId, workspaceId: cfg.workspaceId });
+}
+/** Sign a request-bound identity proof. The returned object is sent verbatim as the
+ *  `requesterIdentity` field of /agent/authorize. */
+export function signBoundProof(privateKeyBase64, fields) {
+    const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
+    const nonce = fields.nonce ?? randomUUID();
+    const exp = (fields.now ?? Date.now()) + (fields.ttlMs ?? 120_000);
+    // OMIT scope/workspaceId when absent so the canonical bytes match the server + the Python SDK — a key
+    // with an undefined value would serialize as literal "undefined", which Python can't reproduce, and a
+    // legacy (no-workspace) proof must stay byte-identical. The server's bound-payload reconstruction
+    // omits them the same way (a2a/identity.ts).
+    const payloadObj = { agentId: fields.agentId, did: fields.did, action: fields.action, amount: fields.amount, ...(fields.scope !== undefined ? { scope: fields.scope } : {}), ...(fields.workspaceId !== undefined ? { workspaceId: fields.workspaceId } : {}), nonce, exp };
+    const payload = Buffer.from(canonicalize(payloadObj), "utf8").toString("base64url");
+    const protectedHdr = Buffer.from(JSON.stringify({ alg: "EdDSA", kid: fields.did }), "utf8").toString("base64url");
+    const signature = Buffer.from(edSign(null, Buffer.from(`${protectedHdr}.${payload}`, "utf8"), key)).toString("base64url");
+    return { agentId: fields.agentId, did: fields.did, action: fields.action, amount: fields.amount, scope: fields.scope, workspaceId: fields.workspaceId, nonce, exp, proof: { protected: protectedHdr, signature } };
+}

package/openapi.yaml

@@ -0,0 +1,171 @@
+# The agent-gate wire contract @decidio/sdk speaks — the machine-readable companion to the
+# quickstart. Scope is deliberately the AGENT FLOOR only (what the floor-limited agent token can
+# reach) plus the outbound resume webhook Decidio sends; workspace administration (register,
+# token mint, approvals) is a human/session surface and stays out of this file.
+openapi: 3.1.0
+info:
+  title: Decidio Agent Gate
+  version: 0.1.0
+  description: >
+    Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
+    receive the signed resume webhook when a routed action is decided. Every outcome seals a
+    verifiable Authority Receipt — verify offline with @decidio/verify (npm) or
+    `python -m decidio.verify` (pip install decidio).
+  license:
+    name: Apache-2.0
+servers:
+  - url: https://decidio-api.onrender.com
+    description: Hosted sandbox (synthetic tester lab)
+  - url: http://localhost:4000
+    description: Local development
+security:
+  - agentToken: []
+components:
+  securitySchemes:
+    agentToken:
+      type: http
+      scheme: bearer
+      description: >
+        The FLOOR-LIMITED agent token minted by `npx @decidio/sdk init` (or Connect → Agents).
+        It authenticates only these /agent/* paths and /a2a — every other API path refuses it.
+  schemas:
+    RequesterIdentity:
+      type: object
+      description: >
+        Request-bound Ed25519 identity proof (detached JWS over the RFC 8785-canonicalized
+        payload; 120s TTL, single-use nonce). Registered agents must sign to be eligible for
+        policy auto-approve; unsigned requests still work but always route to a human.
+      required: [agentId, did, action, amount, nonce, exp, proof]
+      properties:
+        agentId: { type: string }
+        did: { type: string, description: "did:key of the agent's LOCALLY generated keypair" }
+        action: { type: string }
+        amount: { type: number }
+        scope: { type: string }
+        workspaceId: { type: string }
+        nonce: { type: string }
+        exp: { type: integer, description: unix ms expiry }
+        proof:
+          type: object
+          required: [protected, signature]
+          properties:
+            protected: { type: string, description: base64url JWS protected header (EdDSA, kid=did) }
+            signature: { type: string, description: base64url detached signature }
+    AuthorizeRequest:
+      type: object
+      required: [requester, action, amount]
+      properties:
+        requester: { type: string, description: the registered agentId }
+        action: { type: string }
+        amount: { type: number }
+        scope: { type: string }
+        sourceSystem: { type: string }
+        context: { type: object, additionalProperties: true }
+        requesterIdentity: { $ref: "#/components/schemas/RequesterIdentity" }
+        resumeUrl:
+          type: string
+          format: uri
+          description: where Decidio POSTs the signed verdict when a routed decision resolves
+    AuthorizeResponse:
+      type: object
+      required: [decision, decisionId, receiptId]
+      properties:
+        decision:
+          type: string
+          enum: [proceed, route, block]
+          description: >
+            Treat any OTHER value as block — the SDKs allow-list these three so an older client
+            fails closed against a newer server.
+        decisionId: { type: string }
+        receiptId: { type: string }
+        reason: { type: string }
+    StatusResponse:
+      type: object
+      required: [state]
+      properties:
+        state:
+          type: string
+          enum: [pending, approved, auto_approved, rejected, blocked]
+        reason: { type: string }
+    ConfirmRequest:
+      type: object
+      required: [decisionId, capturedResponse, source]
+      properties:
+        decisionId: { type: string }
+        capturedResponse:
+          description: the REAL downstream response the wrapper captured (server minimizes + tokenizes before sealing)
+        source:
+          type: string
+          enum: [wrapper, agent]
+          description: wrapper = SDK-captured (eligible for application_confirmed); agent = self-report (capped at agent_asserted)
+        requesterIdentity:
+          $ref: "#/components/schemas/RequesterIdentity"
+          description: confirm proof is bound to {action:"confirm", scope:decisionId}
+    ResumeWebhook:
+      type: object
+      description: >
+        OUTBOUND — Decidio → your resumeUrl when a routed decision is decided. The raw body is
+        HMAC-signed; verify `x-decidio-signature: sha256=<hex>` with your DECIDIO_WEBHOOK_SECRET
+        BEFORE acting (the SDK resume controllers fail closed). Re-execution is single-use.
+      required: [decisionId, verdict]
+      properties:
+        decisionId: { type: string }
+        verdict: { type: string, enum: [approved, rejected] }
+      # NOTE — deliberately NO `reason` field: the human's justification is never delivered to an
+      # agent-controlled URL (that would egress cleartext rationale). Agents read the tokenized
+      # reason via GET /agent/status/{decisionId} instead. Do not "fix" the server to match a
+      # richer webhook shape.
+paths:
+  /agent/authorize:
+    post:
+      summary: Ask the gate to authorize one agent action
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/AuthorizeRequest" }
+      responses:
+        "200":
+          description: verdict
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AuthorizeResponse" }
+        "401": { description: missing/invalid agent token }
+  /agent/status/{decisionId}:
+    get:
+      summary: Poll a routed decision (blocking mode / durable worker)
+      parameters:
+        - name: decisionId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: current state
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/StatusResponse" }
+        "401": { description: missing/invalid agent token }
+        "404": { description: unknown decision }
+  /agent/confirm:
+    post:
+      summary: Report the captured execution outcome (seals the receipt's evidence tier)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ConfirmRequest" }
+      responses:
+        "200": { description: recorded }
+        "401": { description: missing/invalid agent token }
+  x-webhooks:
+    resume:
+      post:
+        summary: Signed verdict delivery (Decidio → agent resumeUrl)
+        requestBody:
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ResumeWebhook" }
+        responses:
+          "200": { description: agent accepted and (single-use) re-executed }
+          "401": { description: signature missing/invalid — the controller fails closed }