@decidio/sdk 0.1.8 → 0.1.10

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
@@ -121,11 +126,14 @@ becomes the record's execution evidence.
 
 ```bash
 npx @decidio/sdk receipt <decisionId>
-npx @decidio/sdk verify decidio-receipt-<decisionId>.json
+npx @decidio/sdk verify --issuer <did:key:...> decidio-receipt-<decisionId>.json
 ```
 
-The download is an authenticated fetch from your workspace; the *verification* is fully
-offline — the verifier ships inside this package (no second download, no registry probe, same
+Lead with the pin: `--issuer` binds the check to YOUR workspace's DID (the `receipt` command
+prints it from the authenticated response, so it is already on your screen). An UNPINNED
+`verify` proves internal consistency only — any keyholder could have issued such a file — and
+says so; pinned verification proves *who*. The download is an authenticated fetch from your
+workspace; the *verification* is fully offline — the verifier ships inside this package (no second download, no registry probe, same
 implementation as the standalone `@decidio/verify`). The receipt is a W3C Verifiable
 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:
@@ -133,7 +141,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 +155,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 +176,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 +246,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
@@ -258,7 +281,9 @@ 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. Each adapter's shipped `.d.ts` header documents its wiring; `npx
+imports none of them — install the engine you use alongside the SDK (`npm i inngest`,
+`@langchain/langgraph`, `@temporalio/workflow`, or `@openai/agents`); nothing is downloaded
+for engines you don't. 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
@@ -275,14 +300,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 +323,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,5 +1,7 @@
-import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm, assertJsonSafe, assertConfirmRecorded, assertSafeTransport } from "../index.js";
 export async function gateAuthorize(config, ctx) {
+    assertJsonSafe(ctx, "describe(...)");
+    assertSafeTransport(config.apiUrl, !!config.apiToken);
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
     const requesterIdentity = (config.agentKey && config.agentDid)
@@ -20,6 +22,13 @@ export async function gateAuthorize(config, ctx) {
 }
 export async function gateConfirm(config, decisionId, result) {
     const f = config.fetchImpl ?? fetch;
+    try {
+        assertSafeTransport(config.apiUrl, !!config.apiToken);
+    }
+    catch (e) {
+        console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
+        return;
+    }
     try {
         const requesterIdentity = signConfirm(decisionId, config);
         if (!requesterIdentity)
@@ -29,8 +38,11 @@ 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)
+        if (!res.ok) {
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
+            return;
+        }
+        assertConfirmRecorded(await res.json().catch(() => null), decisionId, !!requesterIdentity);
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);

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/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/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;