@decidio/sdk 0.1.5 → 0.1.7

package/README.md

@@ -51,7 +51,8 @@ Every later command reads `.env` from this directory automatically.
 
 What `.env` contains after a successful init: `DECIDIO_API_URL`, `DECIDIO_AGENT_ID`,
 `DECIDIO_AGENT_DID` + `DECIDIO_AGENT_KEY` (the local keypair — the key is what earns
-`application_confirmed` evidence later), `DECIDIO_API_TOKEN` (the floor-limited agent token),
+`application_confirmed` evidence later), `DECIDIO_API_TOKEN` (the floor-limited agent token —
+90 days by default, `--expires-days N` to change),
 `DECIDIO_WORKSPACE_ID`, and `DECIDIO_WEBHOOK_SECRET` (operator deployments only). Pick any
 agent name — if it's already taken in your workspace, `init` stops cleanly and suggests a
 fresh one (or pass `--unique` to auto-append a random suffix — collision-proof for shared
@@ -122,8 +123,13 @@ implementation as the standalone `@decidio/verify`). The receipt is a W3C Verifi
 Credential: signature and content binding verify with no Decidio account and no network — the
 evidence is yours, not ours. To also prove *who* issued it, pin your workspace's issuer:
 `npx @decidio/sdk verify --issuer <did:key:...> receipt.json` (the DID is shown in your app's
-record verify panel). One receipt proves itself; chain order across receipts is verified when
-you pass several files at once.
+record verify panel — or simply read it off the `receipt` command's output, which prints your
+workspace's issuer DID from the authenticated response so you never have to hunt for it).
+
+One receipt proves itself. Pass several files and their **ordering** is verified too: the first
+file is the anchor and each subsequent receipt must follow it, so verifying any consecutive
+*segment* works — you are told whether the segment starts at your workspace's genesis or
+mid-history, and a set spanning two different issuers is refused outright.
 
 What the credential contains, honestly: the sealed **authority decision** — who decided, what
 was authorized, when, under which policy. It seals at decision time and is immutable — which is
@@ -168,15 +174,36 @@ waiting: it parks its call arguments agent-side (`.decidio-pending/` by default
 stores none of your downstream payload) and throws `DecidioSuspendedError`. The process may
 exit. Two ways the parked action resumes when a human decides:
 
-**The worker (self-serve — start here).** One line in any long-lived process:
+**The worker (self-serve — start here).** No inbound URL, no shared secrets, and it resumes work
+the current process never started. Here is a complete `agent.mjs` you can run:
 
 ```js
 import { guard } from "@decidio/sdk";
-guard.worker();   // polls Decidio outward, re-executes parked actions on approval, exactly once
+
+const payInvoiceRaw = async (invoice) => ({ paid: true, id: invoice.id });
+
+// Declare the action name so the wrapper registers at LOAD time, not on first call —
+// that is what lets a restarted process resume actions approved while it was down.
+const payInvoice = guard.protect(
+  payInvoiceRaw,
+  (invoice) => ({ action: "payInvoice", amount: invoice.amount, scope: "Invoice" }),
+  { action: "payInvoice" },
+);
+
+guard.worker();   // polls Decidio, re-executes parked actions on approval, one execution each
+
+// New work suspends immediately; approvals land later, through the same worker.
+try { await payInvoice({ id: "INV-1", amount: 86_000 }); }
+catch (e) { console.log(e.name); }   // DecidioSuspendedError — expected, not a failure
 ```
 
-No inbound URL, no shared secrets, survives restarts. This is the transport to use against the
-hosted sandbox.
+Run it with `node --env-file=.env agent.mjs`, approve from another terminal, and the running
+worker executes it. Kill the process, restart it, then approve: it still executes, because the
+action was registered at load. **If you can't declare the name at wrap time** (a dynamic
+`describe`), register the raw function explicitly at startup instead —
+`guard.register("payInvoice", payInvoiceRaw)` — before calling `guard.worker()`. Without one of
+those two, a cold worker has an empty registry and reports `no_handler` (the parked action is
+kept, not lost, and the message names the exact fix).
 
 **The signed webhook (operator deployments).** Decidio POSTs a signed verdict to your agent's
 `resumeUrl`; the handler verifies the HMAC signature fail-closed, then re-runs your function:
@@ -192,8 +219,27 @@ also allow-list resume hosts (default-deny). That's operator territory: if you r
 Decidio (or we run a pilot with you), the webhook is set up then. Against the hosted sandbox,
 use the worker — a webhook secret your server never learned would (correctly) fail closed.
 
