@decidio/sdk 0.6.4 → 0.8.0

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.6.4   # tracks the SDK release - checked by packages/conformance/manifests.mjs
+  version: 0.8.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
@@ -65,7 +65,28 @@ components:
         resumeUrl:
           type: string
           format: uri
-          description: where Decidio POSTs the signed verdict when a routed decision resolves
+          description: where Decidio POSTs the signed wake-up when a routed decision resolves
+        requestCommitment:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+          description: >
+            REQUEST BINDING (SDK 0.7.0). An OPAQUE commitment to the exact request the agent will run:
+            lowercase-hex HMAC-SHA256 under a key only the agent holds (its Ed25519 signing key, else its
+            API token) over the canonical request. Stored with the decision and returned by
+            GET /agent/status; the SDK recomputes it over the request it is about to run and refuses a
+            mismatch. Carries no authority - the verdict is computed exactly as without it. Anything that
+            is not 64 lowercase hex is a 400.
+        idempotencyKey:
+          type: string
+          pattern: "^[A-Za-z0-9._:-]{16,128}$"
+          description: >
+            SDK 0.7.0. The same key from the same requester returns the SAME decision (idempotentReplay:
+            true) instead of a new one - an engine that re-runs its authorizing code on resume (LangGraph)
+            must not mint a phantom second decision. Accepted ONLY beside a requestCommitment (a key alone is
+            400). Stored only as a requester-scoped HMAC. A replay must be the same request twice over - the
+            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.
     AuthorizeResponse:
       type: object
       required: [decision, decisionId, receiptId]
@@ -79,6 +100,17 @@ components:
         decisionId: { type: string }
         receiptId: { type: string }
         reason: { type: string }
+        requestCommitment:
+          type: [string, "null"]
+          description: the commitment stored with the decision (SDK 0.7.0), null when none was sent
+        idempotentReplay:
+          type: boolean
+          description: >
+            present (true) when this answer is an idempotent replay of an existing decision: nothing was
+            evaluated, created, sealed or summoned again (one `agent.authorize.replayed` audit row is written),
+            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.
     StatusResponse:
       type: object
       required: [state]
@@ -87,6 +119,13 @@ components:
           type: string
           enum: [pending, approved, auto_approved, rejected, blocked]
         reason: { type: string }
+        requestCommitment:
+          type: [string, "null"]
+          description: >
+            SDK 0.7.0: the request commitment the decision was authorized with (null when none was
+            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.
     ConfirmRequest:
       type: object
       required: [decisionId, capturedResponse, source]
@@ -163,10 +202,13 @@ components:
           properties:
             status:
               type: string
-              enum: [executed, indeterminate, rejected, blocked, no_handler, unknown]
+              enum: [executed, indeterminate, rejected, blocked, no_handler, unknown, not_approved, request_unverified]
               description: >
                 the LOCAL run. `indeterminate` means the handler was invoked and its outcome is
-                unknown — it will NOT be retried automatically and needs reconcile().
+                unknown — it will NOT be retried automatically and needs reconcile(). Since SDK 0.7.0 the
+                webhook is a wake-up: `not_approved` = Decidio does not (yet) record an approval, so nothing
+                ran and the entry stays parked; `request_unverified` = the approval could not be tied to the
+                parked request (a different request, or no commitment from the gate), so nothing ran.
             decisionId: { type: string }
             reportRecorded: { type: boolean, description: "Decidio accepted the execution report." }
             executionConfirmed: { type: boolean, description: "the recorded tier attests a COMMITTED execution — a different question from reportRecorded." }
@@ -214,7 +256,11 @@ components:
       description: >
         OUTBOUND — Decidio → your resumeUrl when a routed decision is decided. The raw body is
         HMAC-signed; verify `x-decidio-signature: sha256=<hex>` with your DECIDIO_WEBHOOK_SECRET
-        BEFORE acting (the SDK resume controllers fail closed). A duplicate delivery cannot cause a
+        BEFORE acting (the SDK resume controllers fail closed; since SDK 0.7.0 there is no fallback to
+        the API token - no secret means 401). The server signs with DECIDIO_WEBHOOK_SECRET only and sends
+        no webhook without it; it is a dedicated secret - never the server's API_AUTH_TOKEN. It is a WAKE-UP, never the authority: since SDK 0.7.0 the
+        SDK reads only `decisionId`, then asks GET /agent/status and runs the parked action only when
+        Decidio records it approved for THIS request (the request commitment). A duplicate delivery cannot cause a
         second execution: the SDK writes a durable invoking marker before calling the handler,
         so once invocation may have begun it is never invoked again automatically.
         OPERATOR DEPLOYMENTS ONLY: signing uses a shared secret configured on both the Decidio
@@ -245,7 +291,20 @@ paths:
           content:
             application/json:
               schema: { $ref: "#/components/schemas/AuthorizeResponse" }
+        "400": { description: "a malformed field, including a requestCommitment or idempotencyKey outside its grammar, or an idempotencyKey without a requestCommitment" }
         "401": { description: missing/invalid agent token }
+        "409":
+          description: >
+            IDEMPOTENCY_CONFLICT (SDK 0.7.0) - this idempotencyKey already names a decision for a
+            DIFFERENT request (its requestCommitment, or its requester, action, amount or scope, differs).
+            Send a new key for the new request.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: [IDEMPOTENCY_CONFLICT] }
+                  message: { type: string }
   /agent/status/{decisionId}:
     get:
       summary: Poll a routed decision (blocking mode / durable worker)
@@ -328,7 +387,7 @@ paths:
   x-webhooks:
     resume:
       post:
-        summary: Signed verdict delivery (Decidio → agent resumeUrl)
+        summary: Signed wake-up delivery (Decidio → agent resumeUrl); the SDK confirms the approval with GET /agent/status before acting
         requestBody:
           content:
             application/json:

package/package.json

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