@decidio/sdk 0.1.0

package/dist/cli.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// @decidio/sdk CLI — the on-ramp. Run via `npx @decidio/sdk <cmd>` (or tsx in-repo).
+//   init [agentId]   sign in, register the agent, mint its API token, write .env
+//   doctor           check config + connectivity + durability readiness
+//   approvals        list pending agent approvals; `approvals approve|reject <id> [reason]`
+//   dev [--target U] signal-only relay: forwards Decidio's webhook to your local agent URL
+//
+// TWO TOKEN KINDS, deliberately (self-serve design 2026-08-28): commands that ADMINISTER a
+// workspace (init's register+mint, approvals) need the owner's SESSION token — acquired
+// interactively per run or from DECIDIO_SESSION_TOKEN, held in memory, NEVER written to disk.
+// What lands in .env as DECIDIO_API_TOKEN is the floor-limited AGENT token the runtime SDK
+// needs (it can call /agent/* and nothing else). A session-capable secret must never live in
+// an agent host's .env — that was the pre-publish design's hole.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { createInterface } from "node:readline";
+import { generateKeypair } from "./signing.js";
+const API = (process.env.DECIDIO_API_URL ?? "http://localhost:4000").replace(/\/$/, "");
+const TOKEN = process.env.DECIDIO_API_TOKEN;
+const ENV_PATH = ".env";
+const log = (...a) => console.log(...a);
+async function api(path, init = {}, bearer) {
+    const auth = bearer ?? TOKEN;
+    const res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = text;
+    }
+    return { status: res.status, body };
+}
+function readEnv() {
+    const out = {};
+    if (existsSync(ENV_PATH))
+        for (const line of readFileSync(ENV_PATH, "utf8").split(/\r?\n/)) {
+            const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
+            if (m)
+                out[m[1]] = m[2];
+        }
+    return out;
+}
+function upsertEnv(updates) {
+    const cur = readEnv();
+    const merged = { ...cur, ...updates };
+    const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
+    writeFileSync(ENV_PATH, body);
+}
+// ---- interactive input (session sign-in) ---------------------------------------------------
+function ask(question, mute = false) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        if (mute) {
+            // Hide password echo: after the prompt renders, swallow subsequent output writes.
+            const anyRl = rl;
+            const write = anyRl._writeToOutput?.bind(rl);
+            anyRl._writeToOutput = (s) => { if (s.includes(question))
+                write?.(s); };
+        }
+        rl.question(question, (answer) => { rl.close(); if (mute)
+            process.stdout.write("\n"); resolve(answer.trim()); });
+    });
+}
+/** Owner SESSION token, memory-only. Sources in order: DECIDIO_SESSION_TOKEN env, interactive
+ *  email+password (`/demo/login`), pasted sign-in link (`/demo/login-consume` — for the
+ *  password-less accounts the welcome flow creates). Never persisted. */
+async function acquireSession() {
+    if (process.env.DECIDIO_SESSION_TOKEN)
+        return process.env.DECIDIO_SESSION_TOKEN;
+    // Same rule the server applies to resume URLs: credentials never ride plaintext http to a
+    // non-loopback host. Refuse before prompting, not after collecting a password.
+    if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
+        log(`✘ refusing to send sign-in credentials over plaintext http to ${API} — use https (or localhost for local dev).`);
+        return null;
+    }
+    if (!process.stdin.isTTY) {
+        log("✘ a Decidio sign-in is needed and this terminal is non-interactive.");
+        log("  Set DECIDIO_SESSION_TOKEN (grab a sign-in link from your workspace email; its ?login= value is the token).");
+        return null;
+    }
+    log(`Sign in to your Decidio workspace (${API}). Press Enter at the password prompt to use an emailed sign-in link instead.`);
+    const email = await ask("  email: ");
+    if (email) {
+        const password = await ask("  password (Enter to skip): ", true);
+        if (password) {
+            const r = await api("/demo/login", { method: "POST", body: JSON.stringify({ email, password }) }, "");
+            if (r.status >= 200 && r.status < 300 && r.body?.token)
+                return r.body.token;
+            log(`  ✘ sign-in failed (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}. Trying the link path…`);
+        }
+    }
+    log("  Request a sign-in link from the app's sign-in screen (or use your welcome email), then paste the LINK or its token here.");
+    const pasted = await ask("  link or token: ");
+    if (!pasted)
+        return null;
+    const m = pasted.match(/[?&]login=([^&\s]+)/);
+    const linkToken = m ? decodeURIComponent(m[1]) : pasted;
+    const r = await api("/demo/login-consume", { method: "POST", body: JSON.stringify({ token: linkToken }) }, "");
+    if (r.status >= 200 && r.status < 300 && r.body?.token)
+        return r.body.token;
+    log(`  ✘ link sign-in failed (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}`);
+    return null;
+}
+async function cmdInit(agentId) {
+    log(`Registering agent "${agentId}" with Decidio at ${API}…`);
+    // CLIENT-SIDE KEYGEN: generate the Ed25519 keypair LOCALLY and register only the PUBLIC
+    // did:key. The private key NEVER crosses the wire — it goes straight to this host's env.
+    const existingKey = readEnv().DECIDIO_AGENT_KEY;
+    const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || readEnv().DECIDIO_SOURCE_SYSTEM;
+    const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
+    const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
+    // First try whatever bearer the env already carries (the local-dev / operator path — a static
+    // admin token, or dev-open auth). On 401/403 fall through to the self-serve session flow.
+    let session = null;
+    let r = await api("/api/agents/register", { method: "POST", body: registerBody });
+    if (r.status === 401 || r.status === 403) {
+        session = await acquireSession();
+        if (!session) {
+            log("✘ unauthorized — sign in (or set DECIDIO_SESSION_TOKEN / DECIDIO_API_TOKEN) and retry.");
+            return 1;
+        }
+        r = await api("/api/agents/register", { method: "POST", body: registerBody }, session);
+    }
+    let did, privateKey;
+    if (r.status === 409) {
+        // Already registered to a different (server-held) did. Reuse it; the local key we just
+        // minted does NOT match, so don't write it — the operator must supply the existing key.
+        log(`• agent already registered (did ${r.body?.did}); reusing it.`);
+        did = r.body?.did;
+        if (!existingKey)
+            log("⚠ this agent was registered earlier — set its existing DECIDIO_AGENT_KEY to sign (auto-approve needs a proof).");
+    }
+    else if (r.status >= 200 && r.status < 300) {
+        did = r.body?.did;
+        privateKey = localKey;
+        log(`✔ registered (did ${did}) — key generated locally, public did only sent to Decidio`);
+    }
+    else {
+        log(`✘ register failed (${r.status}): ${JSON.stringify(r.body)}`);
+        return 1;
+    }
+    // Mint the runtime credential: the floor-limited AGENT token (can call /agent/* only). This is
+    // what .env gets — the session token stays in memory and dies with this process. On boxes
+    // without the tester-lab fence (plain local dev) the mint endpoint refuses; that's fine —
+    // local dev auths with its existing env and we say so instead of failing the init.
+    let agentToken, workspaceId;
+    const mintBearer = session ?? TOKEN;
+    if (mintBearer) {
+        const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "sdk-cli" }) }, mintBearer);
+        if (mint.status >= 200 && mint.status < 300 && mint.body?.token) {
+            agentToken = mint.body.token;
+            workspaceId = mint.body.workspaceId;
+            log(`✔ minted the agent API token (shown once server-side; expires ${mint.body.expiresAt ?? "per policy"})`);
+        }
+        else if (session) {
+            log(`✘ could not mint the agent token (${mint.status}): ${JSON.stringify(mint.body)} — the SDK has no runtime credential; fix and re-run init.`);
+            return 1;
+        }
+        else {
+            log(`• no agent token minted (${mint.status}) — assuming local/operator auth via the existing DECIDIO_API_TOKEN.`);
+        }
+    }
+    const secret = readEnv().DECIDIO_WEBHOOK_SECRET || randomBytes(32).toString("hex");
+    const envOut = { DECIDIO_API_URL: API, DECIDIO_AGENT_ID: agentId, DECIDIO_WEBHOOK_SECRET: secret };
+    if (sourceSystem)
+        envOut.DECIDIO_SOURCE_SYSTEM = sourceSystem;
+    if (did)
+        envOut.DECIDIO_AGENT_DID = did;
+    if (privateKey)
+        envOut.DECIDIO_AGENT_KEY = privateKey; // written locally; never left this host
+    if (agentToken)
+        envOut.DECIDIO_API_TOKEN = agentToken; // the FLOOR-LIMITED token — never the session
+    if (workspaceId)
+        envOut.DECIDIO_WORKSPACE_ID = workspaceId;
+    upsertEnv(envOut);
+    log(`✔ wrote ${ENV_PATH} (DECIDIO_API_URL, DECIDIO_AGENT_ID, DECIDIO_WEBHOOK_SECRET${did ? ", DECIDIO_AGENT_DID" : ""}${privateKey ? ", DECIDIO_AGENT_KEY" : ""}${agentToken ? ", DECIDIO_API_TOKEN [agent-scope], DECIDIO_WORKSPACE_ID" : ""})`);
+    if (privateKey)
+        log(`\n✔ signing key stored locally as DECIDIO_AGENT_KEY in ${ENV_PATH} (keep that file out of git; move it to your secret manager for production).\n`);
+    log("Add one line to your agent:");
+    log(`   import { guard } from "@decidio/sdk";`);
+    log(`   const createOpp = guard.protect(createOppRaw, o => ({ action: "createOpportunity", amount: o.Amount, scope: "Opportunity" }));`);
+    log("Mount the resume route (durable async approval):");
+    log(`   // Express:   app.post("/decidio/resume", guard.resumeHandler())`);
+    log(`   // Next.js:   export const POST = (req) => guard.resumeFetchHandler()(req)`);
+    log("");
+    return cmdDoctor();
+}
+async function cmdDoctor() {
+    const env = readEnv();
+    let ok = true;
+    const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
+    line(!!(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL), `API URL: ${API}`);
+    line(!!(process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID), `agent id: ${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || "(unset)"}`);
+    const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
+    line(!!secret, secret ? "webhook secret: set (durable resume will fail-closed verify)" : "webhook secret: MISSING — resume webhook will fail closed");
+    // Signing key — REQUIRED for auto-approve. Without it the SDK can't prove identity, so the
+    // gate routes EVERY request to a human (safe, but surprising). Surface it loudly.
+    const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
+    if (signing)
+        log("✔ signing key: set — agent proves identity, so policy auto-approve is in effect");
+    else
+        log("⚠ signing key: MISSING (DECIDIO_AGENT_KEY/DID) — without it the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
+    // Reachability and token role are SEPARATE checks (the old probe called any <500 green, so a
+    // wrong-kind token looked healthy). /api/health is unauthenticated truth about reachability;
+    // /api/records then classifies the token: 2xx = session/admin scope, 401 = agent-floor scope
+    // (correct for the runtime; init/approvals need a sign-in).
+    try {
+        const h = await api("/api/health", {}, "");
+        line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
+        const rec = await api("/api/records");
+        if (rec.status >= 200 && rec.status < 300)
+            log("✔ token scope: session/admin (init + approvals will work from this env)");
+        else if (rec.status === 401)
+            log("✔ token scope: agent floor — correct for the runtime SDK (approvals/init will prompt for a sign-in)");
+        else
+            log(`⚠ token scope: unexpected ${rec.status} from /api/records`);
+    }
+    catch (e) {
+        line(false, `connectivity: cannot reach ${API} — ${e?.message}`);
+    }
+    log(ok ? "\ndoctor: all green — durable resume ready." : "\ndoctor: fix the ✘ items above.");
+    return ok ? 0 : 1;
+}
+async function cmdApprovals(sub, id, reason) {
+    // Approvals are a HUMAN act on the workspace — session scope, never the agent token. If the
+    // env's token is agent-floor (401 on /api/*), sign in interactively; memory-only as always.
+    let bearer;
+    const probe = await api("/api/decisions/cards");
+    if (probe.status === 401 || probe.status === 403) {
+        const session = await acquireSession();
+        if (!session) {
+            log("✘ approvals need a workspace sign-in.");
+            return 1;
+        }
+        bearer = session;
+    }
+    if (sub === "approve" || sub === "reject") {
+        if (!id) {
+            log(`usage: approvals ${sub} <decisionId> [reason]`);
+            return 2;
+        }
+        const r = await api(`/api/decisions/${encodeURIComponent(id)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
+        if (r.status >= 200 && r.status < 300) {
+            log(`✔ ${sub}d ${id}${r.body?.resumeSignal ? ` — agent signalled (${r.body.resumeSignal.ok ? "ok" : r.body.resumeSignal.error})` : ""}`);
+            return 0;
+        }
+        log(`✘ ${sub} failed (${r.status}): ${JSON.stringify(r.body)}`);
+        return 1;
+    }
+    const r = bearer ? await api("/api/decisions/cards", {}, bearer) : probe;
+    const cards = r.body?.cards ?? [];
+    const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
+    if (!pending.length) {
+        log("No pending agent approvals.");
+        return 0;
+    }
+    log(`Pending agent approvals (${pending.length}):`);
+    for (const c of pending) {
+        const ar = c.agentRequest ?? {};
+        log(`  ${c.id}  ${ar.action ?? "?"}${ar.amount != null ? `  $${Number(ar.amount).toLocaleString()}` : ""}  — ${c.title ?? ""}`);
+    }
+    log(`\nApprove:  decidio approvals approve <id> [reason]   ·   Reject:  decidio approvals reject <id> [reason]`);
+    return 0;
+}
+function cmdDev(target, port) {
+    // Signal-only relay: receive Decidio's webhook here (a stable URL) and forward it to
+    // your local agent's resume listener. Useful when the agent isn't directly reachable.
+    log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
+    createServer((req, res) => {
+        if (req.method !== "POST") {
+            res.statusCode = 405;
+            return res.end();
+        }
+        let raw = "";
+        req.on("data", (c) => (raw += c));
+        req.on("end", async () => {
+            try {
+                const fwd = await fetch(target, { method: "POST", headers: { "content-type": "application/json", ...(req.headers["x-decidio-signature"] ? { "x-decidio-signature": String(req.headers["x-decidio-signature"]) } : {}) }, body: raw });
+                const body = JSON.parse(raw || "{}");
+                log(`→ relayed decision ${body.decisionId} (${body.verdict}) → ${fwd.status}`);
+                res.statusCode = fwd.status;
+                res.end(await fwd.text());
+            }
+            catch (e) {
+                res.statusCode = 502;
+                res.end(JSON.stringify({ error: e?.message }));
+            }
+        });
+    }).listen(port);
+    return 0;
+}
+async function main(argv) {
+    const [cmd, a, b, ...rest] = argv.slice(2);
+    switch (cmd) {
+        case "init": return cmdInit(a ?? process.env.DECIDIO_AGENT_ID ?? "salesops-agent");
+        case "doctor": return cmdDoctor();
+        case "approvals": return cmdApprovals(a, b, rest.join(" ") || undefined);
+        case "dev": {
+            const args = argv.slice(3);
+            const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+            const target = flag("--target") || process.env.DECIDIO_AGENT_RESUME_URL || "http://localhost:4100/decidio/resume";
+            const port = Number(flag("--port") || process.env.DECIDIO_DEV_PORT || 4099);
+            return cmdDev(target, port);
+        }
+        default:
+            log("decidio <init|doctor|approvals|dev>\n  init [agentId] · doctor · approvals [approve|reject <id> [reason]] · dev [--target URL] [--port N]");
+            return cmd ? 1 : 0;
+    }
+}
+main(process.argv).then((code) => { if (code !== 0)
+    process.exitCode = code; }).catch((e) => { console.error(e); process.exit(1); });

package/dist/guard.d.ts

@@ -0,0 +1,52 @@
+import { type ApprovalContext } from "./index.js";
+import { type ResumeController, type ResumeOutcome } from "./resume.js";
+export interface GuardFacadeConfig {
+    apiUrl: string;
+    agentId: string;
+    apiToken?: string;
+    sourceSystem?: string;
+    resumeUrl?: string;
+    webhookSecret?: string;
+    pendingDir?: string;
+    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
+     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
+    agentKey?: string;
+    agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
+     *  so a captured proof can't be replayed in another tenant. */
+    workspaceId?: string;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
+    appUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ProtectOptions {
+    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest/mcp)
+     *  live in @decidio/sdk/adapters and take the engine handle. */
+    adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
+    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
+    mode?: "durable" | "blocking";
+}
+export declare class Guard {
+    config: GuardFacadeConfig;
+    resume?: ResumeController;
+    constructor(config: GuardFacadeConfig, resume?: ResumeController);
+    static fromEnv(): Guard;
+    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
+    resumeHandler(): import("http").RequestListener;
+    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
+    resumeFetchHandler(): (req: Request) => Promise<Response>;
+    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
+     *  any parked approval — so a suspended action survives a process restart. One line at startup.
+     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
+    worker(opts?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onResolved?: (o: ResumeOutcome) => void;
+    }): {
+        stop: () => void;
+    };
+    private ensureResume;
+    protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
+}
+/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
+export declare const guard: Guard;

package/dist/guard.js

@@ -0,0 +1,76 @@
+// The Guard facade — `guard.protect(fn, describe)`, the one agnostic line (TS mirror
+// of decidio-guard Python). A thin layer over the verified primitives: durable mode
+// builds a resume controller and suspends; blocking mode polls (opt-in, loud). The
+// agent executes its own action; Decidio gates + records + signals — never executes.
+import { withApproval } from "./index.js";
+import { createDecidioResume, FilePendingStore } from "./resume.js";
+export class Guard {
+    config;
+    resume;
+    constructor(config, resume) {
+        this.config = config;
+        this.resume = resume;
+    }
+    static fromEnv() {
+        return new Guard({
+            apiUrl: process.env.DECIDIO_API_URL ?? "http://localhost:4000",
+            agentId: process.env.DECIDIO_AGENT_ID ?? "agent",
+            apiToken: process.env.DECIDIO_API_TOKEN,
+            sourceSystem: process.env.DECIDIO_SOURCE_SYSTEM,
+            resumeUrl: process.env.DECIDIO_RESUME_URL,
+            webhookSecret: process.env.DECIDIO_WEBHOOK_SECRET,
+            pendingDir: process.env.DECIDIO_PENDING_DIR,
+            agentKey: process.env.DECIDIO_AGENT_KEY,
+            agentDid: process.env.DECIDIO_AGENT_DID,
+            workspaceId: process.env.DECIDIO_WORKSPACE_ID,
+            appUrl: process.env.DECIDIO_APP_URL,
+        });
+    }
+    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
+    resumeHandler() { return this.ensureResume().webhookHandler(); }
+    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
+    resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
+    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
+     *  any parked approval — so a suspended action survives a process restart. One line at startup.
+     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
+    worker(opts) {
+        return this.ensureResume().worker(opts);
+    }
+    ensureResume() {
+        if (!this.resume) {
+            const c = this.config;
+            this.resume = createDecidioResume({
+                apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
+                resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
+                // Carry the signing identity so the durable/cold confirm on resume is signed too (incl. the
+                // workspace binding — D-B3.6 — so a cold-resume confirm proof is tenant-scoped as well).
+                agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
+                fetchImpl: c.fetchImpl,
+            });
+        }
+        return this.resume;
+    }
+    protect(fn, describe, opts) {
+        if (opts?.adapter && opts.adapter !== "generic") {
+            // Engine adapters are bound explicitly via @decidio/sdk/adapters (they need the
+            // engine handle at call time). Surfaced as a clear error until wired in this build.
+            throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via @decidio/sdk/adapters/${opts.adapter} (it needs the engine handle).`);
+        }
+        const c = this.config;
+        const base = {
+            apiUrl: c.apiUrl, agentId: c.agentId, apiToken: c.apiToken,
+            sourceSystem: c.sourceSystem, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId, appUrl: c.appUrl, fetchImpl: c.fetchImpl,
+        };
+        if ((opts?.mode ?? "durable") === "blocking") {
+            console.warn("[decidio] WARNING: blocking wait — only safe for short, watched approvals. " +
+                "Omit mode:\"blocking\" for durable async resume on real (minutes-to-days) approvals.");
+            // No resumeUrl on the blocking path — the server must not fire a webhook to an
+            // endpoint a blocking agent isn't serving; the poll is the only resume channel.
+            return withApproval(fn, describe, base);
+        }
+        // durable: refuse-don't-downgrade — always wire a resume transport, never silently block.
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume: this.ensureResume() });
+    }
+}
+/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
+export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import type { ResumeController } from "./resume.js";
+export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume } from "./resume.js";
+export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
+export { guard, Guard } from "./guard.js";
+export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
+export { generateKeypair, signBoundProof, signConfirm, canonicalize } from "./signing.js";
+export type { RequesterIdentity } from "./signing.js";
+export interface GuardConfig {
+    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
+    apiUrl: string;
+    /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
+    agentId: string;
+    /** Bearer token for the REST floor (a trusted, already-authenticated internal
+     *  caller). Lives ONLY in the agent host's environment — never in client code. */
+    apiToken?: string;
+    /** Source system label sealed onto the receipt (e.g. "salesforce"). */
+    sourceSystem?: string;
+    /** The agent's PRIVATE signing key (PKCS8 base64), generated locally by `init` and held
+     *  ONLY in the agent host's env as DECIDIO_AGENT_KEY. When set (with `agentDid`), the SDK
+     *  signs a request-bound identity proof on each authorize so the floor PROVES the requester
+     *  instead of trusting the label — required for a registered agent to auto-approve. */
+    agentKey?: string;
+    /** The agent's PUBLIC did:key (the one registered with Decidio). Pairs with `agentKey`. */
+    agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID, from the owner's agent-token mint).
+     *  Bound into the signed proof (D-B3.6) so a captured proof can't be replayed in another tenant.
+     *  For a tester's per-workspace agent token this is the tester's workspace id. */
+    workspaceId?: string;
+    /** Poll cadence + ceiling while a routed action awaits human approval. Used ONLY
+     *  by the blocking transport (no `resume` configured). */
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    /** Optional async notifier so a long human wait surfaces in your logs/UI. */
+    onPending?: (info: {
+        decisionId: string;
+        receiptId: string;
+        url: string | null;
+    }) => void;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL). When set, a routed action can say WHERE to
+     *  approve it — `<appUrl>/d/<decisionId>` opens that decision directly, on web or on the phone
+     *  build. This link used to be built only inside our own example, so a developer who pasted the
+     *  env block set DECIDIO_APP_URL and nothing ever read it. */
+    appUrl?: string;
+    /** Durable async resume. When set, a routed action SUSPENDS (parks its args in the
+     *  store, throws DecidioSuspendedError) instead of blocking — the process may exit
+     *  and resume later via the controller's webhook handler or poll worker. This is
+     *  the production transport for real (minutes-to-days) human approvals. */
+    resume?: ResumeController;
+    /** Callback URL Decidio POSTs the verdict to on approval (webhook transport).
+     *  Sent on /agent/authorize so the decision carries it. Falls back to
+     *  resume.resumeUrl. Omit when using the poll worker. */
+    resumeUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ApprovalContext {
+    action: string;
+    amount: number;
+    scope?: string;
+    /** Optional human-facing DETAILS of the action (e.g. { Account, "Lead Source", Stage }) shown to
+     *  the approver as "what you're approving". Display-only — the policy decides on `amount`/`scope`,
+     *  never these. Residual-safe tokenized server-side before persistence. */
+    context?: Record<string, string | number>;
+}
+export declare class DecidioBlockedError extends Error {
+    reason: string;
+    decisionId: string;
+    constructor(reason: string, decisionId: string);
+}
+export declare class DecidioRejectedError extends Error {
+    reason: string;
+    decisionId: string;
+    constructor(reason: string, decisionId: string);
+}
+export declare class DecidioTimeoutError extends Error {
+    decisionId: string;
+    constructor(decisionId: string);
+}
+/**
+ * Wrap an async action behind the Decidio gate. `describe` extracts the approval
+ * context (action, amount, scope) from the call arguments. Returns a function with
+ * the SAME signature as `fn` — drop-in.
+ */
+/** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
+ *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
+export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
+export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig): (...args: A) => Promise<R>;