-Either way, re-execution is **single-use** — the parked entry is claimed on completion, so a
-duplicate signal can't double-write.
+Either way, re-execution is **single-use on the happy path**: the parked entry is claimed before
+execution and deleted on success, so a duplicate signal finds nothing to replay. Honest edge — if
+your action succeeds but the process dies *before* the entry is cleared, the claim can be retried
+(robust crash-recovery of stale claims is on the roadmap), so make your downstream action
+idempotent if you need exactly-once under crashes.
+
+**Parked arguments must be JSON-serializable.** A suspended action is signed and then written to
+disk as JSON, so values that don't survive `JSON.stringify` round-tripping — `Date`, `Map`,
+`undefined`, `NaN`, class instances with custom `toJSON` — come back changed and fail the
+integrity check on resume (a refusal, never a wrong execution). Pass plain data; rehydrate
+inside your function.
+
+**Payload integrity.** When a routed action is parked, the SDK signs its arguments (bound to the
+decision id) with your agent key; on resume it **refuses to execute** if the parked payload was
+modified, its signature stripped, or the file swapped into another decision's slot. That defends
+against tampering by anything lacking your agent's key — note a *fully compromised agent host*
+can bypass the guard entirely (it holds both the key and the function), so the durable guarantee
+that closes that gap is server-sealed argument binding, auditable in the receipt itself, which is
+on the roadmap. **Upgrading from ≤0.1.5:** entries parked by an older version carry no signature
+and are refused once your agent has a key — drain pending approvals before upgrading, or delete
+the parked files and re-run those actions.
 
 ### Already on a durable engine? Use its native wait
 
@@ -214,9 +260,9 @@ imports none of them. Each adapter's shipped `.d.ts` header documents its wiring
 `npx @decidio/sdk <cmd>`:
 
 - `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
-- `init [agentId] [--unique]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries)
+- `init [agentId] [--unique] [--force] [--expires-days N]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries). Refuses to overwrite a *different* agent's key in this directory; `--force` backs the old `.env` up first.
 - `doctor` — config, connectivity, and what your current token can do
-- `approvals` / `approvals approve|reject <id> [reason]` — the human side, from your terminal
+- `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
 - `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
 - `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency)
 - `dev [--target URL]` — local relay for the resume webhook (operator setups)

package/dist/adapters/_gate.d.ts

@@ -7,7 +7,5 @@ export interface GateAuth {
 }
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
 export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown): Promise<void>;
-/** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export declare function verdictFrom(payload: any): string;
-/** Throw the right error for a non-approving verdict; return for approved/auto_approved. */
 export declare function assertVerdict(verdict: string, decisionId: string, reason?: string): void;

package/dist/adapters/_gate.js

