@decidio/sdk 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -5,6 +5,28 @@ the gate, signing, receipts and the verifier - is conformance-locked between the
 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

package/README.md

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

@@ -1610,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("");

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.3   # 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.3",
+  "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.3"
+    "@decidio/verify": "0.6.4"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {