@decidio/sdk 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,8 +1,41 @@
 # Changelog — @decidio/sdk
 
-Release notes for the client SDK. The Python package `decidio` ships the same changes under the same
-version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
-on upgrade, and what proved it.
+Release notes for the client SDK. The Python package `decidio` ships under the same version; the core -
+the gate, signing, receipts and the verifier - is conformance-locked between the two, while the command line's
+first-run surfaces (the fork, `--demo`, the code sign-in) are TypeScript-first and named as such in the parity
+allowlist. Each entry names what changed, what a reader must do on upgrade, and what proved it.
+
+## 0.6.4 — the request closes when the agent gives up
+
+- **The README links the agent skill file** published on the site (https://decidioai.com/skills/decidio-guard.md, one page for both languages) and the site's llms.txt. The file is served by the site, not shipped in the package; an in-package copy is a one-line publish-boundary decision for this release if wanted.
+- **A blocking wait that hits `pollTimeoutMs` now WITHDRAWS its request** (`POST /agent/withdraw/<id>`
+  `{reason:"timeout"}`) before throwing `DecidioTimeoutError`. Before, the decision stayed open in Decidio
+  forever after this process had stopped waiting, so the queue carried a request nobody could act on and a
+  later tap sealed "approved" for an action that never ran. Now it leaves the queue as *withdrawn* and a
+  later approval is a no-op (`alreadyResolved`). `DecidioTimeoutError.withdrawn` says whether the call
+  landed; a failed withdraw changes nothing else (nothing executes either way). Withdrawing needs the
+  bound agent token and the signing key `init` writes — the gate refuses anyone else with 404, so an
+  unbound or unsigned caller simply sees `withdrawn:false`. If a human decided in the last poll window,
+  the gate answers 409 with that decision and the SDK honours it: the action runs as approved (and
+  confirms), or `DecidioRejectedError` is thrown — never a timeout that hides a decision. The durable
+  path is untouched — its parked action is exactly what a later approval resumes. The CLI tour and the
+  `--demo` stand-in say which of these happened. Nothing to do on upgrade.
+  Proved by: `smoke.ts` (the timeout vector now asserts exactly one withdraw after the last poll, and a
+  failing withdraw still ends in the same error with `withdrawn:false`; a 409 carrying `approved` runs and
+  confirms, `rejected` rejects; a wait that ends in a decision never withdraws) and, server-side,
+  `integration.smoke.ts` #W2 (a lab-posture boot with real bound tokens: another agent's token, an
+  anonymous caller and an unsigned receipt all get 404; the owner's later approve is `alreadyResolved`
+  with no sealed record; a second withdraw → 409) and #W (IdP posture: anonymous and IdP users → 404).
+
+## 0.6.3 — the two 0.6.2 reviews' small items
+
+- **`DECIDIO_DEBUG_INPUT=1` no longer prints what you type** (review: Medium). The 0.6.2 trace hex-dumped every stdin
+  byte - passwords, codes and links, muted prompt or not. It now prints the SHAPE only: control bytes named (`\r`, `\n`,
+  ESC), every printable byte as `x`. A newline problem is visible in the shape alone.
+- Four strings still described the sign-in as an emailed link to paste; they say the code now. The CHANGELOG's "twins"
+  line overstated CLI parity and now says exactly what is locked and what is TypeScript-first. Two README headings
+  still said "0.4". The offline local demo no longer prints "the terminal follows the web app or your phone" when it
+  has just said there are no such doors. `receipt --json` help says it prints a summary; the credential is the file.
 
 ## 0.6.2 — the fork after its first real run
 

package/README.md

@@ -23,7 +23,7 @@ you approve right there (or from your Decidio app), executes on approval, then d
 sealed Authority Receipt and verifies it offline in front of you, pinned to your workspace's
 issuer. It mints a **7-day** tour token (`init` mints 90-day tokens — different jobs, different
 lifetimes) and ends by offering to clean itself up (`quickstart cleanup` works later too).
-Sign in once — `npx @decidio/sdk login`, or when the tour asks: the CLI emails you a link, you paste it, and
+Sign in once — `npx @decidio/sdk login`, or when the tour asks: the CLI emails you an 8-character code, you type it, and
 the sign-in is kept in your profile (owner-only) for 30 days, or until this terminal closes, `logout`, or
 `quickstart cleanup`. At the human step the tour offers three doors: answer here, open the decision in
 the web app (a one-time link, signed in for you), or scan the QR with your phone — whichever answers
@@ -660,7 +660,7 @@ that fits every other confirm error.
 - **The token recovery journal** (`.decidio-token-journal`, owner-only, gitignored; ids and timestamps, never a token value; append-only by the CLI's behaviour — not OS-enforced or tamper-evident). One JSON row per event: `minted` (a token was issued, written BEFORE its credential file), `retired how=persisted` (the credential file now holds it - the token is live and that file is its handle; not revoked), `retired how=revoked` (revoked server-side), `probe` (a durability check). `doctor` names rows still outstanding; `quickstart cleanup` sweeps them.
 - `quickstart --demo` — the same tour with no account: an in-process stand-in of the API on 127.0.0.1 (shipped in this package) answers every door, a key generated for the run signs a real receipt (its content says `local-demo`; pinning it to the hosted issuer fails), and the web/phone door is a hosted demo decision page reached through a one-word relay (no account, no record, ten minutes). Your folder gains exactly one file, the receipt. Offline, the tour is terminal-only and says so.
 - `quickstart --phone web` — the QR at the human step opens the phone web rendering even when the Decidio app is installed (by default it opens the app when there is one).
-- `login [email]` / `logout` — sign in ONCE (the CLI emails you a link; you paste it) and forget that sign-in on this computer (the session token itself stays valid until it expires (up to 30 days) — there is no server-side revocation yet). The session is stored in your user profile, owner-only, bound to the terminal window that created it, for 30 days; `DECIDIO_SESSION_TOKEN` in the environment outranks it (headless shells).
+- `login [email]` / `logout` — sign in ONCE (the CLI emails you an 8-character code; you type it) and forget that sign-in on this computer (the session token itself stays valid until it expires (up to 30 days) — there is no server-side revocation yet). The session is stored in your user profile, owner-only, bound to the terminal window that created it, for 30 days; `DECIDIO_SESSION_TOKEN` in the environment outranks it (headless shells).
 - `dev [--target URL] [--port N]` — local relay for the resume webhook (operator setups)
 
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
@@ -680,7 +680,7 @@ manager for production.
 - `DecidioBlockedError` — policy blocked the action: a named block rule, or the universal backstop that fires when NO active policy governs agents at all (fail closed, no human involved). Distinct from routing-by-default — with an active policy and no matching auto-approve rule, a request is not blocked, it is ROUTED to a person.
 - `DecidioRejectedError` — a human rejected the routed action.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
-- `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); the decision stays open in Decidio, nothing executed locally.
+- `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); nothing executed locally. Since 0.6.4 the SDK's last act before throwing is to tell Decidio it gave up, so the request is closed as **withdrawn** (it leaves the queue; a later approval does nothing) — `error.withdrawn` is `true` when that landed and `false` when the call failed and the request may still be open. Withdrawing needs the bound agent token and the signing key `init` writes (an unbound or unsigned caller cannot withdraw anything — it just gets `withdrawn:false`). If a human decided in the last poll window, the SDK honours that decision instead: the action runs as approved, or `DecidioRejectedError` is thrown. The durable path never withdraws: its parked action is what a later approval resumes.
 - `DecidioRateLimitError` — the workspace's governed-action limit was hit; carries the server's `limit` / `remaining` / `resetAt`.
 - `DecidioHttpError` — the gate refused the call. Carries `status`, `endpoint`, the parsed `body`,
   and **`retryable`** — the field to branch on. A 401/403 is terminal (the agent token expired, or
@@ -703,7 +703,7 @@ Every error raised after a decision exists carries the `decisionId`, so a suspen
 timed-out action is always findable in
 your queue.
 
-## What 0.4 does not yet claim
+## What the SDK does not yet claim
 
 The retest that graded 0.3.3 *A- for the core and the shipped stores* and the first-run reviews of
 0.3.3 and 0.3.5 agree on what is left, and none of it is a defect a patch release closes. Stated here so
@@ -729,7 +729,7 @@ the next reader grades a promise, not a moving target:
 
 ## Compatibility and support
 
-- **Stable in 0.4:** `guard.protect` / `withApproval` and their options; the durable resume
+- **Stable surface:** `guard.protect` / `withApproval` and their options; the durable resume
   controller (`createDecidioResume`: `park`, `resolve`, `reconcile`, `reconfirm`, `recover`, the worker
   and both webhook handlers); the `PendingStore` contract and both shipped stores, including the on-disk
   revision-chain layout; `EvidenceOutcome` (a root export) and `ResumeStatus` / `RecoveryState` (on the
@@ -744,6 +744,7 @@ the next reader grades a promise, not a moving target:
 
 ## Notes
 
+- **Coding agents and assistants:** a one-page skill file for adding the gate to an agent — TypeScript and Python on the same page, what the gate does and does not do, the wrapper, first run vs production, the typed errors, how to verify a receipt — is published at https://decidioai.com/skills/decidio-guard.md (the site summary for machines is https://decidioai.com/llms.txt).
 - **Framework-agnostic:** it wraps at the tool-call boundary, so it works with any agent runtime (LangGraph, OpenAI Agents SDK, CrewAI, a raw tool loop) and any action (Salesforce, M365, SAP, a DB write).
 - **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`independently_reconciled`) where it holds a read connection.
 - **Zero-code alternative:** an agent that speaks MCP (e.g. Claude on the web) can reach the same gate via Decidio's `request_approval` MCP tool with no code at all.

package/dist/cli.js

@@ -501,7 +501,11 @@ function ask(question, mute = false) {
     });
 }
 if (process.env.DECIDIO_DEBUG_INPUT && process.stdin.isTTY) {
-    process.stdin.on("data", (c) => { process.stderr.write(`[stdin ${Buffer.from(c).toString("hex")}]\n`); });
+    process.stdin.on("data", (c) => {
+        const b = Buffer.from(c);
+        const shape = [...b].map((x) => x === 0x0d ? "\\r" : x === 0x0a ? "\\n" : x === 0x1b ? "ESC" : x < 0x20 ? `^${String.fromCharCode(x + 64)}` : x === 0x7f ? "DEL" : "x").join("");
+        process.stderr.write(`[stdin ${b.length}B ${shape}]\n`);
+    });
 }
 function terminalId() {
     for (const k of ["WT_SESSION", "VSCODE_IPC_HOOK_CLI", "TERM_SESSION_ID", "ITERM_SESSION_ID", "TMUX_PANE", "KONSOLE_DBUS_SESSION", "GNOME_TERMINAL_SCREEN", "WINDOWID"]) {
@@ -575,7 +579,7 @@ async function loginFlow(purpose, emailArg) {
         log("  ✘ no email given - re-run when you have it.");
         return null;
     }
-    const password = await ask("  password (Enter = emailed sign-in link): ", true);
+    const password = await ask("  password (Enter = emailed sign-in code): ", 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) {
@@ -1554,7 +1558,8 @@ async function cmdQuickstartInner(opts = {}) {
         }
         else if (doorLink)
             rows.push(`${bold("your phone")}   ${dim("the link above works on a phone too (no QR came back this time)")}`);
-        rows.push(dim("whichever answers first wins — the terminal follows the web app or your phone."));
+        if (!DEMO || doorLink)
+            rows.push(dim("whichever answers first wins — the terminal follows the web app or your phone."));
         block("③", "Your call", rows, "choice");
         let settledState = null;
         const settledP = running.then(() => { settledState = "approved"; }, (e) => { settledState = e instanceof DecidioRejectedError ? "rejected" : "other"; });
@@ -1605,8 +1610,12 @@ async function cmdQuickstartInner(opts = {}) {
             log(`③ the tour's blocking call gave up after 5 minutes while waiting for your answer, so your answer is NOT posted:`);
             if (DEMO)
                 log(`   the demo ends here; nothing is kept (the demo's agent, token and folder go now). Re-run and answer within 5 minutes.`);
+            else if (earlyError.withdrawn) {
+                log(`   the request was WITHDRAWN from your queue (it no longer waits for an answer; deciding it there does nothing). Re-run the tour and answer within 5 minutes.`);
+                log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
+            }
             else {
-                log(`   the request is still ROUTED in your queue - decide it there, or re-run the tour and answer within 5 minutes.`);
+                log(`   the request is still ROUTED in your queue (the withdraw call did not land) - decide it there, or re-run the tour and answer within 5 minutes.`);
                 log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
             }
             log("");
@@ -2186,7 +2195,9 @@ APPROVALS AND RECEIPTS
                                        If it starts with a dash, put it after -- or use --reason:
                                          ... approve <id> -- "-50% cut, per the board"
                                          ... approve <id> --reason "-50% cut, per the board"
-  npx @decidio/sdk receipt <id> [--json]   download a sealed decision's Authority Receipt (.json)
+  npx @decidio/sdk receipt <id> [--json]   download a sealed decision's Authority Receipt to a .json FILE; --json prints
+                                       a summary to stdout (file name, evidence, issuer, the identities you may see) -
+                                       the credential itself is the file
   npx @decidio/sdk verify --issuer <did> <receipt.json> [more...]   verify receipts OFFLINE, pinned to your
                                        workspace's issuer (--allow-unpinned: structural check only)
 

package/dist/demo-gate.js

@@ -35,6 +35,7 @@ export async function startDemoGate(opts = {}) {
     const issuerDid = "did:key:z" + b58(Buffer.concat([Buffer.from([0xed, 0x01]), issuerRaw]));
     const sealedAt = new Date().toISOString();
     let verdict = null;
+    let withdrawnDemo = false;
     let decidedBy = "the human at the terminal";
     let lastReason = "quickstart";
     let relayCode = null;
@@ -121,8 +122,16 @@ export async function startDemoGate(opts = {}) {
                             lastReason = "decided on the demo page";
                         }
                     }
+                    if (withdrawnDemo && !verdict)
+                        return send({ state: "rejected", reason: "quickstart: withdrawn — the tour stopped waiting" });
                     return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver" } : { state: verdict === "approve" ? "approved" : "pending" });
                 }
+                if (path.startsWith("/agent/withdraw/")) {
+                    if (verdict)
+                        return send({ code: "NOT_OPEN", state: verdict === "approve" ? "approved" : "rejected", decisionId: DECISION_ID }, 409);
+                    withdrawnDemo = true;
+                    return send({ ok: true, withdrawn: true, state: "rejected", decisionId: DECISION_ID, reason: "requester_stopped_waiting" });
+                }
                 if (/^\/api\/decisions\/[^/]+\/(approve|reject)$/.test(path)) {
                     const already = verdict !== null;
                     verdict = path.endsWith("/reject") ? "reject" : "approve";

package/dist/guard.js

@@ -65,8 +65,8 @@ export class Guard {
         if ((opts?.mode ?? "durable") === "blocking") {
             const ceilingMs = opts?.pollTimeoutMs ?? base.pollTimeoutMs ?? 600_000;
             console.warn(`[decidio] WARNING: blocking wait — this call gives up after ${Math.round(ceilingMs / 1000)}s ` +
-                `(pollTimeoutMs), and when it does, the decision stays OPEN in Decidio while this process stops waiting: ` +
-                `a later approval cannot resume it. Only safe for short, watched approvals — omit mode:"blocking" for ` +
+                `(pollTimeoutMs), and when it does, this process stops waiting and the request is withdrawn in Decidio: ` +
+                `a later approval does nothing. Only safe for short, watched approvals — omit mode:"blocking" for ` +
                 `durable async resume on real (minutes-to-days) approvals.`);
             return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
         }

package/dist/index.d.ts

@@ -82,7 +82,12 @@ export declare class DecidioRejectedError extends Error {
 }
 export declare class DecidioTimeoutError extends Error {
     decisionId: string;
-    constructor(decisionId: string);
+    withdrawn: boolean;
+    /** `withdrawn` (0.6.4+): true when the SDK told Decidio it gave up and the request was closed as
+     *  WITHDRAWN (the queue no longer carries it; a later approval does nothing); false when that
+     *  best-effort call failed, so the request may still be open in Decidio. Nothing was executed
+     *  locally either way. */
+    constructor(decisionId: string, withdrawn?: boolean);
 }
 /** A transport failure with GUIDANCE instead of a raw fetch stack. Carries the endpoint, the
  *  operation, the underlying code, and the safety state a caller cares about most: whether

package/dist/index.js

@@ -31,9 +31,11 @@ export class DecidioRejectedError extends Error {
 }
 export class DecidioTimeoutError extends Error {
     decisionId;
-    constructor(decisionId) {
+    withdrawn;
+    constructor(decisionId, withdrawn = false) {
         super(`Timed out waiting for human approval (${decisionId})`);
         this.decisionId = decisionId;
+        this.withdrawn = withdrawn;
         this.name = "DecidioTimeoutError";
     }
 }
@@ -192,8 +194,24 @@ export function withApproval(fn, describe, config, opts) {
                 if (st.state === "blocked")
                     throw new DecidioBlockedError(st.reason ?? "blocked", auth.decisionId);
                 if (Date.now() > deadline) {
-                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} is still open in Decidio, but this process stopped waiting and nothing was executed. Re-run to request again, or use durable resume (guard.worker()) so an approval is never lost.`);
-                    throw new DecidioTimeoutError(auth.decisionId);
+                    let withdrawn = false;
+                    let lateState = null;
+                    try {
+                        await post(config, `/agent/withdraw/${encodeURIComponent(auth.decisionId)}`, { reason: "timeout" });
+                        withdrawn = true;
+                    }
+                    catch (e) {
+                        if (e instanceof DecidioHttpError && e.status === 409 && typeof e.body?.state === "string")
+                            lateState = e.body.state;
+                    }
+                    if (lateState === "approved" || lateState === "auto_approved")
+                        break;
+                    if (lateState === "rejected")
+                        throw new DecidioRejectedError("rejected by approver", auth.decisionId);
+                    if (lateState === "blocked")
+                        throw new DecidioBlockedError("blocked", auth.decisionId);
+                    console.warn(`[decidio] blocking wait hit its ${Math.round(pollTimeout / 1000)}s limit — decision ${auth.decisionId} ${withdrawn ? "was withdrawn in Decidio (the queue no longer shows it; a later approval does nothing)" : "is still open in Decidio (the withdraw call failed), but this process stopped waiting"} and nothing was executed. Re-run to request again, or use durable resume (guard.worker()) so an approval is never lost.`);
+                    throw new DecidioTimeoutError(auth.decisionId, withdrawn);
                 }
                 await sleep(pollInterval);
             }

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.6.2   # tracks the SDK release - checked by packages/conformance/manifests.mjs
+  version: 0.6.4   # tracks the SDK release - checked by packages/conformance/manifests.mjs
   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.6.2",
+  "version": "0.6.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",
@@ -84,7 +84,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.6.2"
+    "@decidio/verify": "0.6.4"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {