@decidio/sdk 0.11.0 → 0.12.0

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.11.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.11.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.11.0"
+    "@decidio/verify": "0.12.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {