@decidio/sdk 0.6.4 → 0.7.0

package/dist/adapters/openai.d.ts

@@ -16,10 +16,27 @@ interface RunStateLike {
  *
  * const state = result.state;                       // or RunState from the run
  * const { resolved, pending } = await authorizeInterruptions(config, state, describe);
- * if (pending.length) { await store.put(decisionId, state.toString()); return; }  // suspend
+ * if (pending.length) {                             // suspend: park the state + each {callId, decisionId}
+ *   await store.put(runId, { state: state.toString(), pending: pending.map(({ callId, decisionId }) => ({ callId, decisionId })) });
+ *   return;
+ * }
  * result = await run(agent, state);                 // all resolved → resume
- * // on Decidio approval webhook: state = await RunState.fromString(agent, parked);
- * //   applyResume(state, item, verdict); result = await run(agent, state);
+ * // on Decidio's webhook (a wake-up): restore, find EACH parked call in the restored state by its call id,
+ * // and let Decidio decide it:
+ * //   const parked = await store.get(runId); const state = await RunState.fromString(agent, parked.state);
+ * //   for (const { callId, decisionId } of parked.pending) {
+ * //     const item = state.getInterruptions().find((i) => i.rawItem?.callId === callId);
+ * //     await applyVerifiedResume(config, state, item, decisionId, describe);
+ * //   }
+ * //   result = await run(agent, state);
+ *
+ * THE BINDING IS THE TOOL CALL (#4B review W2): a routed approval is bound to the described context AND
+ * the call itself - its name, call id and exact argument string (toolCallRequest). An item edited after
+ * approval, or a second identical call (another call id), never rides the approval.
+ *
+ * KNOWN LIMIT (predates 0.7.0): this door has no single-execution claim. The RunState is the host's own
+ * storage, so two concurrent resumes of the same parked state can both apply the approval and both run
+ * the tool; serialize resumes per run on your side (one worker per run id, or a lock).
  *
  * Duck-typed on the state/item (no hard @openai/agents import) so it stays thin.
  *
@@ -30,9 +47,12 @@ export interface Resolved {
     verdict: "approved" | "blocked";
     decisionId: string;
 }
+/** `callId` (0.7.0) is the tool call the approval is bound to - find the item again by it after
+ *  RunState.fromString. */
 export interface Pending {
     item: ToolApprovalItem;
     decisionId: string;
+    callId: string;
 }
 /** THIS DOOR AUTHORIZES; IT DOES NOT CONFIRM. Named `gateInterruptions` it looked like the other
  *  `decidioGate*` functions, which all run the action and report what happened. This one cannot:
@@ -42,7 +62,7 @@ export interface Pending {
  *  and a failed confirmation must not look alike.
  *
  *  proceed → state.approve(item); block → state.reject(item); route → pending (a human decides via
- *  Decidio; the host parks state.toString() + resumes via applyResume). */
+ *  Decidio; the host parks state.toString() + resumes via applyVerifiedResume). */
 export declare function authorizeInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
@@ -51,11 +71,21 @@ export declare function authorizeInterruptions(config: GuardConfig, state: RunSt
 /** @deprecated Renamed to `authorizeInterruptions` in 0.3.0 — the old name read like the other
  *  `decidioGate*` doors, which execute and confirm. This one only ever authorized. */
 export declare const gateInterruptions: typeof authorizeInterruptions;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
+/** Apply Decidio's answer for one routed tool call to a resumed RunState (after RunState.fromString)
+ *  - VERIFIED (0.7.0). It asks Decidio: GET /agent/status/:decisionId, and the approval must be bound
+ *  to THIS tool call - the commitment Decidio holds is recomputed over the call's name, call id and exact
+ *  argument string plus `describe(item)` (toolCallRequest), the same binding the call was authorized
+ *  with. A parked RunState is the host's own storage: an item whose arguments were edited there after a
+ *  human approved, or another call handed this call's decision id, must not ride that approval.
+ *
+ *  Approved and bound → state.approve(item), returns "approved". Rejected/blocked by Decidio →
+ *  state.reject(item), returns that verdict. Still pending, or approved for a DIFFERENT request, or not
+ *  tied to one → throws the typed refusal and the RunState is NOT modified.
  *
- *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a
- *  rejection, so a garbled payload, a version-skew verdict or an empty string became a rejection
- *  that a caller could not tell apart from a human deciding no — and the RunState was already
- *  mutated by the time anyone could look. The recognised set is exactly the one `resume` uses. */
-export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
+ *  REPLACES `applyResume(state, item, verdict)`, REMOVED in 0.7.0. It applied a bare verdict string
+ *  with no decision attached, so correctness depended entirely on the host routing the right verdict
+ *  to the right item. It was removed rather than deprecated: a deprecated function that still approves
+ *  keeps the hole open for every integration that never reads the warning, and one that refused
+ *  approvals at runtime would fail AFTER a human approved - the removal fails at build time instead. */
+export declare function applyVerifiedResume(config: GuardConfig, state: RunStateLike, item: ToolApprovalItem, decisionId: string, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<"approved" | "rejected" | "blocked">;
 export {};

package/dist/adapters/openai.js

@@ -1,10 +1,11 @@
-import { gateAuthorize, checkEngineVersion } from "./_gate.js";
-import { DecidioBlockedError } from "../index.js";
+import { gateAuthorize, gateCheckApproval, toolCallRequest, checkEngineVersion } from "./_gate.js";
+import { DecidioBlockedError, approvalRefusal, decisionIdProblem } from "../index.js";
 export async function authorizeInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
-    for (const item of state.getInterruptions()) {
-        const auth = await gateAuthorize(config, describe(item));
+    const batch = state.getInterruptions().map((item) => { const ctx = describe(item); return { item, ctx, request: toolCallRequest(item, ctx) }; });
+    for (const { item, ctx, request } of batch) {
+        const auth = await gateAuthorize(config, ctx, { request });
         if (auth.decision === "proceed") {
             state.approve(item);
             resolved.push({ item, verdict: "approved", decisionId: auth.decisionId });
@@ -14,22 +15,29 @@ export async function authorizeInterruptions(config, state, describe) {
             resolved.push({ item, verdict: "blocked", decisionId: auth.decisionId });
         }
         else if (auth.decision === "route")
-            pending.push({ item, decisionId: auth.decisionId });
+            pending.push({ item, decisionId: auth.decisionId, callId: request.args[0].callId });
         else
             throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
     return { resolved, pending, confirmationSupported: false };
 }
 export const gateInterruptions = authorizeInterruptions;
-export function applyResume(state, item, verdict) {
-    if (verdict === "approved" || verdict === "auto_approved") {
+export async function applyVerifiedResume(config, state, item, decisionId, describe) {
+    const idProblem = decisionIdProblem(decisionId);
+    if (idProblem)
+        throw new DecidioBlockedError(`applyVerifiedResume needs the decision this item was routed as (${idProblem}) - pass the decisionId authorizeInterruptions returned for it. The RunState was NOT modified.`, typeof decisionId === "string" ? decisionId : "");
+    const ctx = describe(item);
+    const check = await gateCheckApproval(config, decisionId, ctx, toolCallRequest(item, ctx));
+    if (check.ok) {
         state.approve(item);
-        return;
+        return "approved";
     }
-    if (verdict === "rejected" || verdict === "blocked") {
+    if (check.code === "rejected" || check.code === "blocked") {
         state.reject(item);
-        return;
+        return check.code;
     }
-    throw new DecidioBlockedError(`unrecognised resume verdict ${JSON.stringify(verdict)} — refusing to apply it. This SDK understands approved / auto_approved / rejected / blocked; anything else is a version skew, and guessing would turn "I do not understand" into a decision. The RunState was NOT modified.`, "");
+    const refusal = approvalRefusal(check);
+    refusal.message += " The RunState was NOT modified.";
+    throw refusal;
 }
 checkEngineVersion("openai");

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome, type ApprovalCheck } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -9,20 +9,39 @@ import { type GateAuth } from "./_gate.js";
  * const verdicts = installDecidioSignal();                 // wires the resume signal
  * const out = await decidioGate(config, ctx, () => createOpp(o), verdicts, {
  * authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities
+ * verify:    (id) => executeActivity(verifyActivity, id),      // body: return verifyApprovalActivity(config, id, ctx)
  * confirm:   (id, r) => executeActivity(confirmActivity, ...),
  * });
  * Decidio's webhook bridges to: handle.signal(decidioResumeSignal, decisionId, verdict, reason)
  *
+ * THE SIGNAL IS A WAKE-UP (0.7.0). Before 0.7.0 the action ran on the signal alone, so anyone who could
+ * signal the workflow with the decisionId approved it. Now the signal only wakes the workflow; `verify`
+ * then confirms with Decidio that THIS request was approved (GET /agent/status + the request
+ * commitment) before `run()`. Still pending → keep waiting for the next signal; rejected/blocked/changed
+ * → the typed refusal. `verify` is HTTP, so it must be an ACTIVITY, never workflow code (determinism) -
+ * and it is required whenever `authorize` is.
+ *
  * (This wiring doc ships in the .d.ts — the README points here.)
  */
 export declare const decidioResumeSignal: import("@temporalio/workflow").SignalDefinition<[string, string, (string | undefined)?]>;
-/** Call inside the workflow to wire the resume signal; returns the verdict store. */
+/** Call inside the workflow to wire the resume signal; returns the signal store. Since 0.7.0 an entry is
+ *  a WAKE-UP for its decision - the verdict it carries is informational and is consumed when the gate
+ *  checks the approval with Decidio. */
 export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;
 }>;
+/** The approval check as an ACTIVITY body (0.7.0) - register an activity that returns this, unchanged,
+ *  and route `verify` through it. GET /agent/status + the request commitment recomputed over `ctx`, which
+ *  must be the same context the gate authorized. Never call it from workflow code (it is HTTP). */
+export declare function verifyApprovalActivity(config: GuardConfig, decisionId: string, ctx: ApprovalContext): Promise<ApprovalCheck>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
+    /** THE APPROVAL CHECK, run after the resume signal and before `run()` (0.7.0). It is HTTP, so route it
+     *  through an ACTIVITY whose body is `return verifyApprovalActivity(config, decisionId, ctx)` - the same
+     *  `ctx` this gate authorized - and return that value unchanged. Required whenever `authorize` is
+     *  supplied; without either it defaults to a direct call (tests only - a workflow must not do I/O). */
+    verify?: (decisionId: string) => Promise<ApprovalCheck>;
     /** Reports through YOUR activity. Return the gate's confirm response body (validated with
      *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
      *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */

package/dist/adapters/temporal.js

@@ -1,21 +1,34 @@
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
-import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
+import { DecidioBlockedError, approvalRefusal } from "../index.js";
+import { gateAuthorize, gateConfirm, gateCheckApproval, assertApprovalCheckShape, checkEngineVersion, assertAuthorizeVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
 export function installDecidioSignal() {
     const verdicts = new Map();
     setHandler(decidioResumeSignal, (decisionId, verdict, reason) => { verdicts.set(decisionId, { verdict, reason }); });
     return verdicts;
 }
+export function verifyApprovalActivity(config, decisionId, ctx) {
+    return gateCheckApproval(config, decisionId, ctx);
+}
 let confirmWarned = false;
 export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
+    if (opts.authorize && !opts.verify) {
+        throw new Error("[decidio] temporal: `authorize` runs in your activity, so the approval check must too - pass `verify: (decisionId) => executeActivity(verifyActivity, decisionId)`, where the activity returns verifyApprovalActivity(config, decisionId, ctx) (from @decidio/sdk/temporal) unchanged. Since 0.7.0 a resume signal only wakes the workflow; the approval is confirmed with Decidio before your action runs. Nothing was routed or executed.");
+    }
     const auth = assertAuthorizeVerdict(await (opts.authorize ?? (() => gateAuthorize(config, ctx)))(), "unknown");
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        await condition(() => verdicts.has(auth.decisionId));
-        const v = verdicts.get(auth.decisionId);
-        assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
+        const verify = opts.verify ?? ((decisionId) => gateCheckApproval(config, decisionId, ctx));
+        for (;;) {
+            await condition(() => verdicts.has(auth.decisionId));
+            verdicts.delete(auth.decisionId);
+            const check = assertApprovalCheckShape(await verify(auth.decisionId), auth.decisionId);
+            if (check.ok)
+                break;
+            if (check.code !== "pending")
+                throw approvalRefusal(check);
+        }
     }
     else if (auth.decision !== "proceed") {
         throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)} — refusing to execute`, auth.decisionId);

package/dist/cli.d.ts

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
+/** The issuer store's key for a Decidio address: its origin (scheme + lowercased host + non-default port), computed by a
+ *  RESTRICTED parser that FAILS CLOSED, identically in both SDKs. It deliberately does NOT reproduce the browser URL's
+ *  canonicalisation: `new URL("https://%64ecidio-api.onrender.com").origin` is the real host, and keying by that let a
+ *  planted store entry under a percent-encoded / IDN / numeric-shorthand / backslash spelling be silently trusted AS the
+ *  real host (the Python twin, on urlsplit, never decoded these, so the two SDKs also disagreed). Now: only a bare
+ *  http(s)://, an ASCII-label host or a bracketed real IP literal is keyed as an origin; anything the parser is not sure
+ *  it can canonicalise the same in both languages is keyed as its trimmed lowercased self, which cannot equal a real
+ *  origin and so is never mistaken for one. Exported for the smokes; the Python twin _issuer_store_key answers the same. */
+export declare function issuerStoreKey(url: string): string;
 /** The agent id `init` uses when none is given: this folder's name (or the package name), slugified. "my-agent" told a
  *  tester nothing; the folder they are in is the agent they are building (founder ruling 2026-09-06). */
 export declare function defaultAgentId(dir?: string): string;