@decidio/sdk 0.1.8 → 0.1.9

package/README.md

@@ -23,7 +23,10 @@ prints the approve command and exits rather than approve its own request (CI can
 
 Under 30 minutes, no help needed. You'll need Node 20.6+, a terminal, and a Decidio workspace
 (request one at [decidioai.com](https://decidioai.com/#early-access) — the hosted sandbox is
-synthetic data, safe to experiment in). Lab workspaces have a **governed-action allowance**
+synthetic data, safe to experiment in — and it is ONE SHARED workspace: workspace-wide views
+like `tokens list` or `approvals` show every lab member's agents and decisions there, which is
+the shared-lab boundary working as designed; production workspaces are per-tenant). Lab
+workspaces have a **governed-action allowance**
 (currently 30 actions/hour); hitting it raises a typed `DecidioRateLimitError` naming the limit
 and reset time — nothing is routed or executed — and `tokens list` shows your remaining
 allowance any time.
@@ -56,7 +59,9 @@ stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another De
 `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** (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.
+Every later command reads `.env` from this directory automatically. Re-running init for an
+agent that already has a token REPLACES it — the server keeps one active token per agent, so
+the previous one is revoked and init says so.
 
 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
@@ -133,7 +138,10 @@ evidence is yours, not ours. To also prove *who* issued it, pin your workspace's
 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
+One receipt proves itself. Pass several files and their **ordering** is verified too — in
+**seal order** (each receipt's `prevHash` links to its predecessor's `contentHash`), which is
+the order decisions were *sealed*, not the order of their displayed decision numbers (two
+decisions created together can seal in either order). 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.
@@ -144,9 +152,12 @@ why the credential's own `confirmation.status` field reads `"pending"` forever.
 evidence that arrives *after* the seal (your function's captured result) lives on the
 **record**, not inside the credential bytes: the `receipt` command prints the record's current
 tier next to the file, and with the signing key `init` wrote you'll see `application_confirmed`
-— the wrapper's report was cryptographically bound to your agent. (No signing key configured?
-The server caps the evidence at the weaker `agent_asserted`, and the SDK warns at confirm
-time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
+— the wrapper's report carried a signed identity proof bound to your agent, this decision, and
+a freshness window. Precisely: the proof authenticates WHO is confirming WHAT decision — it
+does not yet sign the captured response bytes themselves (that binding is on the receipt-v2
+roadmap), so treat the tier as proven reporter identity, not a cryptographic hash of the
+result. (No signing key configured? The server caps the evidence at the weaker
+`agent_asserted`, and the SDK warns at confirm time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
 later facts supersede, they never rewrite.
 
 One sharing note: a receipt is **not a secret, but it is not metadata-free** — it names the
@@ -162,7 +173,9 @@ npx @decidio/sdk approvals approve <the same decisionId>
 Decisions are single-use: the CLI reports "already resolved — nothing changed" and exits
 non-zero. The server answers replays idempotently — a second approve can never re-execute the
 action. (The durable resume path has the same property: parked actions are claimed exactly
-once, and its webhook handler fails closed without a verified signature.)
+once, and its webhook handler fails closed without a verified signature — unless you
+explicitly set `allowUnsigned: true`, which removes webhook authenticity and makes the
+controller say so loudly at startup; never use it on an internet-reachable endpoint.)
 
 That's the whole contract: gate → human decision → your execution → owned, verifiable evidence.
 
@@ -230,6 +243,13 @@ 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.
 
+**The supported argument data model is plain JSON**: `null`, booleans, strings, finite
+numbers, arrays, and plain objects. Anything that cannot survive JSON with its meaning intact
+— `NaN`/`Infinity`, `undefined`, `BigInt`, `Map`/`Set`/`Date`, class instances, functions,
+circular structures — is **refused before the decision is routed or the payload signed**
+(typed error naming the offending path), because a value that silently drifts in serialization
+would mean a human approves one thing and your function executes another.
+
 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
@@ -275,14 +295,15 @@ imports none of them. Each adapter's shipped `.d.ts` header documents its wiring
 - `doctor` — config, connectivity, and what your current token can do
 - `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). Unknown flags are refused, never ignored.
