@decidio/sdk 0.10.0 → 0.12.0

package/dist/resume.js

@@ -1,4 +1,4 @@
-import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, randomUUID } from "node:crypto";
+import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, randomUUID, randomBytes } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync, openSync, closeSync, fsyncSync, linkSync } from "node:fs";
 import { join } from "node:path";
 import { userInfo } from "node:os";
@@ -7,7 +7,7 @@ import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredentia
 import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody, tierConfirms, tombstoneTier } from "./evidence.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args, ...(p.requestCommitment !== undefined ? { requestCommitment: p.requestCommitment } : {}) }), "utf8");
+const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args, ...(p.requestCommitment !== undefined ? { requestCommitment: p.requestCommitment } : {}), ...(p.claimKey !== undefined ? { claimKey: p.claimKey } : {}) }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
     if (agentKey) {
@@ -882,6 +882,55 @@ export async function checkApproval(cfg, decisionId, request, opts = {}) {
     }
     return { ok: true, decisionId, state };
 }
+export const RETRY_DELAYS_MS = [300, 1_000];
+export const REQUEST_KEY_RE = /^[A-Za-z0-9._:-]{16,128}$/;
+export function newClaimKey() {
+    return `run_${randomBytes(18).toString("base64url")}`;
+}
+export async function claimApproval(cfg, decisionId, claimKey) {
+    const no = (code, reason, status) => ({ ok: false, decisionId, code, final: code === "already_used" || code === "expired" || code === "not_claimable", reason, ...(status !== undefined ? { status } : {}) });
+    if (typeof claimKey !== "string" || !REQUEST_KEY_RE.test(claimKey))
+        return no("refused", "this run's claim key is not one Decidio accepts (16-128 letters, digits, dot, colon, underscore or dash). Nothing ran.");
+    const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
+    const url = cfg.apiUrl.replace(/\/$/, "") + "/agent/claim/" + encodeURIComponent(decisionId);
+    let last = "";
+    for (let attempt = 0;; attempt++) {
+        let res;
+        try {
+            res = await f(url, { method: "POST", headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) }, body: JSON.stringify({ claimKey }) });
+        }
+        catch (e) {
+            last = `could not reach Decidio: ${e?.cause?.code ?? e?.code ?? e?.message ?? e}`;
+        }
+        if (res) {
+            const body = await res.json().catch(() => null);
+            if (res.status === 200) {
+                if (body && body.ok === true && body.claimed === true)
+                    return { ok: true, decisionId, again: body.again === true };
+                return no("unrecognized", "Decidio answered the claim with HTTP 200 but did not say this run collected the approval, and an answer this SDK does not understand is never permission. Nothing ran.", 200);
+            }
+            if (res.status === 409) {
+                const code = body?.code;
+                if (code === "ALREADY_USED")
+                    return no("already_used", "this approval was already used by another run. Ask again for a new approval. Nothing ran.", 409);
+                if (code === "EXPIRED")
+                    return no("expired", "this approval has expired. Ask again for a new approval. Nothing ran.", 409);
+                if (code === "NOT_CLAIMABLE")
+                    return no("not_claimable", "Decidio says this approval can't be collected by a run (only a person's approval is, and a deploy approval belongs to its deploy job). Nothing ran.", 409);
+                return no("unrecognized", `Decidio refused the claim with a code this SDK does not know (${JSON.stringify(code ?? null)}). Nothing ran.`, 409);
+            }
+            if (res.status === 404)
+                return no("not_found", "Decidio did not let this agent collect the approval (HTTP 404: it does not know this decision for this credential, or it predates approval claims). Nothing ran.", 404);
+            if (!(res.status === 429 || (res.status >= 500 && res.status !== 501)))
+                return no("refused", `Decidio refused to let this run collect the approval (HTTP ${res.status}). Nothing ran.`, res.status);
+            last = `HTTP ${res.status}`;
+        }
+        if (attempt >= RETRY_DELAYS_MS.length)
+            return no("unreachable", `could not collect the approval from Decidio after ${attempt + 1} tries (${last}). Nothing ran.`);
+        await sleep(RETRY_DELAYS_MS[attempt]);
+    }
+}
 const V2_STORE_METHODS = [
     "put", "get", "delete", "list",
     "claim", "markInvoking", "recordExecuted", "markIndeterminate", "markReported",
@@ -1125,6 +1174,25 @@ export function createDecidioResume(opts) {
             refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: ${check.reason}. Nothing ran; the parked entry is untouched for inspection. If the request really changed, reject this decision and re-run the action to request a fresh approval.`);
             return finish({ status: "request_unverified", decisionId, action: pending.action, reason: check.reason });
         }
+        if (check.state === "approved") {
+            let claimed;
+            try {
+                claimed = await claimApproval(ctrl, decisionId, pending.claimKey ?? newClaimKey());
+            }
+            catch (e) {
+                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+                throw e;
+            }
+            if (!claimed.ok) {
+                if (claimed.final) {
+                    await ctrl.store.markDiscarded(decisionId, "blocked", claimed.reason);
+                    await ctrl.store.delete(decisionId);
+                    return finish({ status: "blocked", decisionId, action: pending.action, reason: claimed.reason });
+                }
+                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+                throw new Error(`[decidio] ${decisionId}: ${claimed.reason} The entry stays parked; the next signal tries again with the same claim key.`);
+            }
+        }
         try {
             await ctrl.store.markInvoking(decisionId, attemptId);
         }
@@ -1194,10 +1262,11 @@ export function createDecidioResume(opts) {
             catch (e) {
                 throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} NOT parked and NOT executable — but decision ${p.decisionId} may already be routed; reject it in your queue: npx @decidio/sdk approvals reject ${p.decisionId}`, p.decisionId);
             }
