@decidio/sdk 0.1.2 → 0.1.4

package/README.md

@@ -2,12 +2,33 @@
 
 One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every outcome.
 
+## The two-minute tour
+
+```bash
+npx @decidio/sdk quickstart
+```
+
+One command, guided: it registers a fresh agent (key generated locally), gates a demo action
+with the same one line you'll use on your real function, routes it to a human — **you** — lets
+you approve right there (or from your Decidio app), executes on approval, then downloads the
+sealed Authority Receipt and verifies it offline in front of you. Sign in when prompted, or
+export `DECIDIO_SESSION_TOKEN` for headless terminals. No config: with no `DECIDIO_API_URL` set
+it targets the hosted synthetic sandbox.
+
 ## Quickstart — seven steps to your first sealed receipt
 
 Under 30 minutes, no help needed. You'll need Node 20.6+, a terminal, and a Decidio workspace
 (request one at [decidioai.com](https://decidioai.com/#early-access) — the hosted sandbox is
-synthetic data, safe to experiment in). Shell commands below are Bash; on PowerShell, `export
-NAME=value` becomes `$env:NAME="value"`.
+synthetic data, safe to experiment in).
+
+**PowerShell users** — the equivalents for every Bash idiom used below:
+
+```powershell
+mkdir decidio-quickstart; cd decidio-quickstart          # instead of mkdir ... && cd ...
+$env:DECIDIO_API_URL = "https://decidio-api.onrender.com" # instead of export NAME=value
+$env:DECIDIO_SOURCE_SYSTEM = "salesforce"; npx @decidio/sdk init my-sf-agent
+                                                          # instead of VAR=value npx ... (inline env)
+```
 
 **1. Install**
 
