@codespar/cli 0.16.0 → 0.18.0

package/templates/checkout-agent/agents/checkout-agent/tools.json

@@ -0,0 +1,68 @@
+{
+  "meta_tools": [
+    {
+      "name": "codespar_charge",
+      "effect": "charge",
+      "description": "The order and its charge. action=create turns the cart into an ORDER for the customer you are talking to: the code prices it from the catalog, checks it against the sales policy (price, discount, margin floor, ticket, service hours) and, depending on the approval mode, asks the attendant or confirms it alone. Nothing is issued by create. action=issue sends the confirmed order's charge: ONE bolepix (cobranca com vencimento, due today: the customer pays by Pix or by boleto) for the cart's total, with an idempotency key, so asking twice returns the same charge; the code presents the QR and the copy-and-paste. If the cart changed after the order was confirmed, issue sends it back to the attendant instead. action=status reads the order. You never pass an amount or a document: the code takes the total from the cart and the customer's name and document from the store's customer book.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["create", "issue", "status"], "description": "create (the default) places the order; issue sends its charge; status reads it." },
+          "cart_id": { "type": "string", "description": "Optional. The cart (cart-1). Omitted: the conversation's current cart." },
+          "customer": { "type": "string", "description": "action=create: the alias of the customer you are talking to, their first name in lowercase (marina). Never a document, a name typed for somebody else, or a Pix key." },
+          "payment": { "type": "string", "enum": ["bolepix"], "description": "Optional. The only instrument offered: bolepix." },
+          "total_minor": { "type": "integer", "description": "Optional. The total you told the customer. The code recomputes it; if yours differs, the order is refused and you present the cart's total again." },
+          "execution_id": { "type": "string", "description": "Optional, issue/status: the order to act on. Omitted: the current cart's order." }
+        },
+        "required": ["action"]
+      }
+    }
+  ],
+  "local_tools": [
+    {
+      "name": "list_catalog",
+      "effect": "read",
+      "description": "The store's catalog (sku, title, category, list price, availability, stock where limited) and how it sells: service hours, the instrument, and the discount rule in words. Read-only. Costs, discount ceilings, coupon codes and customers are not returned.",
+      "input_schema": { "type": "object", "properties": {} }
+    },
+    {
+      "name": "cart_view",
+      "effect": "read",
+      "description": "The cart as the code priced it: lines, totals, coupon, validation_issues, cart_hash, and the order it belongs to, if any. Read-only.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "cart_id": { "type": "string", "description": "Optional. Omitted: the conversation's current cart." }
+        }
+      }
+    },
+    {
+      "name": "cart_update",
+      "effect": "state",
+      "description": "REPLACES the whole cart with the lines you pass and answers the cart re-priced by the code. There is no add or remove: send the complete list every time; an empty list empties the cart. A line is a sku and a quantity, plus a negotiated discount in percent when the customer asked for one; there is no price field anywhere, prices come from the catalog. A coupon is the code the customer gave you; the code checks it against the store's table. Every answer carries validation_issues [{code, field, message}] (sku_unknown, item_unavailable, quantity_invalid, quantity_above_stock, coupon_unknown, coupon_not_applicable, price_not_caller_input): a line or a coupon named there is NOT in the cart. If the cart already became an order that is still open, the order follows the new cart and goes back to the attendant.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "cart_id": { "type": "string", "description": "Optional. Omitted: the conversation's current cart, or a new one if none is open." },
+          "lines": {
+            "type": "array",
+            "description": "The complete cart, one entry per sku.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "sku": { "type": "string", "description": "A sku from list_catalog." },
+                "quantity": { "type": "integer", "minimum": 1 },
+                "discount_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Optional. A negotiated discount on this line, in percent. The code refuses what the store's policy does not allow." }
+              },
+              "required": ["sku", "quantity"],
+              "additionalProperties": false
+            }
+          },
+          "coupon": { "type": "string", "description": "Optional. The coupon code the customer gave." },
+          "order_discount_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Optional. A negotiated discount on the whole order, in percent. Does not add to a coupon." }
+        },
+        "required": ["lines"]
+      }
+    }
+  ]
+}