@@ -1,15 +1,7 @@
-// Shared adapter gate logic (TS) — the thin-adapter rule in code. Every engine adapter
-// reuses these gate calls + verdict handling; only the suspend/resume translation
-// differs. Pure/testable so the offline smoke covers our logic; the engine-primitive
-// call in each adapter is a thin one-liner verified by typecheck against real types.
 import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm } from "../index.js";
 export async function gateAuthorize(config, ctx) {
     const f = config.fetchImpl ?? fetch;
-    // Fall back to the resume controller's URL (matches the core wrapper) so an adapter
-    // decision carries a callback URL even when only resume.resumeUrl was set.
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    // Sign the bound identity proof like the core wrapper, so an adapter-path agent can PROVE
-    // its identity and auto-approve (not just route). No key → unsigned → server routes.
     const requesterIdentity = (config.agentKey && config.agentDid)
         ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
         : undefined;
@@ -29,10 +21,7 @@ export async function gateAuthorize(config, ctx) {
 export async function gateConfirm(config, decisionId, result) {
     const f = config.fetchImpl ?? fetch;
     try {
-        // Sign the confirm too (bound to {action:"confirm", scope:decisionId}) so the adapter path
-        // earns application_confirmed; without a key the server caps it at agent_asserted.
         const requesterIdentity = signConfirm(decisionId, config);
-        // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch).
         if (!requesterIdentity)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
@@ -40,8 +29,6 @@ export async function gateConfirm(config, decisionId, result) {
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
             body: JSON.stringify({ decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
         });
-        // fetch only rejects on network error — surface a non-2xx (auth/500) too. Best-effort:
-        // log, don't throw (the action already happened).
         if (!res.ok)
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
     }
@@ -49,11 +36,9 @@ export async function gateConfirm(config, decisionId, result) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
     }
 }
-/** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export function verdictFrom(payload) {
     return (payload && typeof payload === "object" ? payload.verdict : payload) ?? "";
 }
-/** Throw the right error for a non-approving verdict; return for approved/auto_approved. */
 export function assertVerdict(verdict, decisionId, reason) {
     if (verdict === "approved" || verdict === "auto_approved")
         return;

package/dist/adapters/langgraph.d.ts

@@ -1,9 +1,6 @@
 import { Command } from "@langchain/langgraph";
 import { type GuardConfig, type ApprovalContext } from "../index.js";
-/** Gate `run()` behind Decidio inside a LangGraph node. */
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>): Promise<R>;
-/** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
- *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
 export declare function decidioResumeCommand(body: {
     verdict?: string;
     reason?: string;

package/dist/adapters/langgraph.js

@@ -1,19 +1,11 @@
-// @decidio/sdk/langgraph — durable suspend via LangGraph's native `interrupt()`.
-// `interrupt` finds the running graph itself (no handle needed), so the gate drops into
-// a node: authorize → on route, interrupt() durably pauses (the checkpointer persists;
-// the process can die) → on resume (Command(resume={verdict})) run the agent's own
-// action + confirm. Decidio is the approval system; the host bridges its webhook to the
-// graph resume (decidioResumeCommand). Requires @langchain/langgraph (optional peer dep).
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
-/** Gate `run()` behind Decidio inside a LangGraph node. */
 export async function decidioGate(config, ctx, run) {
     const auth = await gateAuthorize(config, ctx);
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        // Durable pause. On resume, interrupt() returns the Command(resume=...) payload.
         const resumed = interrupt({ decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } });
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
@@ -21,8 +13,6 @@ export async function decidioGate(config, ctx, run) {
     await gateConfirm(config, auth.decisionId, result);
     return result;
 }
-/** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
- *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
 export function decidioResumeCommand(body) {
     return new Command({ resume: { verdict: body.verdict, reason: body.reason } });
 }

package/dist/adapters/openai.d.ts

@@ -14,13 +14,9 @@ export interface Pending {
     item: ToolApprovalItem;
     decisionId: string;
 }
-/** Ask Decidio for each pending tool-approval on a RunState.
- *  proceed → state.approve(item); block → state.reject(item); route → pending (a human
- *  decides via Decidio; the host parks state.toString() + resumes via applyResume). */
 export declare function gateInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
 }>;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
 export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
 export {};

package/dist/adapters/openai.js

@@ -1,23 +1,4 @@
-// @decidio/sdk/openai — gate OpenAI Agents SDK tool-approval interruptions through
-// Decidio, with durable suspend via the SDK's native RunState serialization.
-//
-// The Agents loop surfaces tool approvals on the RunState (state.getInterruptions());
-// you state.approve(item)/reject(item) then resume with run(agent, state). RunState
-// serializes (state.toString() / RunState.fromString(agent, s)) — that's the durability:
-// park the serialized state agent-side on `route`, resume on Decidio's approval.
-//
-//   const state = result.state;                       // or RunState from the run
-//   const { resolved, pending } = await gateInterruptions(config, state, describe);
-//   if (pending.length) { await store.put(decisionId, state.toString()); return; }  // suspend
-//   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);
-//
-// Duck-typed on the state/item (no hard @openai/agents import) so it stays thin.
 import { gateAuthorize } from "./_gate.js";
-/** Ask Decidio for each pending tool-approval on a RunState.
- *  proceed → state.approve(item); block → state.reject(item); route → pending (a human
- *  decides via Decidio; the host parks state.toString() + resumes via applyResume). */
 export async function gateInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
@@ -36,7 +17,6 @@ export async function gateInterruptions(config, state, describe) {
     }
     return { resolved, pending };
 }
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
 export function applyResume(state, item, verdict) {
     if (verdict === "approved" || verdict === "auto_approved")
         state.approve(item);

package/dist/adapters/temporal.d.ts

@@ -1,7 +1,6 @@
 import { type GuardConfig, type ApprovalContext } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 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. */
 export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;

package/dist/adapters/temporal.js

@@ -1,19 +1,7 @@
-// @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
-// Decidio resume signal. Strongest durability (the workflow survives worker restarts for
-// days); the agent's action runs on resume. Requires @temporalio/workflow (optional peer).
-//
-// Inside your workflow:
-//   const verdicts = installDecidioSignal();                 // wires the resume signal
-//   const out = await decidioGate(config, ctx, () => createOpp(o), verdicts, {
-//     authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities
-//     confirm:   (id, r) => executeActivity(confirmActivity, ...),
-//   });
-// Decidio's webhook bridges to: handle.signal(decidioResumeSignal, decisionId, verdict, reason)
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
-/** Call inside the workflow to wire the resume signal; returns the verdict store. */
 export function installDecidioSignal() {
     const verdicts = new Map();
     setHandler(decidioResumeSignal, (decisionId, verdict, reason) => { verdicts.set(decisionId, { verdict, reason }); });
@@ -24,7 +12,7 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        await condition(() => verdicts.has(auth.decisionId)); // durable wait on the signal
+        await condition(() => verdicts.has(auth.decisionId));
         const v = verdicts.get(auth.decisionId);
         assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
     }