@decidio/sdk 0.1.1 → 0.1.2

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**
 

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() {
@@ -239,25 +248,31 @@ 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`);
+    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("");
@@ -287,8 +302,18 @@ 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.
+        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.");
+        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`.");
@@ -386,6 +411,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 +460,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.

package/openapi.yaml

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