@@ -29,6 +50,17 @@ is sent), registers the agent, mints its **floor-limited API token** (it can req
 and nothing else — your workspace session never touches the agent's disk), and writes `.env`.
 Every later command reads `.env` from this directory automatically.
 
+What `.env` contains after a successful init: `DECIDIO_API_URL`, `DECIDIO_AGENT_ID`,
+`DECIDIO_AGENT_DID` + `DECIDIO_AGENT_KEY` (the local keypair — the key is what earns
+`application_confirmed` evidence later), `DECIDIO_API_TOKEN` (the floor-limited agent token),
+`DECIDIO_WORKSPACE_ID`, and `DECIDIO_WEBHOOK_SECRET` (operator deployments only). Pick any
+agent name — if it's already taken in your workspace, `init` stops cleanly and suggests a
+fresh one (or pass `--unique` to auto-append a random suffix — collision-proof for shared
+workspaces and CI). Headless terminal (no prompts possible)? Export `DECIDIO_SESSION_TOKEN` first:
+request a sign-in link, then exchange its `?login=` value at `POST /demo/login-consume` — the
+response's `token` is your session token (the CLI prints these exact instructions when it
+can't prompt).
+
 **3. Protect one function** — save this as `quickstart.mjs`:
 
 ```js
@@ -62,7 +94,11 @@ changed: `DECIDIO_SOURCE_SYSTEM=salesforce npx @decidio/sdk init my-sf-agent`. T
 named rule auto-approves amounts under $1M when the request carries the agent's signed
 identity proof, so even this $86k example would proceed there.)
 
-**5. Approve it** — in a second terminal (same directory):
+**5. Approve it** — in a second terminal (same directory; replace `<decisionId>` with the id
+step 4 printed — angle brackets are placeholders, never typed literally). Approvals are a
+*human* act, so this terminal needs your sign-in too: it will prompt, or export
+`DECIDIO_SESSION_TOKEN` here as well for headless shells (the `.env` deliberately holds only
+the agent's floor-limited token — it cannot approve anything):
 
 ```bash
 npx @decidio/sdk approvals               # see it pending
@@ -73,27 +109,32 @@ The moment you approve, the first terminal wakes: **your own function executes**
 holds your credentials or runs your code — and the SDK reports the captured result back, which
 becomes the record's execution evidence.
 
-**6. Download the receipt and verify it offline:**
+**6. Download the receipt (online), then verify it (offline):**
 
 ```bash
 npx @decidio/sdk receipt <decisionId>
-npx @decidio/verify decidio-receipt-<decisionId>.json
+npx @decidio/sdk verify decidio-receipt-<decisionId>.json
 ```
 
-The receipt is a W3C Verifiable Credential: the signature and content binding verify with no
-Decidio account and no network (after the one-time `npx` package download) — the evidence is
-yours, not ours. To also prove *who* issued it, pin your workspace's issuer:
-`npx @decidio/verify --issuer <did:key:...> receipt.json` (the DID is shown in your app's
+The download is an authenticated fetch from your workspace; the *verification* is fully
+offline — the verifier ships inside this package (no second download, no registry probe, same
+implementation as the standalone `@decidio/verify`). The receipt is a W3C Verifiable
+Credential: signature and content binding verify with no Decidio account and no network — the
+evidence is yours, not ours. To also prove *who* issued it, pin your workspace's issuer:
+`npx @decidio/sdk verify --issuer <did:key:...> receipt.json` (the DID is shown in your app's
 record verify panel). One receipt proves itself; chain order across receipts is verified when
 you pass several files at once.
 
 What the credential contains, honestly: the sealed **authority decision** — who decided, what
-was authorized, when, under which policy. It seals at decision time and is immutable, so
-execution evidence that arrives *after* the seal (your function's captured result) lives on the
-**record**, not inside the credential bytes: your Decidio record page shows the evidence tier
-(`application_confirmed` once the wrapper's signed report lands). Immutable seal + accruing
-evidence is the design, not an omission — corrections and later facts supersede, they never
-rewrite.
+was authorized, when, under which policy. It seals at decision time and is immutable — which is
+why the credential's own `confirmation.status` field reads `"pending"` forever. Execution
+evidence that arrives *after* the seal (your function's captured result) lives on the
+**record**, not inside the credential bytes: the `receipt` command prints the record's current
+tier next to the file, and with the signing key `init` wrote you'll see `application_confirmed`
+— the wrapper's report was cryptographically bound to your agent. (No signing key configured?
+The server caps the evidence at the weaker `agent_asserted`, and the SDK warns at confirm
+time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
+later facts supersede, they never rewrite.
 
 **7. Prove a replay is rejected:**
 

package/dist/adapters/_gate.js

@@ -32,6 +32,9 @@ export async function gateConfirm(config, decisionId, result) {
         // Sign the confirm too (bound to {action:"confirm", scope:decisionId}) so the adapter path
         // earns application_confirmed; without a key the server caps it at agent_asserted.
         const requesterIdentity = signConfirm(decisionId, config);
+        // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch).
+        if (!requesterIdentity)
+            console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
             method: "POST",
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },

package/dist/cli.js

@@ -24,6 +24,8 @@ import { createServer } from "node:http";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
+import { withApproval } from "./index.js";
+import { verifyReceipt, verifyChain } from "@decidio/verify";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -55,13 +57,19 @@ for (const [k, v] of Object.entries(readEnvFile())) {
     if (process.env[k] === undefined)
         process.env[k] = v;
 }
-const API = (process.env.DECIDIO_API_URL ?? "http://localhost:4000").replace(/\/$/, "");
-const TOKEN = process.env.DECIDIO_API_TOKEN;
+// `quickstart` is the zero-config guided tour: with no DECIDIO_API_URL anywhere it targets the
+// hosted sandbox (and says so); every other command keeps the localhost dev default.
+const IS_QUICKSTART = process.argv[2] === "quickstart";
+const API = (process.env.DECIDIO_API_URL ?? (IS_QUICKSTART ? "https://decidio-api.onrender.com" : "http://localhost:4000")).replace(/\/$/, "");
+// Token is read AT CALL TIME, not captured at import: init mints a fresh agent token mid-run and
+// its closing doctor must probe with THAT, not the pre-init env (round-3 Codex catch — the stale
+// capture made init's own doctor print "token: REJECTED" seconds after a successful mint).
+const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
 /** Fetch wrapper that turns transport failures into guidance instead of a stack trace. */
 async function api(path, init = {}, bearer) {
-    const auth = bearer ?? TOKEN;
+    const auth = bearer ?? TOKEN();
     let res;
     try {
         res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
@@ -189,18 +197,24 @@ async function cmdInit(agentId) {
     }
     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.
+        // Already registered to a server-held did. WITHOUT the original private key on this machine
+        // this is a HARD STOP, not a degraded continue (round-3 Codex catch: init used to write a
+        // keyless .env and print happy-path next steps — every request then routed unproven and
+        // execution evidence silently capped at agent_asserted).
         did = r.body?.did;
-        log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it.`);
-        if (sourceSystem)
-            log(`  Note: sourceSystem can't change on an existing agent — the registered lane stands. To use the "${sourceSystem}" lane, register a NEW name: npx @decidio/sdk init ${agentId}-${sourceSystem}`);
-        if (existingKey)
-            log(`  Your .env already carries a DECIDIO_AGENT_KEY; if it's this agent's original key, signing keeps working.`);
+        if (existingKey) {
+            log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it with the DECIDIO_AGENT_KEY already in .env.`);
+            if (sourceSystem)
+                log(`  Note: sourceSystem can't change on an existing agent — the registered lane stands. To use the "${sourceSystem}" lane, register a NEW name.`);
+        }
         else {
-            log(`  ⚠ Its private key lives wherever this agent was FIRST initialized — keys never leave the machine that made them.`);
-            log(`  Either restore that DECIDIO_AGENT_KEY into .env, or start fresh under a new name:`);
-            log(`    npx @decidio/sdk init ${agentId}-2`);
+            const suggestion = `${agentId}-${randomBytes(2).toString("hex")}`;
+            log(`✘ "${agentId}" is already registered in this workspace, and its private key is not on this machine`);
+            log(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
+            log(`  Nothing was written. Two ways forward:`);
+            log(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
+            log(`    2. Reuse "${agentId}": restore its original DECIDIO_AGENT_KEY into .env here, then re-run init.`);
+            return 1;
         }
     }
     else if (r.status >= 200 && r.status < 300) {
@@ -218,7 +232,7 @@ async function cmdInit(agentId) {
     // 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;
+    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) {
@@ -248,6 +262,11 @@ async function cmdInit(agentId) {
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     upsertEnv(envOut);
+    // The closing doctor (and anything else this process does) must see what init just wrote —
+    // OVERWRITE process.env with the fresh values (round-3 Codex catch: doctor probed with the
+    // stale pre-init token and reported the mint it just watched as REJECTED).
+    for (const [k, v] of Object.entries(envOut))
+        process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
     ensureGitignore();
     if (privateKey)
@@ -274,7 +293,7 @@ async function cmdInit(agentId) {
     log("");
     log(`     node --env-file=.env quickstart.mjs      # routes to a human, prints the decision id, waits`);
     log(`     npx @decidio/sdk approvals               # (second terminal) see it pending`);
-    log(`     npx @decidio/sdk approvals approve <id>  # approve -> your function runs -> sealed`);
+    log(`     npx @decidio/sdk approvals approve <id>  # approve -> your function runs -> evidence recorded`);
     log("");
     return cmdDoctor();
 }
@@ -305,12 +324,13 @@ async function cmdDoctor() {
     else if (rec.status === 401) {
         // A 401 off the agent floor could also mean an INVALID token (Codex catch: don't
         // false-green expiry). Disambiguate with a floor probe: a valid agent token gets 404 for an
-        // unknown decision (authorized, not found); an invalid one gets 401 again.
+        // unknown decision (authorized, not found); an invalid one gets 401 again. A rejection here
+        // flips the overall verdict — "all green" after a red line was round 3's other doctor bug.
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
             log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
         else if (probe.status === 401)
-            log("✘ token: REJECTED on the agent floor too — it's invalid or expired. Re-run `npx @decidio/sdk init` to mint a fresh one.");
+            line(false, "token: REJECTED on the agent floor too — it's invalid or expired. Re-run `npx @decidio/sdk init` to mint a fresh one.");
         else
             log(`⚠ token scope: agent-floor probe returned ${probe.status} — inconclusive`);
     }
@@ -322,6 +342,9 @@ async function cmdDoctor() {
 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.
+    const jsonMode = sub === "--json";
+    if (jsonMode)
+        sub = undefined;
     let bearer;
     const probe = await api("/api/decisions/cards");
     if (probe.status === 401 || probe.status === 403) {
@@ -368,6 +391,11 @@ async function cmdApprovals(sub, id, reason) {
     }
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
+    if (jsonMode) {
+        // Stable machine output (round-3 ask): agents scripting the queue parse this, not prose.
+        log(JSON.stringify(pending.map((c) => ({ decisionId: c.id, action: c.agentRequest?.action ?? null, amount: c.agentRequest?.amount ?? null, title: c.title ?? null })), null, 2));
+        return 0;
+    }
     if (!pending.length) {
         log("No pending agent approvals. Trigger one from your protected function, then re-run this.");
         return 0;
@@ -410,7 +438,7 @@ async function cmdReceipt(id) {
     }
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(name, JSON.stringify(r.body.credential, null, 2) + "\n");
-    log(`✔ wrote ${name}`);
+    log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
     // The credential seals at DECISION time (immutable), so execution evidence that arrived later
     // lives on the record — surface the CURRENT tier here so the reader doesn't need a second
     // lookup to see it (Codex catch).
@@ -418,12 +446,219 @@ async function cmdReceipt(id) {
     const conf = detail.body?.record?.confirmation;
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
-    log(`  Verify it offline — no Decidio account or network needed:`);
-    log(`    npx @decidio/verify ${name}`);
+    // Emit EXACTLY the deterministic command we document (round-4 catch: the README and this hint
+    // disagreed, and bare npx re-probes the registry) — the verifier ships INSIDE this package.
+    log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
+    log(`    npx @decidio/sdk verify ${name}`);
     log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
-    log(`    npx @decidio/verify --issuer <did:key:...> ${name}`);
+    log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
     return 0;
 }
+// ---- verify (embedded) ----------------------------------------------------------------------
+/** Duplicate-key-refusing parse — the SAME semantics as the decidio-verify CLI (RFC 8785 §3.1:
+ *  duplicate keys make different parsers disagree on which value is real; refuse instead).
+ *  Conformance-locked: the cross-language runner asserts this door refuses the same vectors for
+ *  the same reasons as decidio-verify and python -m decidio.verify. */
+function parseReceiptStrict(text, file) {
+    const value = JSON.parse(text);
+    const stack = [];
+    let i = 0;
+    const readString = () => {
+        let out = "";
+        i++;
+        while (i < text.length) {
+            const ch = text[i];
+            if (ch === "\\") {
+                out += text[i] + text[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === '"') {
+                i++;
+                return out;
+            }
+            out += ch;
+            i++;
+        }
+        return out;
+    };
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            const s = readString();
+            let j = i;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (text[j] === ":" && stack.length > 0) {
+                const key = JSON.parse(`"${s}"`);
+                const top = stack[stack.length - 1];
+                if (top.has(key))
+                    throw new Error(`${file}: duplicate JSON key ${JSON.stringify(key)} — RFC 8785 requires duplicate-free input, and different parsers disagree on which value is real`);
+                top.add(key);
+            }
+            continue;
+        }
+        if (ch === "{")
+            stack.push(new Set());
+        else if (ch === "}")
+            stack.pop();
+        i++;
+    }
+    return value;
+}
+function cmdVerify(argsIn) {
+    const issIdx = argsIn.indexOf("--issuer");
+    const expectedIssuer = issIdx >= 0 ? argsIn[issIdx + 1] : undefined;
+    const files = argsIn.filter((a, i) => !a.startsWith("--") && !(issIdx >= 0 && i === issIdx + 1));
+    if (!files.length) {
+        log("usage: npx @decidio/sdk verify [--issuer <did:key>] <receipt.json> [more.json ...]");
+        log("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
+        return 2;
+    }
+    let vcs;
+    try {
+        vcs = files.map((f) => parseReceiptStrict(readFileSync(f, "utf8"), f));
+    }
+    catch (e) {
+        log(`✘ INVALID  ${String(e?.message ?? e)}`);
+        return 1;
+    }
+    let allOk = true;
+    vcs.forEach((vc, i) => {
+        const res = verifyReceipt(vc, expectedIssuer);
+        allOk = allOk && res.valid;
+        log(`${res.valid ? "✔ VALID  " : "✘ INVALID"}  ${files[i]}`);
+        log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}`);
+        log(`    content-bound: ${res.contentBound}${res.reason ? `   reason: ${res.reason}` : ""}`);
+    });
+    if (vcs.length > 1) {
+        const c = verifyChain(vcs, expectedIssuer);
+        allOk = allOk && c.valid;
+        log(`\nchain: ${c.valid ? "✔ intact" : "✘ broken"} (${c.length}/${vcs.length})${c.reason ? ` — ${c.reason}` : ""}`);
+    }
+    return allOk ? 0 : 1;
+}
+// ---- quickstart (the guided two-minute tour) ------------------------------------------------
+async function cmdQuickstart() {
+    const t0 = Date.now();
+    log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
+    log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
+    log("");
+    const session = await acquireSession("The quickstart");
+    if (!session)
+        return 1;
+    // 1. A collision-proof agent, registered fresh every run (round-4 ask: idempotent sample
+    //    registration). Key generated locally; floor-limited token minted; .env written so the
+    //    take-away snippet works in this directory afterward.
+    const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
+    log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
+    const { did, privateKeyBase64 } = generateKeypair();
+    const reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+    if (!(reg.status >= 200 && reg.status < 300)) {
+        log(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
+        return 1;
+    }
+    const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart" }) }, session);
+    if (!(mint.status >= 200 && mint.status < 300) || !mint.body?.token) {
+        log(`✘ token mint failed (${mint.status}): ${JSON.stringify(mint.body)}`);
+        return 1;
+    }
+    const envOut = {
+        DECIDIO_API_URL: API, DECIDIO_AGENT_ID: agentId, DECIDIO_AGENT_DID: reg.body?.did ?? did,
+        DECIDIO_AGENT_KEY: privateKeyBase64, DECIDIO_API_TOKEN: mint.body.token,
+        DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "", DECIDIO_WEBHOOK_SECRET: readEnvFile().DECIDIO_WEBHOOK_SECRET || randomBytes(32).toString("hex"),
+    };
+    // NEVER clobber a real agent's key (guard catch: keys never leave this machine — overwriting
+    // .env's DECIDIO_AGENT_KEY orphans that agent irrecoverably). A directory that already holds
+    // one gets a TOUR-SCOPED env file instead.
+    let envFile = ENV_PATH;
+    if (readEnvFile().DECIDIO_AGENT_KEY) {
+        envFile = ".env.quickstart";
+        writeFileSync(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
+        log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
+    }
+    else {
+        upsertEnv(envOut);
+    }
+    ensureGitignore();
+    log(`  ✔ key generated locally (public half registered) · floor-limited token minted · ${envFile} written`);
+    log("");
+    // 2. Gate a demo action — the same one line you'd wrap your real function with.
+    log(`② Gating a demo action with ONE line — guard.protect(payInvoice, …):`);
+    log("");
+    log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
+    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }));`);
+    log("");
+    let decisionId = "";
+    const cfg = {
+        apiUrl: API, agentId, apiToken: mint.body.token, agentKey: privateKeyBase64,
+        agentDid: reg.body?.did ?? did, workspaceId: mint.body.workspaceId,
+        pollIntervalMs: 1500, pollTimeoutMs: 300_000,
+        onPending: (p) => { decisionId = p.decisionId; },
+    };
+    const payInvoice = withApproval(async (inv) => ({ paid: true, id: inv.id }), (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }), cfg);
+    const running = payInvoice({ id: "INV-2026-001", amount: 86_000 });
+    running.catch(() => { });
+    const waitStart = Date.now();
+    while (!decisionId && Date.now() - waitStart < 30_000)
+        await new Promise((r) => setTimeout(r, 250));
+    if (!decisionId) {
+        log("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
+        return 1;
+    }
+    log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
+    log(`    so deny-by-default sends everything to a person. Nothing executes until someone decides.`);
+    log("");
+    // 3. The human moment — approve right here, or from the Decidio app.
+    if (process.stdin.isTTY) {
+        await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
+    }
+    else {
+        log("③ Headless terminal — auto-approving with your session so the tour can continue.");
+    }
+    const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: "quickstart" }) }, session);
+    if (!(ap.status >= 200 && ap.status < 300)) {
+        log(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
+        return 1;
+    }
+    log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
+    // 4. The blocking wrapper wakes and runs the agent's own function.
+    let result;
+    try {
+        result = await running;
+    }
+    catch (e) {
+        log(`✘ the gated call did not complete: ${e?.message ?? e}`);
+        return 1;
+    }
+    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
+    log("");
+    // 5. The proof: download the receipt and verify it offline, all in-process.
+    log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
+    const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
+    if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
+        log(`✘ receipt fetch failed (${rec.status})`);
+        return 1;
+    }
+    const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
+    writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
+    const v = verifyReceipt(rec.body.credential, undefined);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding verified with NO network, no Decidio account)`);
+    const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
+    const tier = detail.body?.record?.confirmation?.status;
+    if (tier)
+        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's report was cryptographically bound to this agent`);
+    log("");
+    const secs = Math.round((Date.now() - t0) / 1000);
+    log(`Done in ${secs}s: gated → routed to a human → approved → executed once → sealed, verifiable proof in your hands.`);
+    log("");
+    log("Take it to your real agent — the .env here already works:");
+    log(`  import { guard } from "@decidio/sdk";`);
+    log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));`);
+    log("");
+    log("Next: the README's 7-step quickstart (durable mode, workers, adapters) · your queue at your Decidio app.");
+    return v.valid ? 0 : 1;
+}
 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.
@@ -453,15 +688,27 @@ function cmdDev(target, port) {
 }
 const USAGE = `decidio — the Decidio SDK command line
 
+  New here? See the whole thing work in about two minutes:
+
+      npx @decidio/sdk quickstart
+
+  It gates a demo action, routes it to YOU for approval, executes on your yes, and hands you a
+  cryptographically verifiable receipt. (Guided and explicit — this CLI never acts, signs you
+  in, or writes files unless you ask it to.)
+
+  npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
+                                       (--unique appends a random suffix — collision-proof samples)
   npx @decidio/sdk doctor              check config, connectivity, and what your token can do
-  npx @decidio/sdk approvals           list pending agent approvals
+  npx @decidio/sdk approvals [--json]  list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
+  npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
   npx @decidio/sdk --version           print the CLI version
 
+Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error.
 Docs: the README that shipped with this package (quickstart, durable resume, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
@@ -479,10 +726,20 @@ async function main(argv) {
         return 0;
     }
     switch (cmd) {
-        case "init": return cmdInit((a && !a.startsWith("-") ? a : undefined) ?? process.env.DECIDIO_AGENT_ID ?? "my-agent");
+        case "quickstart": return cmdQuickstart();
+        case "init": {
+            const argsIn = argv.slice(3);
+            const unique = argsIn.includes("--unique");
+            const nameArg = argsIn.find((x) => !x.startsWith("-"));
+            let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
+            if (unique)
+                name = `${name}-${randomBytes(2).toString("hex")}`;
+            return cmdInit(name);
+        }
         case "doctor": return cmdDoctor();
         case "approvals": return cmdApprovals(a, b, rest.join(" ") || undefined);
         case "receipt": return cmdReceipt(a);
+        case "verify": return cmdVerify(argv.slice(3));
         case "dev": {
             const args = argv.slice(3);
             const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };

package/dist/index.d.ts

@@ -75,6 +75,16 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+/** A transport failure with GUIDANCE instead of a raw undici stack (round-4 Codex catch: the CLI
+ *  wrapped network errors kindly but the runtime leaked `TypeError: fetch failed`). Carries the
+ *  endpoint, the operation, the underlying code, and the safety state a caller cares about most:
+ *  whether anything could have executed. */
+export declare class DecidioNetworkError extends Error {
+    endpoint: string;
+    op: string;
+    code: string | undefined;
+    constructor(endpoint: string, op: string, code: string | undefined, cause: unknown);
+}
 /**
  * Wrap an async action behind the Decidio gate. `describe` extracts the approval
  * context (action, amount, scope) from the call arguments. Returns a function with

package/dist/index.js

@@ -61,9 +61,37 @@ export class DecidioTimeoutError extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A transport failure with GUIDANCE instead of a raw undici stack (round-4 Codex catch: the CLI
+ *  wrapped network errors kindly but the runtime leaked `TypeError: fetch failed`). Carries the
+ *  endpoint, the operation, the underlying code, and the safety state a caller cares about most:
+ *  whether anything could have executed. */
+export class DecidioNetworkError extends Error {
+    endpoint;
+    op;
+    code;
+    constructor(endpoint, op, code, cause) {
+        super(`[decidio] could not reach ${endpoint} during ${op}${code ? ` (${code})` : ""}. ` +
+            `Nothing was executed locally and no verdict was received — if a request reached Decidio it is ` +
+            `visible in your queue. Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe ` +
+            `(a retry creates a new request — it can never double-execute).`);
+        this.endpoint = endpoint;
+        this.op = op;
+        this.code = code;
+        this.name = "DecidioNetworkError";
+        this.cause = cause;
+    }
+}
+async function reach(f, url, op, init) {
+    try {
+        return await f(url, init);
+    }
+    catch (e) {
+        throw new DecidioNetworkError(url, op, e?.cause?.code ?? e?.code, e);
+    }
+}
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
-    const res = await f(cfg.apiUrl.replace(/\/$/, "") + path, {
+    const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `POST ${path}`, {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
         body: JSON.stringify(body),
@@ -74,7 +102,7 @@ async function post(cfg, path, body) {
 }
 async function get(cfg, path) {
     const f = cfg.fetchImpl ?? fetch;
-    const res = await f(cfg.apiUrl.replace(/\/$/, "") + path, {
+    const res = await reach(f, cfg.apiUrl.replace(/\/$/, "") + path, `GET ${path}`, {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
     if (!res.ok)
@@ -190,6 +218,10 @@ export function withApproval(fn, describe, config) {
                 source: "wrapper", // the SDK captured the genuine response, not an agent self-report
                 ...(confirmIdentity ? { requesterIdentity: confirmIdentity } : {}),
             });
+            // An UNSIGNED confirm is server-capped at the weaker agent_asserted tier. Say so at the
+            // moment it happens — a silent evidence downgrade was round 3's acceptance FAIL.
+            if (!confirmIdentity)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID (npx @decidio/sdk init writes them) to earn application_confirmed.`);
         }
         catch (e) {
             // surface but don't throw — the action already happened

package/dist/resume.js

@@ -110,6 +110,10 @@ async function confirm(cfg, decisionId, capturedResponse) {
     // 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);
+    // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch): the durable
+    // path is what production agents run, so it must disclose an agent_asserted cap too.
+    if (!requesterIdentity)
+        console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
     await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.2
+  version: 0.1.4
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -79,5 +79,8 @@
     "typecheck": "tsc --noEmit",
     "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@decidio/verify": "^0.1.3"
   }
 }