package/templates/checkout-agent/agents/checkout-agent/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/templates/checkout-agent/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "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.",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "packages/agent-core",
+    "packages/agent-runtime",
+    "agents/checkout-agent"
+  ],
+  "scripts": {
+    "start": "npm start --workspace=agents/checkout-agent --",
+    "check": "npm run check --workspaces --if-present --",
+    "test": "vitest run --pool=forks --maxWorkers=1",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/tsconfig.json && tsc --noEmit -p agents/checkout-agent/tsconfig.json",
+    "whatsapp:emulator": "node scripts/whatsapp-emulator.mjs",
+    "approve": "npm run approve --workspace=agents/checkout-agent --",
+    "deny": "npm run deny --workspace=agents/checkout-agent --",
+    "eval": "npm run eval --workspace=agents/checkout-agent --",
+    "inspect": "npm run inspect --workspace=agents/checkout-agent --",
+    "poll": "npm run poll --workspace=agents/checkout-agent --",
+    "reconcile": "npm run reconcile --workspace=agents/checkout-agent --",
+    "rerun": "npm run rerun --workspace=agents/checkout-agent --",
+    "resume": "npm run resume --workspace=agents/checkout-agent --",
+    "webhook": "npm run webhook --workspace=agents/checkout-agent --"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}

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

@@ -0,0 +1,34 @@
+# @codespar/agent-core
+
+The primitives every CodeSpar starter-kit agent inherits (spec v5.1.1, section 4): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract and the two providers.
+
+This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|check|eval`, the setup that wires this package to an agent directory, and the scenario and adversarial runners — is [`@codespar/agent-runtime`](../agent-runtime), which depends on this one and is what an agent's `package.json` scripts call (#13). Nothing here knows an agent's name.
+
+## The state machine, and what the types do and do not prove
+
+`transition(execution, to, input)` accepts only a `to` that the table in `state-machine.ts` lists for `execution.state`. On a **narrowed** value (`Execution<"drafted">`, `Execution<"executing">`, ...) a transition outside the table is a compile error, and `test/transitions.type-test.ts` keeps that true with `@ts-expect-error` lines that `tsc` refuses to leave unused. An **un-narrowed** `Execution` (the union, which is what a row read back from SQLite is) compiles for any target; the engine narrows with casts at its call sites. So the guard that always holds is the runtime one: `transition()` throws `IllegalTransitionError` on any pair the table does not list, whatever the static type said. The type test proves the table is closed; the runtime check enforces it.
+
+## The one policy, three gates
+
+`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`, `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/checkout-agent/packages/agent-core/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@codespar/agent-core",
+  "version": "0.1.0",
+  "description": "The primitives every CodeSpar starter-kit agent inherits: the execution state machine, the approval artifact, the agent.yaml manifest, escalate_above, actor, local state and providers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./providers/anthropic": "./src/providers/anthropic.ts",
+    "./providers/replay": "./src/providers/replay.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --pool=forks --maxWorkers=1 --root ../.. packages/agent-core"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.128.0",
+    "@codespar/sdk": "0.16.10",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  }
+}

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

@@ -0,0 +1,163 @@
+/**
+ * The tool-use loop. The provider says what the model wants; this file
+ * dispatches only the tools `tools.json` names, records every step in the
+ * transcript, and hands payment tools to the engine, which is the only
+ * thing that can move an execution past `drafted`.
+ */
+import type { ProofBundle } from "./bundle.js";
+import type { ExecutionEngine } from "./engine.js";
+import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
+import { isReply } from "./providers/types.js";
+import type { Execution } from "./state-machine.js";
+import type { ToolsFile } from "./tools.js";
+import { allowedToolNames, toolSpecs } from "./tools.js";
+
+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>;
+
+export interface AgentLoopOptions {
+  runtime: AgentRuntime;
+  tools: ToolsFile;
+  handlers: Record<string, ToolHandler>;
+  system: string;
+  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;
+}
+
+export interface TurnResult {
+  reply: string;
+  tool_calls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+export class AgentLoop {
+  private readonly messages: ConversationMessage[] = [];
+  private readonly allowed: Set<string>;
+  private readonly specs: ToolSpec[];
+  private readonly clock: () => Date;
+
+  constructor(private readonly options: AgentLoopOptions) {
+    this.allowed = allowedToolNames(options.tools);
+    this.specs = toolSpecs(options.tools);
+    this.clock = options.clock ?? (() => new Date());
+  }
+
+  get history(): readonly ConversationMessage[] {
+    return this.messages;
+  }
+
+  async turn(userText: string): Promise<TurnResult> {
+    const { runtime, bundle } = this.options;
+    const maxSteps = this.options.maxSteps ?? 8;
+    const calls: TurnResult["tool_calls"] = [];
+    const executions: Execution[] = [];
+
+    this.messages.push({ role: "user", content: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+
+    for (let step = 0; step < maxSteps; step += 1) {
+      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      if (isReply(out)) {
+        this.messages.push({ role: "assistant", content: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant_step", reply: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant", text: out.text });
+        return { reply: out.text, tool_calls: calls, executions };
+      }
+
+      this.messages.push({ role: "assistant", content: "", tool_calls: out });
+      bundle.transcript({ at: this.now(), kind: "assistant_step", tool_calls: out });
+
+      for (const call of out) {
+        const result = await this.dispatch(call, executions);
+        calls.push({ name: call.name, refused: result.refused });
+        this.messages.push({ role: "tool", tool_call_id: call.id, name: call.name, content: JSON.stringify(result.content), ...(result.refused ? { is_error: true } : {}) });
+        bundle.transcript({ at: this.now(), kind: "tool_result", tool_call_id: call.id, name: call.name, refused: result.refused, content: result.content });
+      }
+    }
+
+    const text = "I stopped: too many tool steps in one turn. Nothing was paid beyond what the trail shows.";
+    this.messages.push({ role: "assistant", content: text });
+    bundle.transcript({ at: this.now(), kind: "assistant", text, truncated: true });
+    return { reply: text, tool_calls: calls, executions };
+  }
+
+  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+    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)) {
+      // Section 15, closed tools: a tool outside tools.json is refused, and the refusal is in the trail.
+      bundle.event({ at: this.now(), type: "tool.refused", tool: call.name, reason: "tool_not_allowed", actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_not_allowed", message: `${call.name} is not in this agent's tools.json` } };
+    }
+    const handler = handlers[call.name];
+    if (!handler) return { refused: true, content: { error: "tool_not_implemented", message: `${call.name} has no handler` } };
+
+    try {
+      const content = await handler(call.input, {
+        engine,
+        onExecution: async (execution) => {
+          const settledOrNot = await onExecution(execution);
+          executions.push(settledOrNot);
+          return settledOrNot;
+        },
+        ...(onBatch ? { onBatch } : {}),
+      });
+      return { refused: false, content };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      bundle.event({ at: this.now(), type: "tool.error", tool: call.name, message, actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_failed", message } };
+    }
+  }
+
+  private now(): string {
+    return this.clock().toISOString();
+  }
+}

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

@@ -0,0 +1,195 @@
+/**
+ * The CodeSpar receivable rail: the merchant COLLECTS. `pay()` issues a
+ * cobranca com vencimento through `POST /v1/charges` (the REST form of the
+ * `codespar_charge` meta-tool, action=create): `method: "boleto"` plus a
+ * `due_date` is what makes it ONE receivable the payer settles either by
+ * boleto or by Pix; `idempotency_key` is REQUIRED on that create and is our
+ * attempt id, so a retry returns the same charge instead of a second
+ * receivable the same debtor could pay twice. An immediate Pix
+ * (`method: "pix"`) is deliberately not used: the API does not replay its
+ * create on a key and does not read it back, so it cannot close a loop.
+ *
+ * `lookup()` is `GET /v1/charges/{id}`, which accepts our idempotency key as
+ * the id; the kit polls it to close the cycle when no webhook can reach a
+ * terminal. Branching is on `local_status` and the normalized `status`, never
+ * on prose. Amounts cross the wire in MAJOR units (`amount: 1080.5`), which
+ * is what `coerceMetaChargeArgs` reads; the answer's `amount_minor` is
+ * compared with what was asked and a mismatch is a failure, not a charge.
+ *
+ * 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, 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, type ApiErrorCode } from "./client.js";
+
+/** 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 {
+  return {
+    payable: view.payable,
+    status: view.status,
+    pix_copy_paste: view.pix_copy_paste,
+    boleto_bank_line: view.boleto_bank_line,
+    boleto_bar_code: view.boleto_bar_code,
+    due_date: view.due_date,
+  };
+}
+
+/** What a charge view means for the attempt. The row's own status wins over the issuer's normalized one where they name a terminal state. */
+export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight" } {
+  if (view.issuance_unconfirmed || !view.id) return { status: "in_flight" };
+  const id = view.id;
+  if (view.local_status === "settled" || view.status === "CONFIRMED" || view.settlement === "confirmed") {
+    return { status: "settled", transaction_id: id, receipt_id: id, money_moved: false, sandbox: true, raw: view };
+  }
+  if (view.local_status === "expired" || view.status === "EXPIRED") {
+    return { status: "failed", code: "charge_expired", message: `charge ${id} reached its due date unpaid`, raw: view };
+  }
+  if (view.status === "CANCELLED" || view.local_status === "cancelled") {
+    return { status: "failed", code: "charge_cancelled", message: `charge ${id} was withdrawn`, raw: view };
+  }
+  return { status: "accepted", transaction_id: id, instrument: instrumentOf(view), sandbox: true, raw: view };
+}
+
+export class CodeSparChargeRail implements PaymentRail {
+  readonly name = "codespar-charge" as const;
+
+  constructor(private readonly api: ApiClient) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    if (!payment.due_date) return { status: "failed", code: "due_date_required", message: "a receivable needs a due_date; the immediate Pix charge cannot be read back or replayed" };
+    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", {
+        body: {
+          consumer_id: payment.consumer_id,
+          amount: payment.amount_minor / 100,
+          currency: payment.currency,
+          method: "boleto",
+          description: payment.description ?? payment.purpose,
+          buyer: { name: payment.beneficiary ?? payment.payee, document: payment.payee },
+          due_date: payment.due_date,
+          idempotency_key: payment.attempt_id,
+        },
+      });
+    } catch (err) {
+      const failure = describeApiError(err);
+      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.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);
+      return { status: "failed", code: "amount_mismatch", message: `the API issued ${view.amount_minor} for a request of ${payment.amount_minor} (charge ${view.id}); ${withdrawn ? "withdrawn" : "withdrawal refused, an operator must cancel it"}` };
+    }
+    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;
+  }
+
+  /**
+   * By the charge id when the create handed one back; by our idempotency key only when it did not (the create's answer was lost).
+   * The route's doc says the read accepts the caller's key as the id; on staging (2026-09-23) it answered `charge_not_found` for
+   * the key and the charge for the id, so the id comes first and the key is the fallback, not the other way round.
+   */
+  async lookup(attemptId: string, _payment: RailPayment, transactionId?: string): Promise<RailLookup> {
+    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 === "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 === "failed" || byKey.kind === "uncertain") return byKey.outcome;
+    return undefined;
+  }
+
+  /**
+   * 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 } });
+      return { kind: "view", view };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return { kind: "missing" };
+      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 } });
+      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: settledAt(view) ?? new Date().toISOString() },
+        chain: null,
+        receipt_sig: null,
+        receipt_sig_ed25519: null,
+        receipt_sig_kid: null,
+        actor,
+        raw: view,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  private async withdraw(chargeId: string): Promise<boolean> {
+    try {
+      await this.api.post("/v1/charges/{chargeId}/cancel", { path: { chargeId } });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * The one place the kit talks to the CodeSpar API. The key is checked for
+ * the `csk_test_` prefix before the client is built, so no live key ever
+ * reaches the network from this repository.
+ */
+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";
+
+export interface CodeSparClientOptions {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export function createCodeSparClient(options: CodeSparClientOptions): ApiClient {
+  const apiKey = assertTestKey(options.apiKey);
+  return new ApiClient({
+    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    apiKey,
+    ...(options.projectId ? { projectId: options.projectId } : {}),
+    timeout: options.timeoutMs ?? 30_000,
+  });
+}
+
+export interface ApiFailure {
+  status: number;
+  code: string;
+  message: string;
+  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 envelope = errorEnvelope(err.body);
+    return {
+      status: err.status,
+      code: err.code ?? envelope.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: envelope.message ?? err.message,
+      body: err.body,
+    };
+  }
+  return { status: 0, code: "unknown", message: err instanceof Error ? err.message : String(err) };
+}
+
+/** 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 || UNCERTAIN_CODES.some((code) => code === failure.code);
+}