@decidio/sdk 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # @decidio/sdk
 
-One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every outcome.
+One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every decision, with execution evidence accruing on the record.
 
 ## The two-minute tour
 
@@ -41,13 +41,12 @@ npm install @decidio/sdk
 
 ```bash
 export DECIDIO_API_URL=https://decidio-api.onrender.com   # the hosted sandbox
-npx @decidio/sdk init my-agent
+npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: collision-proof
 ```
 
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
 workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
-is sent), registers the agent, mints its **floor-limited API token** (it can request approvals
-and nothing else — your workspace session never touches the agent's disk), and writes `.env`.
+is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
 Every later command reads `.env` from this directory automatically.
 
 What `.env` contains after a successful init: `DECIDIO_API_URL`, `DECIDIO_AGENT_ID`,
@@ -86,9 +85,10 @@ console.log("executed after approval:", result);
 node --env-file=.env quickstart.mjs
 ```
 
-A brand-new agent matches **no** auto-approve rule, so Decidio's deny-by-default **routes every
-request to a human** — that is the point: nothing executes without either a named policy rule or
-a person. The script prints the decision id and waits. (To later see a policy `proceed`,
+A brand-new agent matches **no** auto-approve rule, so Decidio **routes every request to a
+human by default** — that is the point: nothing executes without either a named policy rule or
+a person. (Routing-by-default is distinct from a policy **block**, which refuses the action
+outright — no human can approve a blocked request.) The script prints the decision id and waits. (To later see a policy `proceed`,
 register a **new** agent in the sandbox's pre-policied lane — an existing agent's lane can't be
 changed: `DECIDIO_SOURCE_SYSTEM=salesforce npx @decidio/sdk init my-sf-agent`. That lane's
 named rule auto-approves amounts under $1M when the request carries the agent's signed
@@ -192,8 +192,21 @@ 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.
+
+**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
 
@@ -201,8 +214,8 @@ If your agent runs on Inngest/Temporal/LangGraph, the engine *is* the durable st
 `@decidio/sdk/inngest` maps the gate onto `step.waitForEvent`; `@decidio/sdk/langgraph` is a
 drop-in via `interrupt()`; `@decidio/sdk/temporal` uses `condition` + signal;
 `@decidio/sdk/openai` gates RunState approvals. All optional peer dependencies — the core SDK
-imports none of them. See each adapter's header for its wiring, and `example/` in the repo for
-runnable end-to-ends.
+imports none of them. Each adapter's shipped `.d.ts` header documents its wiring; `npx
+@decidio/sdk quickstart` is the fastest runnable end-to-end.
 
 ## One surface, every runtime — and Python too
 
@@ -213,10 +226,12 @@ runnable end-to-ends.
 
 `npx @decidio/sdk <cmd>`:
 
-- `init [agentId]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries)
+- `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
+- `init [agentId] [--unique]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries)
 - `doctor` — config, connectivity, and what your current token can do
 - `approvals` / `approvals approve|reject <id> [reason]` — the human side, from your terminal
 - `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)
 
 Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**

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);
     }