-            const argsSig = signArgs(p, ctrl.agentKey, integrityKey());
+            const parked = { ...p, claimKey: p.claimKey ?? newClaimKey() };
+            const argsSig = signArgs(parked, ctrl.agentKey, integrityKey());
             if (!argsSig)
                 console.warn(`[decidio] parking ${p.decisionId} UNBOUND — no agent key or webhook secret to sign the payload with, so a modified pending file could not be detected. Run \`npx @decidio/sdk init\` to configure keys.`);
-            await ctrl.store.put({ ...p, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
+            await ctrl.store.put({ ...parked, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
         },
         async resolve(input) { return resolveCore(input); },
         webhookHandler() {
@@ -1478,7 +1547,7 @@ export function createDecidioResume(opts) {
                             else if (outcome.status === "rejected")
                                 console.error(`[decidio] resumed ${p.decisionId}: REJECTED — the parked "${p.action}" was discarded, nothing executed.`);
                             else if (outcome.status === "blocked")
-                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED by policy — the parked "${p.action}" was discarded, nothing executed.`);
+                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED ${outcome.reason ? `(${outcome.reason})` : "by policy"} — the parked "${p.action}" was discarded, nothing executed.`);
                             workerOpts?.onResolved?.(outcome);
                         }
                         catch (e) {

package/dist/signing.d.ts

@@ -126,6 +126,14 @@ export declare function requestCommitment(material: BindingMaterial, request: Co
 /** lowercase-hex idempotency key over an execution identity (e.g. LangGraph's thread + task +
  *  commitment), keyed so the host's thread ids never reach Decidio in the clear. */
 export declare function idempotencyKey(material: BindingMaterial, identity: Record<string, JsonValue>): string;
+/** THE REQUEST KEY A CALL SENDS BY DEFAULT (11f, founder 2026-10-30): an idempotency key over a per-call random id and
+ *  the request's commitment, so the SDK's own retry of one call is the same request (the gate answers the decision it
+ *  already made) while two calls stay two requests. Python twin: invocation_request_key. */
+export declare function invocationRequestKey(material: BindingMaterial, invocationId: string, commitment: string): string;
+/** A CALLER'S OWN REQUEST KEY (11f), e.g. an order id: keyed like every other identity, so the caller's id never reaches
+ *  Decidio in the clear. Deliberately NOT over the commitment: the same key for a changed request is the gate's 409
+ *  IDEMPOTENCY_CONFLICT, never a silent second request. Python twin: own_request_key. */
+export declare function ownRequestKey(material: BindingMaterial, key: string): string;
 /** The Claude Code hook's request scope: `cmd-` + 16 hex of a KEYED digest over the command text and its subject
  *  (chat approvals follow-up, invariant-guard 2026-10-15). The text may carry a credential the display redacts; an
  *  unkeyed digest sealed beside the redacted text would be an offline oracle for a weak password. Keyed under its own

package/dist/signing.js

@@ -198,6 +198,12 @@ export function requestCommitment(material, request) {
 export function idempotencyKey(material, identity) {
     return createHmac("sha256", bindingSubkey(material, "decidio.idempotency-key.v1")).update(canonicalJson(identity, "idempotency identity"), "utf8").digest("hex");
 }
+export function invocationRequestKey(material, invocationId, commitment) {
+    return idempotencyKey(material, { invocation: invocationId, commitment });
+}
+export function ownRequestKey(material, key) {
+    return idempotencyKey(material, { requestKey: key });
+}
 export function boundScope(material, text) {
     return "cmd-" + createHmac("sha256", bindingSubkey(material, "decidio.hook-scope.v1")).update(text, "utf8").digest("hex").slice(0, 16);
 }

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.10.0   # tracks the SDK release - checked by packages/conformance/manifests.mjs
+  version: 0.12.0   # 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
@@ -87,6 +87,15 @@ components:
             same requestCommitment AND the same requester, action, amount and scope (the server binds that
             tuple itself) - otherwise 409 IDEMPOTENCY_CONFLICT; an earlier decision is never handed back for a
             changed request.
+
+
+            SDK 0.12.0 sends one BY DEFAULT beside every requestCommitment: a keyed HMAC over a fresh id for the
+            call and the commitment (or over the caller's own key, or an engine's own id for the call - an
+            OpenAI tool call id, a Temporal workflow run and activity, an Inngest run), and retries a network
+            failure, a 5xx or a non-AGENT_RATE 429 with the SAME key: a retry of a request still waiting is
+            answered with the one already waiting, and no retry runs an action twice. (A request is not
+            guaranteed single: an auto-approval whose answer is lost on every try, or a keyless request a policy
+            blocks, can make a second decision.) Without key material there is no commitment and no key.
     AuthorizeResponse:
       type: object
       required: [decision, decisionId, receiptId]
@@ -111,14 +120,27 @@ components:
             and `receipt` carries only the fields fixed at create. A sealed auto-approval replays as `proceed`
             only when THIS call could itself auto-approve (a verified, replay-protected identity or a trusted
             transport); anything else answers `route` or `block` - ask GET /agent/status for the real state.
+        openTwin:
+          type: boolean
+          description: >
+            present (true, beside idempotentReplay) when this KEYLESS request joined the same request from the
+            same agent that is still waiting for a person: nothing new was created, counted or summoned, and the
+            caller waits on that decision. The request may be shared, so a caller that gives up waiting must not
+            withdraw it (the SDKs skip their timeout withdraw after either flag; the server refuses a shared
+            withdraw with 409 SHARED_REQUEST).
     StatusResponse:
       type: object
       required: [state]
+      description: >
+        Reading the status claims NOTHING: a dashboard, the CLI or a second watcher can poll it freely. The run
+        that acts on a person's approval collects it with POST /agent/claim/{decisionId}.
       properties:
         state:
           type: string
           enum: [pending, approved, auto_approved, rejected, blocked]
-        reason: { type: string }
+        decisionId: { type: string }
+        receiptId: { type: [string, "null"] }
+        reason: { type: [string, "null"], description: the approver's reason, tokenized; never a cleartext name }
         requestCommitment:
           type: [string, "null"]
           description: >
@@ -126,6 +148,27 @@ components:
             sent). The SDK treats an approval as covering the request it is about to run only when this
             equals its own recompute; a gate that returns no commitment for a request the SDK bound is
             refused (commitment_missing), never trusted.
+        spent:
+          type: boolean
+          description: >
+            SDK 0.8.0: true once an execution is recorded on this approval - one approval covers one action,
+            once. The SDKs refuse to run on a spent approval and ask again.
+        grantExpiresAt:
+          type: [string, "null"]
+          format: date-time
+          description: >
+            SDK 0.8.0: when a granted decision's approval lapses (its seal's time plus the gate's TTL); null
+            otherwise. A granted decision with no expiry has a grant of unknown age, which the SDKs treat as
+            expired.
+        handedBackAt:
+          type: [string, "null"]
+          format: date-time
+          description: when an idempotent replay handed this granted decision back to a retry (null otherwise)
+        claimed:
+          type: boolean
+          description: >
+            SDK 0.12.0: whether a run has collected this person's approval (POST /agent/claim) - never by whom.
+            Informational: it claims nothing, and a caller decides a claim only by claiming.
     ConfirmRequest:
       type: object
       required: [decisionId, capturedResponse, source]
@@ -328,6 +371,119 @@ paths:
             check runs BEFORE any lookup, so this response reveals nothing about existence.
         "401": { description: missing/invalid agent token }
         "404": { description: unknown decision }
+  /agent/claim/{decisionId}:
+    post:
+      summary: Collect a person's approval for ONE run, once, right before acting on it (SDK 0.12.0)
+      description: >
+        Several programs can wait on one approval (callers that asked the same request, a second poller); only
+        the run that collects it runs it. The first claim wins. The same claimKey claiming again is the same run
+        retrying (a lost answer) and is answered the same, with `again: true`. Any other key is told the
+        approval was already used, and asks again. Only a PERSON's approval (state `approved`) is claimed: an
+        auto-approval is never shared, so it is NOT_CLAIMABLE, and so are a refusal, a waiting request and a
+        GitHub deploy approval (its deploy job uses it). A spent or expired approval is refused before anything
+        is written. A person's sign-in cannot claim (people approve, runs claim): it gets the 404. A bound agent
+        token claims only its own signed decisions; an unsigned decision is claimable by any agent credential
+        of the workspace (founder call 29). The SDKs make the claimKey at random for each run (two workers with
+        one key would be one run), retry a network failure or a 5xx with the SAME key, and run only on a 200.
+      parameters:
+        - name: decisionId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [claimKey]
+              properties:
+                claimKey:
+                  type: string
+                  pattern: "^[A-Za-z0-9._:-]{16,128}$"
+                  description: the run's own key; stored only as a keyed digest scoped to this decision
+      responses:
+        "200":
+          description: this run collected the approval - run the action
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, claimed, decisionId, again]
+                properties:
+                  ok: { type: boolean, enum: [true] }
+                  claimed: { type: boolean, enum: [true] }
+                  decisionId: { type: string }
+                  again: { type: boolean, description: true when the same key claimed again (the same run retrying) }
+        "400": { description: "a malformed decision id (INVALID_DECISION_ID) or claimKey (VALIDATION)" }
+        "401": { description: missing/invalid agent token }
+        "404": { description: unknown decision, one this credential may not claim, or a person's sign-in }
+        "409":
+          description: >
+            Do NOT run. `ALREADY_USED` - another run collected this approval, or it was already used: ask again
+            for a new one. `EXPIRED` - the approval lapsed: ask again. `NOT_CLAIMABLE` - not a person's approval
+            (still waiting, refused, an auto-approval, or a deploy approval).
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: [ALREADY_USED, EXPIRED, NOT_CLAIMABLE] }
+                  decisionId: { type: string }
+                  state: { type: string, enum: [pending, approved, auto_approved, rejected, blocked] }
+                  message: { type: string }
+  /agent/withdraw/{decisionId}:
+    post:
+      summary: The requester stopped waiting - close its OPEN routed request as withdrawn (SDK 0.6.4)
+      description: >
+        The blocking SDK wait calls this when it hits its ceiling, so the queue stops carrying a request nobody
+        will act on and a later tap cannot seal "approved" for an action that will never run. A withdrawal only
+        ever reduces authority. Only the requester may withdraw: a bound agent token whose agent signed the
+        request; everything else is the 404. A withdrawn request reads `rejected` on GET /agent/status. A SHARED
+        request is never withdrawn: once another caller joined it (openTwin), the answer is 409 SHARED_REQUEST and
+        nothing changes. The SDKs skip the withdraw after an `idempotentReplay` or `openTwin` answer.
+      parameters:
+        - name: decisionId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason: { type: string, enum: [timeout, cancelled], description: "default timeout" }
+      responses:
+        "200":
+          description: withdrawn
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  withdrawn: { type: boolean, enum: [true] }
+                  state: { type: string, enum: [rejected] }
+                  decisionId: { type: string }
+                  reason: { type: string }
+        "400": { description: "a malformed decision id (INVALID_DECISION_ID) or an unknown reason (INVALID_REASON)" }
+        "401": { description: missing/invalid agent token }
+        "404": { description: unknown decision, or not this requester's own signed request }
+        "409":
+          description: >
+            `NOT_OPEN` - a decision already stands (or it was already withdrawn); `state` is the derived state, so
+            an approval that landed in the last moment is honoured. `SHARED_REQUEST` - another caller is waiting on
+            this same request; nothing changed (no `state`), and a person still decides it.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: [NOT_OPEN, SHARED_REQUEST] }
+                  state: { type: string, enum: [pending, approved, auto_approved, rejected, blocked] }
+                  decisionId: { type: string }
+                  message: { type: string }
   /agent/confirm:
     post:
       summary: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "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.10.0"
+    "@decidio/verify": "0.12.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {