@decidio/sdk 0.1.1 → 0.1.3

package/README.md

@@ -4,9 +4,10 @@ One line to put a human-or-policy approval gate in front of any AI-agent action
 
 ## Quickstart — seven steps to your first sealed receipt
 
-Under 30 minutes, no help needed. You'll need Node 20+, a terminal, and a Decidio workspace
+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).
+synthetic data, safe to experiment in). Shell commands below are Bash; on PowerShell, `export
+NAME=value` becomes `$env:NAME="value"`.
 
 **1. Install**
 
@@ -28,6 +29,16 @@ 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. 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
@@ -76,7 +87,7 @@ becomes the record's execution evidence.
 
 ```bash
 npx @decidio/sdk receipt <decisionId>
-npx @decidio/verify decidio-receipt-<decisionId>.json
+npx --yes @decidio/verify decidio-receipt-<decisionId>.json
 ```
 
 The receipt is a W3C Verifiable Credential: the signature and content binding verify with no
@@ -87,12 +98,15 @@ record verify panel). One receipt proves itself; chain order across receipts is
 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

@@ -22,7 +22,16 @@ import { readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline";
+import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
+const VERSION = (() => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+})();
 // ---- environment: load the CWD .env FIRST (Codex finding: init writes .env, but the next
 // command ignored it and pointed at localhost). Process env always wins — .env only fills gaps.
 function readEnvFile() {
@@ -47,12 +56,15 @@ for (const [k, v] of Object.entries(readEnvFile())) {
         process.env[k] = v;
 }
 const API = (process.env.DECIDIO_API_URL ?? "http://localhost:4000").replace(/\/$/, "");
-const TOKEN = process.env.DECIDIO_API_TOKEN;
+// 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 ?? {}) } });
@@ -180,18 +192,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) {
@@ -209,7 +227,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) {
@@ -239,27 +257,38 @@ async function cmdInit(agentId) {
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     upsertEnv(envOut);
-    log(`✔ wrote ${ENV_PATH} — every decidio command and the SDK read it from this directory`);
+    // 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)
         log(`  (the agent's private signing key is in there — for production, move it to your secret manager)`);
     log("");
     log("Next: protect one function and watch it route. Two steps:");
     log("");
-    log("  1. Save this as quickstart.mjs:");
+    log("  1. Save this as quickstart.mjs (the same snippet as the README's step 3):");
     log("");
     log(`     import { guard } from "@decidio/sdk";`);
-    log(`     const payInvoiceRaw = async (inv) => ({ paid: true, id: inv.id });   // your real action`);
-    log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
-    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
-    log(`       { mode: "blocking" });   // blocking = watch it happen live; durable is the production mode`);
-    log(`     await payInvoice({ id: "INV-1", amount: 86000 });`);
+    log("");
+    log(`     const payInvoiceRaw = async (invoice) => ({ paid: true, id: invoice.id });   // your real action`);
+    log("");
+    log(`     const payInvoice = guard.protect(`);
+    log(`       payInvoiceRaw,`);
+    log(`       (invoice) => ({ action: "payInvoice", amount: invoice.amount, scope: "Invoice" }),`);
+    log(`       { mode: "blocking" },   // blocking = watch it happen live; durable is the production mode`);
+    log(`     );`);
+    log("");
+    log(`     const result = await payInvoice({ id: "INV-2026-001", amount: 86_000 });`);
+    log(`     console.log("executed after approval:", result);`);
     log("");
     log("  2. Run it, approve it, watch it complete:");
     log("");
-    log(`     node --env-file=.env quickstart.mjs      # routes to a human and waits`);
+    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();
 }
@@ -287,8 +316,19 @@ async function cmdDoctor() {
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
         log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
-    else if (rec.status === 401)
-        log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
+    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. 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)
+            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`);
+    }
     else
         log(`⚠ token scope: unexpected ${rec.status} from /api/records`);
     log(ok ? "\ndoctor: all green." : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
@@ -297,6 +337,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) {
@@ -343,6 +386,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;
@@ -386,6 +434,13 @@ 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}`);
+    // 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).
+    const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
+    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}`);
     log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
@@ -428,11 +483,16 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk approvals reject <id> [reason]
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
+  npx @decidio/sdk --version           print the CLI version
 
 Docs: the README that shipped with this package (quickstart, durable resume, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
     const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
+    if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+        log(VERSION);
+        return 0;
+    }
     if (!cmd || wantsHelp(cmd)) {
         log(USAGE);
         return 0;

package/dist/index.js

@@ -122,13 +122,16 @@ export function withApproval(fn, describe, config) {
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
         // 2. routed → either SUSPEND for async resume (durable) or BLOCK-poll (interactive)
         if (auth.decision === "route") {
-            // Hand back a link straight to the decision. An agent that suspends and says only "waiting"
-            // leaves the operator to go hunting through a queue; one that prints the URL does not.
+            // ALWAYS hand back the decision id — an agent that suspends and says only "waiting" leaves
+            // the operator hunting through a queue, and an agent that says NOTHING (the pre-0.1.2 bug:
+            // the print was gated on appUrl, which init never writes) leaves them staring at a silent
+            // terminal. The Codex acceptance run failed exactly this claim; the id line is unconditional
+            // now, with the deep link when appUrl is configured and the CLI command when not.
             const approvalUrl = decisionUrl(config.appUrl, auth.decisionId);
             if (config.onPending)
                 config.onPending({ decisionId: auth.decisionId, receiptId: auth.receiptId, url: approvalUrl });
-            else if (approvalUrl)
-                console.log(`[decidio] ${ctx.action} is awaiting approval — approve it at ${approvalUrl}`);
+            else
+                console.log(`[decidio] ${ctx.action} is awaiting approval (decision ${auth.decisionId}) — approve it ${approvalUrl ? `at ${approvalUrl}` : `in your Decidio queue, or: npx @decidio/sdk approvals approve ${auth.decisionId}`}`);
             // Durable transport: park the args agent-side, register the raw fn so a (cold)
             // resume can replay it, and SUSPEND. The process may exit now; the controller's
             // webhook handler or poll worker re-executes THIS fn when a human approves.
@@ -187,6 +190,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.0
+  version: 0.1.3
   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
@@ -154,7 +154,10 @@ paths:
         "404": { description: unknown decision }
   /agent/confirm:
     post:
-      summary: Report the captured execution outcome (seals the receipt's evidence tier)
+      summary: >
+        Report the captured execution outcome — recorded as the RECORD's evidence tier
+        (application_confirmed). The credential sealed at decision time is immutable; evidence
+        accrues on the record, never inside the sealed bytes.
       requestBody:
         required: true
         content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",