-- `tokens list` / `tokens revoke <jti>` — see and kill agent tokens (values are never re-shown; the jti is the revocation handle). Each row carries its status — `active`, `expired`, or `REVOKED <date>` — so the list confirms the revocations it performs; re-revoking is an honest no-op (exit 1)
+- `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 — the sdk's embedded copy is pinned to the previous release, so message wording may trail it one version; verdicts and semantics are conformance-locked identical). Unknown flags are refused, never ignored. Fully offline AND fully decoupled: it touches no network and reads no `.env` — a receipt verifies identically from an empty directory.
+- `tokens list [--mine]` / `tokens revoke <jti>` — see and kill agent tokens (values are never re-shown; the jti is the revocation handle). Each row carries its status — `active`, `expired`, or `REVOKED <date>` — so the list confirms the revocations it performs; re-revoking is an honest no-op (exit 1). The list is workspace-wide (a shared workspace shows every member's agents); `--mine` narrows to this directory's agent
 - `quickstart cleanup` — revoke the tour's token and delete its local credentials. What stays, honestly: sealed records (permanent by design) and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap)
 - `dev [--target URL]` — local relay for the resume webhook (operator setups)
 
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
-pure JSON); errors, usage guidance, and the per-run target-host announcement go to **stderr**.
-Exit codes: 0 success · 1 failure or honest no-op · 2 usage error.
+pure JSON); errors, usage shown on *error* paths, and the per-run target-host announcement go
+to **stderr**. Asked-for help (an explicit `--help`, or invoking the bare CLI) is itself a
+result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error.
 
 Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**
 sign-in held in memory for that run. What lands on disk in `.env`: the agent's floor-limited
@@ -297,7 +318,8 @@ manager for production.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
 - `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); the decision stays open in Decidio, nothing executed locally.
 
-Every error carries the `decisionId`, so a suspended or timed-out action is always findable in
+Every error raised after a decision exists carries the `decisionId`, so a suspended or
+timed-out action is always findable in
 your queue.
 
 ## Notes

package/dist/adapters/_gate.d.ts

@@ -7,5 +7,7 @@ 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,7 +1,19 @@
-import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm } from "../index.js";
+// 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, assertJsonSafe, assertConfirmRecorded } from "../index.js";
 export async function gateAuthorize(config, ctx) {
+    // SAME JSON-safety gate as the core wrapper (guard equivalent-path catch: the adapter door
+    // skipped it, and the server's amount coercion turns a drifted NaN→null into a $0 request —
+    // a human would approve an amount that meant something else entirely).
+    assertJsonSafe(ctx, "describe(...)");
     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;
@@ -21,7 +33,10 @@ 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", {
@@ -29,16 +44,24 @@ 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 } : {}) }),
         });
-        if (!res.ok)
+        // 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)`);
+            return;
+        }
+        // The ONE confirm-body rule, on this door too (guard equivalent-path catch).
+        assertConfirmRecorded(await res.json().catch(() => null), decisionId, !!requesterIdentity);
     }
     catch (e) {
         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,6 +1,19 @@
 import { Command } from "@langchain/langgraph";
 import { type GuardConfig, type ApprovalContext } from "../index.js";
+/**
+ * @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).
+ *
+ * (This wiring doc ships in the .d.ts — the README points here.)
+ */
+/** 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,11 +1,23 @@
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
+/**
+ * @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).
+ *
+ * (This wiring doc ships in the .d.ts — the README points here.)
+ */
+/** 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);
     }
@@ -13,6 +25,8 @@ 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

@@ -5,6 +5,26 @@ interface RunStateLike {
     approve(item: ToolApprovalItem): void;
     reject(item: ToolApprovalItem): void;
 }
+/**
+ * @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.
+ *
+ * (This wiring doc ships in the .d.ts — the README points here.)
+ */
 export interface Resolved {
     item: ToolApprovalItem;
     verdict: "approved" | "blocked";
@@ -14,9 +34,13 @@ 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,4 +1,7 @@
 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 = [];
@@ -17,6 +20,7 @@ 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,6 +1,22 @@
 import { type GuardConfig, type ApprovalContext } from "../index.js";
 import { type GateAuth } from "./_gate.js";
+/**
+ * @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)
+ *
+ * (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. */
 export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;

package/dist/adapters/temporal.js

@@ -1,7 +1,23 @@
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
+/**
+ * @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)
+ *
+ * (This wiring doc ships in the .d.ts — the README points here.)
+ */
 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 }); });
@@ -12,7 +28,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));
+        await condition(() => verdicts.has(auth.decisionId)); // durable wait on the signal
         const v = verdicts.get(auth.decisionId);
         assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
     }