@decidio/sdk 0.1.6 → 0.1.8

package/README.md

@@ -11,22 +11,29 @@ npx @decidio/sdk quickstart
 One command, guided: it registers a fresh agent (key generated locally), gates a demo action
 with the same one line you'll use on your real function, routes it to a human — **you** — lets
 you approve right there (or from your Decidio app), executes on approval, then downloads the
-sealed Authority Receipt and verifies it offline in front of you. Sign in when prompted, or
-export `DECIDIO_SESSION_TOKEN` for headless terminals. No config: with no `DECIDIO_API_URL` set
-it targets the hosted synthetic sandbox.
+sealed Authority Receipt and verifies it offline in front of you, pinned to your workspace's
+issuer. It mints a **7-day** tour token (`init` mints 90-day tokens — different jobs, different
+lifetimes) and ends by offering to clean itself up (`quickstart cleanup` works later too).
+Sign in when prompted. No config: with no `DECIDIO_API_URL` set it targets the hosted synthetic
+sandbox. Headless, the tour **stops at the routed decision** — approving is a human act, so it
+prints the approve command and exits rather than approve its own request (CI can pass
+`--auto-approve-demo`, which labels that authority as automated).
 
 ## Quickstart — seven steps to your first sealed receipt
 
 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).
+synthetic data, safe to experiment in). 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.
 
 **PowerShell users** — the equivalents for every Bash idiom used below:
 
 ```powershell
 mkdir decidio-quickstart; cd decidio-quickstart          # instead of mkdir ... && cd ...
 $env:DECIDIO_API_URL = "https://decidio-api.onrender.com" # instead of export NAME=value
-$env:DECIDIO_SOURCE_SYSTEM = "salesforce"; npx @decidio/sdk init my-sf-agent
+$env:DECIDIO_AGENT_ID = "my-agent"; npx @decidio/sdk init
                                                           # instead of VAR=value npx ... (inline env)
 ```
 
@@ -37,13 +44,15 @@ mkdir decidio-quickstart && cd decidio-quickstart
 npm install @decidio/sdk
 ```
 
-**2. Point at your Decidio and register your agent**
+**2. Register your agent**
 
 ```bash
-export DECIDIO_API_URL=https://decidio-api.onrender.com   # the hosted sandbox
 npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: collision-proof
 ```
 
+Every CLI command talks to the hosted sandbox by default and announces its target host on
+stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
+
 `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`.
@@ -51,7 +60,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
@@ -88,11 +98,9 @@ node --env-file=.env quickstart.mjs
 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
-identity proof, so even this $86k example would proceed there.)
+outright — no human can approve a blocked request. Policy `proceed` rules — named auto-approve
+for requests carrying the agent's signed identity proof — are configured per workspace by its
+owner.) The script prints the decision id and waits.
 
 **5. Approve it** — in a second terminal (same directory; replace `<decisionId>` with the id
 step 4 printed — angle brackets are placeholders, never typed literally). Approvals are a
@@ -122,8 +130,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
@@ -136,6 +149,10 @@ The server caps the evidence at the weaker `agent_asserted`, and the SDK warns a
 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
+action, amount limits, policy, agent and issuer identifiers, and the decision reason. Share it
+with auditors and counterparties deliberately, the way you would any business record.
+
 **7. Prove a replay is rejected:**
 
 ```bash
@@ -168,15 +185,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:
@@ -198,6 +236,12 @@ your action succeeds but the process dies *before* the entry is cleared, the cla
 (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
@@ -227,13 +271,19 @@ 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)
+- `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)
+- `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.
+
 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
 API token, its locally-generated private signing key, and a webhook secret (used only in