@codespar/cli 0.17.0 → 0.18.0

package/README.md

@@ -156,6 +156,7 @@ one-line description per template.
 | `multi-tenant` | Next.js + OpenAI — one API key, N tenants |
 <!-- kit-templates:start -->
 | `bills-agent` | Starter kit — The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt. |
+| `checkout-agent` | Starter kit — The merchant's agent that sells in the conversation: the customer builds a cart the code prices, the attendant (or the sales policy) confirms the order, one bolepix is issued with an idempotency key, the QR and the copy-and-paste go to the customer, and the order closes on commerce.charge.paid. |
 | `collections-agent` | Starter kit — The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired. |
 | `hello-agent` | Starter kit — The worked example of the codespar-agent-builder skill: a read-only agent that reads the month's bills and cannot pay. Built from the five files, the packs and one kit module. |
 | `supplier-payments-agent` | Starter kit — A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codespar/cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "CodeSpar CLI. The agentic OS for money movement in Latin America, from your terminal: authenticate, browse servers, mint mandates, execute tools, manage sessions, stream logs.",
   "type": "module",
   "bin": {

package/templates/bills-agent/README.md

@@ -1,7 +1,7 @@
 # {{name}}
 
 Scaffolded by `codespar init --template bills-agent` from the `bills-agent` starter kit
-(https://github.com/codespar/agent-starter-kits at `8f130b7cdc30510c929e6f7ebb07184f763e6ce4`, agent 0.1.0).
+(https://github.com/codespar/agent-starter-kits at `b766575306a71c9135c0d70e23d591e6523dc2f8`, agent 0.1.0).
 
 The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt.
 

package/templates/bills-agent/agents/bills-agent/AGENTS.md

@@ -10,7 +10,7 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 6. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
 7. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
 8. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
-9. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+9. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key: what reaches a third party is its hash, sealed into a v4 receipt, which proves what was approved and never who. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
 10. **No telemetry.** Nothing in this repository phones home.
 
 `AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.

package/templates/bills-agent/agents/bills-agent/CLAUDE.md

@@ -10,7 +10,7 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 6. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
 7. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
 8. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
-9. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+9. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key: what reaches a third party is its hash, sealed into a v4 receipt, which proves what was approved and never who. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
 10. **No telemetry.** Nothing in this repository phones home.
 
 `AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.

package/templates/bills-agent/agents/bills-agent/README.md

@@ -70,7 +70,7 @@ Not in this kit yet: WhatsApp, batch payouts.
 | `npm run resume` | After a crash: dispatches only what the outbox proves was never sent, reconciles the rest from the rail, expires what went stale. Never pays twice. |
 | `npm run rerun <run-id>` | Replays a recorded run with no network and checks the state sequence matches. |
 | `npm run inspect <run-id> [--json] [--html <file>]` | The proof bundle of that run read back as a timeline: who proposed what, who approved it and when (with the `items_hash` and the escalation trigger when one fired), under which version of the mandate, every state transition with its actor, which call went out under which idempotency key, what the rail answered, and which receipts came back. `--json` puts the whole report on stdout and nothing else; `--html` writes one self-contained page that opens from disk with nothing fetched. Payees are masked the way the bundle masks them, and the conversation is reported as counts, not text. |
-| `npm run verify -- <receipt-file> [--json] [--keys <file>] [--url <url>]` | Checks a receipt's Ed25519 signature against CodeSpar's published key set. No key and no agent needed: it runs on a receipt file copied to another machine. The exit code is the verdict — 0 verified, 1 tampered, 3 unsigned, 4 unknown key, 5 the key set could not be read, 6 not a receipt. |
+| `npm run verify -- <receipt-file> [--json] [--keys <file>] [--url <url>] [--approval <file>] [--from-api]` | Checks a receipt's Ed25519 signature against CodeSpar's published key set, then recomputes its chain from the API's receipt read under the published recipe, then holds the sealed approval hashes against the approval artifact. The read needs no key and no agent; a run's masked copy proves the signature only, unless `--from-api` reads the receipt with this agent's key (nothing is written). The exit code is the verdict — 0 verified, 1 tampered, 3 unsigned, 4 unknown key, 5 the key set could not be read, 6 not a receipt, 7 signature only (the body was not bound), 8 the body is not the sealed one, 9 the sealed approval is not the artifact's. |
 | `npm run reconcile` | Compares local state with the rail. Closes an `executing` execution only from a recorded rail outcome; what the rail has not answered yet stays `executing` with an `execution.uncertain` event, for a human. Never dispatches. |
 | `npm run consent -- --yes` | Runs a new consent for a mandate (test key, partner surface); without `--yes` it asks at the keyboard. The signed envelope is stored in `.codespar/mandate.json`, mode 0600. The first thing to run after `.env`: `npm start -- --input` needs it. |
 
@@ -91,7 +91,7 @@ transcript.jsonl        the conversation and the tool calls
 approval.json           the approval artifacts of the run (section 4.2 of the spec)
 mandate.snapshot.json   the mandate as it was, keys masked
 events.jsonl            every transition and every rail event, each with its actor
-receipts/               the receipts the rail returned, each stamped with the actor
+receipts/               the receipts the rail returned, each stamped with the actor; the payee is the one the receipt sealed
 run.json                mode, rail, mandate id and the version it ran under
 ```
 
@@ -111,14 +111,15 @@ The receipt copies carry both of the API's seals. `receipt_sig` is the HMAC, whi
 npm run verify -- runs/<run-id>/receipts/<receipt-id>.json
 ```
 
-That reads the public key set from `/.well-known/codespar-receipt-keys.json`, picks the key the receipt names, rebuilds `codespar-receipt:v1:<receipt_id>:<chain>` and checks it with stock `node:crypto` — no key, no API key, no CodeSpar call that could be refused. `--keys <file>` uses a saved copy of the key set instead and touches no network at all; `--json` puts the verdict on stdout. `--url` names another deployment's key set: the default is production, and every deployment publishes its own key under the same `kid`, so a sandbox receipt checked against the production keys reads `tampered`. The signature covers the receipt id and the chain, so the masking above does not disturb it, and the file verifies on a machine that has never seen this repository. A receipt sealed before the API had the capability answers `unsigned`, which is not a failure: it has no Ed25519 signature and never will, and its HMAC seal is unaffected.
+That reads the public key set from `/.well-known/codespar-receipt-keys.json`, picks the key the receipt names, rebuilds `codespar-receipt:v1:<receipt_id>:<chain>` and checks it with stock `node:crypto` — no key, no API key, no CodeSpar call that could be refused. `--keys <file>` uses a saved copy of the key set instead and touches no network at all; `--json` puts the verdict on stdout. `--url` names another deployment's key set: the default is production. The signature covers the receipt id and the chain, so the masking above does not disturb it, and the file verifies on a machine that has never seen this repository; on its own the copy answers `signature_only`, because it masks the payee the chain sealed. `npm run verify -- runs/<run-id>/receipts/<receipt-id>.json --from-api` reads the unmasked receipt from the API with this agent's key, recomputes the chain from it, and holds its sealed approval hashes against the artifact the copy names in `approval.json`: `verified` then means this payment was made against the list that artifact approved. Nothing unmasked is written. A receipt sealed before the API had the capability answers `unsigned`, which is not a failure: it has no Ed25519 signature and never will, and its HMAC seal is unaffected. A receipt sealed before chain v4 answers `signature_only`: its chain seals the mandate's own signature, which the verifier does not take. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §47.
 
 
 ## Limits and stubs
 
 - The receipt carries two signatures. The HMAC one, under the consumer secret CodeSpar holds, proves the payment to whoever runs this agent, because verifying it means holding the key that also mints it. The Ed25519 one, sealed by CodeSpar's platform issuer key since the API added it, proves it to anybody with `npm run verify`. A receipt sealed before that carries no Ed25519 signature and never will — there is no backfill, and signing an old receipt with today's key would attest to what the database says now, not to what happened then.
-- The approval artifact is signed by HMAC with a **local development key** (`.codespar/approval.key`). This is a stub: the CodeSpar API does not sign approval lists today. It proves what was approved to whoever runs the agent.
-- Revocation is checked against the API. With a test key, the core reads `GET /v1/mandates/{id}` before every `executing` and executes on `status: active` only: `paused` → `denied` (`mandate_paused`), `revoked` → `denied` (`mandate_revoked`), `expired` → `expired`, and a read that does not answer (timeout, 5xx, 404, an unreadable body) → `denied` (`mandate_status_unavailable`), never "assume active". `npx -y @codespar/cli@0.14.0 mandate revoke <id>` is the switch. Without a key (the CI, the scenarios, `rerun`) the same check answers from a **local stub** (`packages/agent-core/src/stubs/mandate-status.ts`), which is also where the organization kill switch (`org pauseAll`) lives, since the API does not expose one yet.
+- The receipt names the payee because every spend presents the approved payment as a `quote`; without one the API seals no payee anywhere in the chain. The API only records a quote that disagrees with what settled and pays anyway, so the kit refuses the disagreement before the call, and a receipt that seals a different payee, or none, stops the run with `ReceiptSealMismatchError` instead of a warning. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §18.
+- The approval artifact is signed by HMAC with a **local development key** (`.codespar/approval.key`). This is a stub: the CodeSpar API does not sign approval lists today, so WHO approved is proved to whoever runs the agent and nobody else. WHAT was approved reaches further: every spend carries the artifact's `items_hash` (and a batch line its `batch_hash`), the API seals them into the receipt's chain (v4), and `npm run verify` holds that sealed link against the artifact. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §3.
+- Revocation is checked against the API. With a test key, the core reads `GET /v1/mandates/{id}` before every `executing` and executes on `status: active` only: `paused` → `denied` (`mandate_paused`), `revoked` → `denied` (`mandate_revoked`), `expired` → `expired`, and a read that does not answer (timeout, 5xx, 404, an unreadable body) → `denied` (`mandate_status_unavailable`), never "assume active". `npx -y @codespar/cli@0.14.0 mandate revoke <id>` is the switch. The same read carries the organization kill switch (ent#1648): `org_paused: true` → `denied` (`org_paused`) whatever `status` says, and a read without `org_paused` is `mandate_status_unavailable`, never "assume running". If the switch is pressed after the read, the API refuses the spend itself with 403 `org_paused` and the execution closes `failed` (`org_paused`); nothing moved. The kit never resumes an organization: that is a dashboard action by a verified admin. Without a key (the CI, the scenarios, `rerun`) the same check answers from a **local stub** (`packages/agent-core/src/stubs/mandate-status.ts`), where `pauseAll` stands in for the switch.
 - The `actor` of every call is carried locally on every event, approval and receipt copy. The API has no `actor` field on the wire today; the spend carries `agent_id`, which the mandate binds.
 - A `consumer_id` with an approved account does not leave the registry. Synthetic onboarding stops at document verification, which is the correct behaviour.
 - CodeSpar does not host or run this agent. The repository delivers it; whoever runs it, runs it.

package/templates/bills-agent/agents/bills-agent/src/modules/embedded-consent.ts

@@ -72,7 +72,7 @@ export async function runEmbeddedConsent(options: ConsentOptions): Promise<Manda
 
   // The consumer's "browser" is this terminal: the submit is the same call the hosted page makes,
   // plus the attestation the partner surface requires. Sandbox rails accept a placeholder token.
-  const submitted = (await api.request("post", "/v1/consents/{token}/submit" as never, {
+  const submitted = await api.post("/v1/consents/{token}/submit", {
     path: { token: init.token },
     body: {
       consumer_id: consumerId,
@@ -81,9 +81,10 @@ export async function runEmbeddedConsent(options: ConsentOptions): Promise<Manda
       display_label: "bills-agent (sandbox)",
       attestation: { method: "in_person", asserted_at: Math.floor(now().getTime() / 1000), reference: "terminal" },
     },
-  } as never)) as { mandate_id: string; mandate: Record<string, unknown>; signature: string };
+  });
 
   const signed = submitted.mandate;
+  const allowlist = signed["merchant_allowlist"];
   const mandate = MandateSchema.parse({
     id: submitted.mandate_id,
     version: 1,
@@ -95,8 +96,8 @@ export async function runEmbeddedConsent(options: ConsentOptions): Promise<Manda
     per_tx_cap_minor: Number(signed["per_tx_cap_minor"]),
     ...(signed["periodic_cap"] ? { periodic_cap: signed["periodic_cap"] } : {}),
     merchant_pin_kind: String(signed["merchant_pin_kind"]),
-    merchant_allowlist: signed["merchant_allowlist"],
-    beneficiaries: example.beneficiaries.filter((b) => (signed["merchant_allowlist"] as string[]).includes(b.payee)),
+    merchant_allowlist: allowlist,
+    beneficiaries: example.beneficiaries.filter((b) => Array.isArray(allowlist) && allowlist.includes(b.payee)),
     status: "active",
     expires_at: new Date(Number(signed["expires_at"]) * 1000).toISOString(),
     signature: submitted.signature,

package/templates/bills-agent/packages/agent-core/README.md

@@ -12,10 +12,23 @@ This package is the decisions. The RUNNER around them — the terminal channel,
 
 `ExecutionEngine.policy()` runs at draft, at a human's approval and again immediately before `executing`, inside the transaction that writes the outbox row. Mandate status, allowlist, per-transaction cap, the window cap (counting settled, in flight AND awaiting executions as reservations), `escalate_above` and the artifact's `items_hash` are all re-checked at the last gate. A person's approval satisfies `escalate_above` and nothing else.
 
+## What the artifact binds besides the items
+
+`items_hash` covers the execution's items: payee, amount, currency and a receivable's due date. Two optional bindings cover what those fields cannot see, and each is **omitted, never null**, when it does not apply, so an artifact without them signs the same bytes it signed before they existed (`test/composition.test.ts` pins that against an artifact hashed on `main` before `composition` was added):
+
+- `batch` — the set a line was approved inside (`batch_hash` over the ordered lines, the line's `index`, the `count`). One execution per line, N lines.
+- `composition` — what ONE amount is made of (`{ ref, composition_hash, line_count }`, with `compositionHash` over the resolved lines). One execution, N lines behind it: a sale is one charge, so a cart of three lines is one item whose amount is the order's total. Two units at 100 and one unit at 200 are the same item and the same `items_hash`; they are not the same `composition_hash`. `compositionHash` uses `itemsHash`'s canonicalisation over `ref`, `quantity`, `unit_amount`, `amount` and `currency`, not `itemsHash` itself, because ten units at a 10% discount and nine at list price have the same line amount.
+
+`checkApprovalArtifact` compares both, and the last gate sends a mismatch back to `awaiting_approval` with `items_hash_mismatch`, like a changed list. `ExecutionEngine.restate()` is how an OPEN execution (`awaiting_approval`, `approved`) follows the proposal behind it — a customer who changes the cart after the order was approved — without a transition: items, total, `items_hash` and composition are replaced, the state, the artifact and the idempotency key are kept, and the last gate does the refusing. The payees of a restatement cannot change.
+
+## What of the artifact reaches the receipt
+
+Every spend carries `approval: { items_hash, batch_hash? }`, the artifact's own hashes (`spendApprovalOf`), and the API seals them into the receipt's chain as a link of their own (chain v4, ent#1670). Both rails refuse a spend without them before any call. `composition` is not sent: the API takes the two hashes and nothing else, and only charges carry a composition today. `receipt-chain.ts` recomputes a chain from the receipt read under the `chain_recipe` the key document publishes (RFC 8785 implemented locally, `node:crypto` only), and `verifyReceiptRead` holds the signature, the body and the sealed approval link against the artifact, in that order. It proves WHAT was approved to anybody holding the read; WHO approved stays in the artifact, under the local key. `docs/OPEN_QUESTIONS.md` §3 and §47.
+
 ## Reconcile never re-dispatches
 
 An execution left in `executing` is looked up on the rail, attempt by attempt. A recorded settled or failed outcome closes it; `in_flight`, `uncertain` or unknown leaves it in `executing` with `reason: rail_uncertain` for a human. The single exception is an outbox row still `pending` (the state changed, no call was ever made): those attempts go out once, under the same ids.
 
 ## Stubs
 
-`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, and a read that does not answer is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.
+`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, `org_paused: true` (the organization kill switch, ent#1648) refuses it whatever `status` says, and a read that does not answer, or answers without `org_paused`, is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.

package/templates/bills-agent/packages/agent-core/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.128.0",
-    "@codespar/sdk": "0.16.6",
+    "@codespar/sdk": "0.16.10",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   }

package/templates/bills-agent/packages/agent-core/src/agent.ts

@@ -16,6 +16,42 @@ export interface ToolContext {
   engine: ExecutionEngine;
   /** Fires when a payment tool created an execution; the channel decides what to do with it (ask, or run). */
   onExecution: (execution: Execution) => Promise<Execution>;
+  /**
+   * Fires ONCE for a batch, before its first line is drafted, when the channel
+   * can take one gesture for the whole list. Absent on a channel that decides
+   * line by line (the one-shot, the scenario runner), and then nothing changes:
+   * each line reaches `onExecution` and is decided there. The gesture never
+   * approves anything itself; every line is still drafted, still reaches
+   * `onExecution`, and still mints its own artifact.
+   */
+  onBatch?: (batch: BatchPresentation) => Promise<BatchGesture | undefined>;
+}
+
+/** What a person sees when a whole batch is put in front of them: the list, its total, and the hash of the list. */
+export interface BatchPresentation {
+  ref: string;
+  label: string;
+  /** `batchHash` of the ordered lines. The gesture is a decision about THIS hash and no other. */
+  batch_hash: string;
+  count: number;
+  total_minor: number;
+  /** The total as the kit writes money. */
+  total: string;
+  lines: Array<{
+    index: number;
+    beneficiary: string;
+    amount_minor: number;
+    amount: string;
+    /** A line a previous run already covers is shown, and does not run again whatever the gesture says. */
+    status: "open" | "already_settled" | "in_progress" | "attempt_id_conflict";
+  }>;
+}
+
+/** The decision a person took on a presented batch: which positions they approved and which they vetoed. */
+export interface BatchGesture {
+  batch_hash: string;
+  approved: number[];
+  vetoed: number[];
 }
 
 export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
@@ -28,6 +64,7 @@ export interface AgentLoopOptions {
   bundle: ProofBundle;
   engine: ExecutionEngine;
   onExecution: ToolContext["onExecution"];
+  onBatch?: ToolContext["onBatch"] | undefined;
   /** A hard stop on tool round-trips per turn, so a looping model cannot run forever. */
   maxSteps?: number;
   clock?: () => Date;
@@ -91,7 +128,7 @@ export class AgentLoop {
   }
 
   private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
-    const { bundle, handlers, engine, onExecution } = this.options;
+    const { bundle, handlers, engine, onExecution, onBatch } = this.options;
     bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
 
     if (!this.allowed.has(call.name)) {
@@ -110,6 +147,7 @@ export class AgentLoop {
           executions.push(settledOrNot);
           return settledOrNot;
         },
+        ...(onBatch ? { onBatch } : {}),
       });
       return { refused: false, content };
     } catch (err) {

package/templates/bills-agent/packages/agent-core/src/api/charge-rail.ts

@@ -19,30 +19,39 @@
  * There is no receipt object for a receivable; the paid charge as the API
  * reports it is what the bundle keeps, marked `kind: "charge"` and unsealed.
  */
-import type { ApiClient } from "@codespar/sdk";
+import type { ApiClient, ApiOperation, ApiSuccess } from "@codespar/sdk";
 import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
 import type { Actor, ChargeInstrument } from "../types.js";
-import { describeApiError, isUncertain } from "./client.js";
+import { describeApiError, isUncertain, type ApiErrorCode } from "./client.js";
 
-/** The `/v1/charges` answer, as the SDK types it. */
-export interface ChargeView {
-  id: string | null;
-  status: string;
-  local_status: string;
-  status_conflict: boolean;
-  method: string;
-  currency: string;
-  amount: number;
-  amount_minor: number;
-  due_date: string | null;
-  payable: boolean;
-  boleto_bar_code: string | null;
-  boleto_bank_line: string | null;
-  pix_copy_paste: string | null;
-  credit_correlation_armed: boolean;
-  payment_in_flight: boolean;
-  settlement: "confirmed" | "pending" | "unconfirmable" | null;
-  issuance_unconfirmed: boolean;
+/** The `/v1/charges/{chargeId}` answer, as the SDK's generated OpenAPI types it. The create answers the same shape, and the compiler holds them together. */
+export type ChargeView = ApiSuccess<ApiOperation<"/v1/charges/{chargeId}", "get">>;
+
+/**
+ * Documented as the read's 409. The create does not document it, and the
+ * create's error path below still treats it as uncertain, which is the safe
+ * reading of a code the route is not known to send (OPEN_QUESTIONS §8).
+ */
+const ISSUANCE_UNCONFIRMED: ApiErrorCode<ApiOperation<"/v1/charges/{chargeId}", "get">> = "issuance_unconfirmed";
+
+/** The read's other 409: the reference matched more than one charge. Terminal for that reference; the API answers by the charge id. */
+const REFERENCE_AMBIGUOUS: ApiErrorCode<ApiOperation<"/v1/charges/{chargeId}", "get">> = "charge_reference_ambiguous";
+
+type ChargeRead =
+  | { kind: "view"; view: ChargeView }
+  | { kind: "missing" }
+  | { kind: "in_flight" }
+  | { kind: "failed"; outcome: Extract<RailOutcome, { status: "failed" }> }
+  | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> };
+
+/**
+ * When the charge settled, if the answer says so. `settled_at` is a column of
+ * the charge row, but the SDK's type for the read does not carry it, so this
+ * is the one field here read outside the type (OPEN_QUESTIONS §8).
+ */
+function settledAt(view: ChargeView): string | undefined {
+  const value: unknown = (view as Record<string, unknown>)["settled_at"];
+  return typeof value === "string" && value !== "" ? value : undefined;
 }
 
 export function instrumentOf(view: ChargeView): ChargeInstrument {
@@ -82,7 +91,7 @@ export class CodeSparChargeRail implements PaymentRail {
     if (!payment.consumer_id) return { status: "failed", code: "consumer_id_required", message: "a receivable settles into the principal's account; the policy names no consumer_id" };
     let view: ChargeView;
     try {
-      view = (await this.api.post("/v1/charges", {
+      view = await this.api.post("/v1/charges", {
         body: {
           consumer_id: payment.consumer_id,
           amount: payment.amount_minor / 100,
@@ -93,13 +102,13 @@ export class CodeSparChargeRail implements PaymentRail {
           due_date: payment.due_date,
           idempotency_key: payment.attempt_id,
         },
-      })) as ChargeView;
+      });
     } catch (err) {
       const failure = describeApiError(err);
-      if (isUncertain(failure) || failure.code === "issuance_unconfirmed") return { status: "uncertain", code: failure.code, message: failure.message };
+      if (isUncertain(failure) || failure.code === ISSUANCE_UNCONFIRMED) return { status: "uncertain", code: failure.code, message: failure.message };
       return { status: "failed", code: failure.code, message: failure.message };
     }
-    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: "issuance_unconfirmed", message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
+    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: ISSUANCE_UNCONFIRMED, message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
     if (view.amount_minor !== payment.amount_minor) {
       // The API understood another amount than the one approved. The receivable exists; withdraw it rather than leave a debt nobody approved.
       const withdrawn = await this.withdraw(view.id);
@@ -107,7 +116,7 @@ export class CodeSparChargeRail implements PaymentRail {
     }
     const outcome = outcomeOf(view);
     // `in_flight` is excluded above (`issuance_unconfirmed` / no id); the create answers a state, never "still running".
-    return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
+    return outcome.status === "in_flight" ? { status: "uncertain", code: ISSUANCE_UNCONFIRMED, message: "the create answered no readable state" } : outcome;
   }
 
   /**
@@ -119,37 +128,48 @@ export class CodeSparChargeRail implements PaymentRail {
     const byId = transactionId ? await this.read(transactionId) : { kind: "missing" as const };
     if (byId.kind === "view") return outcomeOf(byId.view);
     if (byId.kind === "in_flight") return { status: "in_flight" };
-    if (byId.kind === "uncertain") return byId.outcome;
+    if (byId.kind === "failed" || byId.kind === "uncertain") return byId.outcome;
     const byKey = await this.read(attemptId);
     if (byKey.kind === "view") return outcomeOf(byKey.view);
     if (byKey.kind === "in_flight") return { status: "in_flight" };
-    if (byKey.kind === "uncertain") return byKey.outcome;
+    if (byKey.kind === "failed" || byKey.kind === "uncertain") return byKey.outcome;
     return undefined;
   }
 
-  private async read(chargeRef: string): Promise<{ kind: "view"; view: ChargeView } | { kind: "missing" } | { kind: "in_flight" } | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> }> {
+  /**
+   * A 409 is branched on its code, never on the status alone: only `issuance_unconfirmed` means "still issuing".
+   * `charge_reference_ambiguous` is terminal for the reference and fails explicitly instead of being polled forever,
+   * and a 409 whose code this kit does not read is a failure too.
+   */
+  private async read(chargeRef: string): Promise<ChargeRead> {
     try {
-      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } })) as ChargeView;
+      const view = await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } });
       return { kind: "view", view };
     } catch (err) {
       const failure = describeApiError(err);
       if (failure.status === 404) return { kind: "missing" };
-      if (failure.status === 409) return { kind: "in_flight" };
+      if (failure.status === 409) {
+        if (failure.code === ISSUANCE_UNCONFIRMED) return { kind: "in_flight" };
+        const message =
+          failure.code === REFERENCE_AMBIGUOUS
+            ? `the reference ${chargeRef} matches more than one charge, and the API answers for the charge id only; which one is this attempt's is not assumed, so reconcile it by the charge id`
+            : `GET /v1/charges/${chargeRef} answered 409 with a code this kit does not read (${failure.code}); it is not read as a charge still issuing`;
+        return { kind: "failed", outcome: { status: "failed", code: failure.code, message } };
+      }
       return { kind: "uncertain", outcome: { status: "uncertain", code: failure.code, message: failure.message } };
     }
   }
 
   async receipt(chargeId: string, actor: Actor): Promise<RailReceipt | undefined> {
     try {
-      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } })) as ChargeView;
-      const raw = view as ChargeView & { settled_at?: string };
+      const view = await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } });
       return {
         receipt_id: chargeId,
         kind: "charge",
         state: view.local_status === "settled" ? "paid" : view.local_status,
         mandate: { id: "n/a" },
         // The read names no buyer, so the payee is not on this record; the execution's item names the debtor.
-        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: raw.settled_at ?? new Date().toISOString() },
+        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: settledAt(view) ?? new Date().toISOString() },
         chain: null,
         receipt_sig: null,
         receipt_sig_ed25519: null,

package/templates/bills-agent/packages/agent-core/src/api/client.ts

@@ -3,7 +3,7 @@
  * the `csk_test_` prefix before the client is built, so no live key ever
  * reaches the network from this repository.
  */
-import { ApiClient, CodesparApiError, TimeoutError } from "@codespar/sdk";
+import { ApiClient, CodesparApiError, TimeoutError, type ApiOperation, type ApiResponse } from "@codespar/sdk";
 import { assertTestKey } from "../secrets.js";
 
 export const DEFAULT_BASE_URL = "https://api.codespar.dev";
@@ -32,15 +32,38 @@ export interface ApiFailure {
   body?: unknown;
 }
 
+/**
+ * The `error.code` values an operation documents on its non-2xx answers, read
+ * from the SDK's generated types. A code the kit branches on is declared
+ * against this, so a code the API stops documenting fails `tsc`.
+ */
+export type ApiErrorCode<Op> = Extract<ApiResponse<Op>, { ok: false }>["data"] extends infer D ? (D extends { error: { code: infer C } } ? C : never) : never;
+
+/** The codes both spend routes document; the rail takes either. */
+export type SpendErrorCode = ApiErrorCode<ApiOperation<"/v1/consumers/mandates/{id}/spend", "post">> & ApiErrorCode<ApiOperation<"/v1/consumer-payments/execute", "post">>;
+
+const UNCERTAIN_CODES: readonly SpendErrorCode[] = ["psp_dispatch_uncertain", "psp_attempt_uncertain"];
+
+/** The thrown error's body is `unknown` to the SDK, whatever the route documents; this reads `{ error: { code, message } }` off it without a cast. */
+function errorEnvelope(body: unknown): { code?: string; message?: string } {
+  if (!body || typeof body !== "object" || !("error" in body)) return {};
+  const error = body.error;
+  if (!error || typeof error !== "object") return {};
+  return {
+    ...("code" in error && typeof error.code === "string" ? { code: error.code } : {}),
+    ...("message" in error && typeof error.message === "string" ? { message: error.message } : {}),
+  };
+}
+
 /** Normalise the SDK's two error classes into one readable shape without leaking the body into logs. */
 export function describeApiError(err: unknown): ApiFailure {
   if (err instanceof TimeoutError) return { status: 0, code: "timeout", message: `request timed out after ${err.timeoutMs}ms` };
   if (err instanceof CodesparApiError) {
-    const body = err.body as { error?: { code?: string; message?: string } } | undefined;
+    const envelope = errorEnvelope(err.body);
     return {
       status: err.status,
-      code: err.code ?? body?.error?.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
-      message: body?.error?.message ?? err.message,
+      code: err.code ?? envelope.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: envelope.message ?? err.message,
       body: err.body,
     };
   }
@@ -49,5 +72,5 @@ export function describeApiError(err: unknown): ApiFailure {
 
 /** 5xx, timeouts and `psp_dispatch_uncertain` mean "the money may have moved". */
 export function isUncertain(failure: ApiFailure): boolean {
-  return failure.status === 0 || failure.status >= 500 || failure.code === "psp_dispatch_uncertain" || failure.code === "psp_attempt_uncertain";
+  return failure.status === 0 || failure.status >= 500 || UNCERTAIN_CODES.some((code) => code === failure.code);
 }

package/templates/bills-agent/packages/agent-core/src/api/mandate-status.ts

@@ -6,26 +6,36 @@
  * the same `csk_test_` client every other call of the kit uses.
  *
  * Fail-closed: this source never throws and never assumes. A transport
- * failure, a timeout, a 404, a 5xx, an unreadable body or a status outside
- * `active | paused | revoked | expired` is reported as `unknown`, and the
- * engine executes nothing on `unknown`.
+ * failure, a timeout, a 404, a 5xx, an unreadable body, a status outside
+ * `active | paused | revoked | expired` or an `org_paused` that is not a
+ * boolean is reported as `unknown`, and the engine executes nothing on
+ * `unknown`.
  *
- * The organization kill switch (`org pauseAll`) has no API surface, so
- * `org_paused` is `false` here: the API cannot say it, and this source does
- * not invent it.
+ * The organization kill switch (ent#1648) answers on the same read:
+ * `org_paused` next to `status`, which stays the mandate's own. A missing
+ * `org_paused` is `unknown`, never "not paused": a deployment that cannot
+ * say whether the organization stopped every spend has not said it did not.
  */
-import type { ApiClient } from "@codespar/sdk";
+import type { ApiOperation, ApiSuccess, ApiClient } from "@codespar/sdk";
 import { z } from "zod";
 import type { MandateStatusReport, MandateStatusSource } from "../revocation.js";
 import { describeApiError } from "./client.js";
 
-/** The two fields of the 14-field projection the gate reads; the rest is passed through untouched. */
+/** `GET /v1/mandates/{id}` as the SDK's generated OpenAPI types it. */
+type MandateRead = ApiSuccess<ApiOperation<"/v1/mandates/{id}", "get">>;
+
+/**
+ * The three fields the gate reads; the rest is passed through untouched.
+ * Bound to the SDK's type, so a field the API renames or retypes breaks the
+ * compile here instead of reading as absent at run time.
+ */
 const MandateReadSchema = z
   .object({
     status: z.enum(["active", "paused", "revoked", "expired"]),
     expires_at: z.string(),
+    org_paused: z.boolean(),
   })
-  .passthrough();
+  .passthrough() satisfies z.ZodType<Pick<MandateRead, "status" | "expires_at" | "org_paused">>;
 
 export class ApiMandateStatusSource implements MandateStatusSource {
   constructor(
@@ -35,7 +45,7 @@ export class ApiMandateStatusSource implements MandateStatusSource {
 
   async check(mandateId: string): Promise<MandateStatusReport> {
     const base = { mandate_id: mandateId, org_paused: false, checked_at: this.clock().toISOString(), source: "api" as const };
-    let body: unknown;
+    let body: MandateRead;
     try {
       body = await this.api.get("/v1/mandates/{id}", { path: { id: mandateId } });
     } catch (err) {
@@ -46,11 +56,17 @@ export class ApiMandateStatusSource implements MandateStatusSource {
           : `GET /v1/mandates/${mandateId} did not answer (${failure.code}): ${failure.message}`;
       return { ...base, status: "unknown", detail };
     }
+    // The type says what the API promises; the parse checks that this answer kept the promise.
     const parsed = MandateReadSchema.safeParse(body);
     if (!parsed.success) {
-      const status = body && typeof body === "object" && "status" in body ? String((body as { status: unknown }).status) : "missing";
-      return { ...base, status: "unknown", detail: `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})` };
+      const unread = parsed.error.issues.map((issue) => issue.path.join(".") || "body");
+      const status = body && typeof body === "object" && "status" in body ? String(body.status) : "missing";
+      const detail = unread.includes("org_paused")
+        ? `GET /v1/mandates/${mandateId} did not say whether the organization is paused (org_paused unreadable)`
+        : `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})`;
+      return { ...base, status: "unknown", detail };
     }
+    if (parsed.data.org_paused) return { ...base, org_paused: true, status: parsed.data.status };
     const expiresAt = new Date(parsed.data.expires_at).getTime();
     const expired = Number.isFinite(expiresAt) && expiresAt <= this.clock().getTime();
     return { ...base, status: expired && parsed.data.status === "active" ? "expired" : parsed.data.status };