@codespar/cli 0.12.1 → 0.14.0

package/templates/bills-agent/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "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.",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "packages/agent-core",
+    "agents/bills-agent"
+  ],
+  "scripts": {
+    "start": "npm start --workspace=agents/bills-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 agents/bills-agent/tsconfig.json",
+    "approve": "npm run approve --workspace=agents/bills-agent --",
+    "consent": "npm run consent --workspace=agents/bills-agent --",
+    "deny": "npm run deny --workspace=agents/bills-agent --",
+    "eval": "npm run eval --workspace=agents/bills-agent --",
+    "reconcile": "npm run reconcile --workspace=agents/bills-agent --",
+    "rerun": "npm run rerun --workspace=agents/bills-agent --",
+    "resume": "npm run resume --workspace=agents/bills-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/bills-agent/packages/agent-core/README.md

@@ -0,0 +1,19 @@
+# @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.
+
+## 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.
+
+## 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.

package/templates/bills-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.4",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * 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>;
+}
+
+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"];
+  /** 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 } = 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;
+        },
+      });
+      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/bills-agent/packages/agent-core/src/api/charge-rail.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 } 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";
+
+/** 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;
+}
+
+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" };
+    let view: ChargeView;
+    try {
+      view = (await this.api.post("/v1/charges", {
+        body: {
+          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,
+        },
+      })) as ChargeView;
+    } 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;
+  }
+
+  async lookup(attemptId: string, _payment: RailPayment): Promise<RailLookup> {
+    try {
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: attemptId } })) as ChargeView;
+      return outcomeOf(view);
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      if (failure.status === 409) return { status: "in_flight" };
+      return { 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 };
+      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() },
+        chain: null,
+        receipt_sig: 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/bills-agent/packages/agent-core/src/api/client.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 } 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;
+}
+
+/** 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;
+    return {
+      status: err.status,
+      code: err.code ?? body?.error?.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: body?.error?.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 || failure.code === "psp_dispatch_uncertain" || failure.code === "psp_attempt_uncertain";
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Mandate status from the API: `GET /v1/mandates/{id}`, the one registered
+ * spelling of the consumer-allowance point read (the SDK's OpenAPI says the
+ * path has no alias; `/v1/consumers/mandates/{id}` answers 404 on staging,
+ * measured 2026-09-23). Consulted before `executing` (section 4.7), through
+ * 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`.
+ *
+ * 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.
+ */
+import type { 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. */
+const MandateReadSchema = z
+  .object({
+    status: z.enum(["active", "paused", "revoked", "expired"]),
+    expires_at: z.string(),
+  })
+  .passthrough();
+
+export class ApiMandateStatusSource implements MandateStatusSource {
+  constructor(
+    private readonly api: ApiClient,
+    private readonly clock: () => Date = () => new Date(),
+  ) {}
+
+  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;
+    try {
+      body = await this.api.get("/v1/mandates/{id}", { path: { id: mandateId } });
+    } catch (err) {
+      const failure = describeApiError(err);
+      const detail =
+        failure.status === 404
+          ? `the API has no mandate ${mandateId} for this key (${failure.code})`
+          : `GET /v1/mandates/${mandateId} did not answer (${failure.code}): ${failure.message}`;
+      return { ...base, status: "unknown", detail };
+    }
+    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 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 };
+  }
+}

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

@@ -0,0 +1,101 @@
+/**
+ * The CodeSpar sandbox rail. With the signed envelope the consent returned
+ * (`mandate.canonical` + `mandate.signature`) it spends through
+ * `POST /v1/consumer-payments/execute`; without it, by mandate id through
+ * `POST /v1/consumers/mandates/{id}/spend`. Both are idempotent on
+ * `attempt_id`. The by-id route answered `bad_signature` on staging for a
+ * mandate carrying `periodic_cap` (OPEN_QUESTIONS §14), which is why the
+ * envelope is preferred when it exists. Receipts come back from
+ * `GET /v1/consumers/receipts/{id}`.
+ *
+ * The API has no `actor` field on the wire today (OPEN_QUESTIONS §2). The
+ * spend carries `agent_id`, which the mandate binds; the full actor is
+ * stamped on the local receipt copy and on every event of the bundle.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import type { Mandate } from "../mandate.js";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { Actor } from "../types.js";
+import { describeApiError, isUncertain } from "./client.js";
+
+export class CodeSparRail implements PaymentRail {
+  readonly name = "codespar" as const;
+
+  constructor(
+    private readonly api: ApiClient,
+    private readonly envelope?: Pick<Mandate, "canonical" | "signature"> | undefined,
+  ) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    try {
+      const outcome =
+        this.envelope?.canonical && this.envelope.signature
+          ? await this.api.post("/v1/consumer-payments/execute", {
+              body: {
+                mandate: this.envelope.canonical,
+                signature: this.envelope.signature,
+                amount_minor: payment.amount_minor,
+                purpose: payment.purpose,
+                agent_id: payment.agent_id,
+                payee: payment.payee,
+                attempt_id: payment.attempt_id,
+              },
+            })
+          : await this.api.post("/v1/consumers/mandates/{id}/spend", {
+              path: { id: payment.mandate_id },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id },
+            });
+      return {
+        status: "settled",
+        transaction_id: outcome.payment.transactionId,
+        receipt_id: outcome.receipt?.id ?? null,
+        money_moved: outcome.payment.moneyMoved,
+        sandbox: !outcome.payment.moneyMoved,
+        raw: outcome,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+  }
+
+  /**
+   * There is no read route for an attempt. The documented way is to present
+   * the same `attempt_id` again: the lifecycle is idempotent on it and
+   * answers the state it reached. `psp_attempt_in_flight` means the first
+   * presentation is still running.
+   */
+  async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const outcome = await this.pay(payment);
+    if (outcome.status === "failed" && outcome.code === "psp_attempt_in_flight") return { status: "in_flight" };
+    return outcome;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    try {
+      const r = await this.api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
+      return {
+        receipt_id: r.receipt_id,
+        state: r.state,
+        mandate: { id: r.mandate.id },
+        payment: {
+          amount_minor: r.payment.amount_minor,
+          payee: r.quote?.payee ?? null,
+          attempt_id: r.payment.attempt_id,
+          money_moved: r.payment.money_moved,
+          sandbox: r.payment.sandbox === true,
+          at: r.payment.at,
+        },
+        chain: r.chain,
+        receipt_sig: r.receipt_sig,
+        actor,
+        raw: r,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * The sandbox PAYER: `POST /v1/test/charges/{chargeId}/pay` (alias
+ * `POST /v1/charges/{chargeId}/sandbox/pay`), test environment only. It
+ * plays the debtor: the charge goes through the same settlement path a
+ * provider `charge-in` webhook takes, `commerce.charge.paid` fans out to the
+ * project's triggers, and every record it leaves carries `simulated: true`
+ * plus `settled_against: "sandbox_fixture"`. No money moves anywhere. A
+ * live-environment key is refused with `sandbox_pay_not_permitted` before
+ * anything is read. The route is not in the SDK's typed operations yet
+ * (merged 2026-09-23), so it is called by path.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import { describeApiError, type ApiFailure } from "./client.js";
+
+export interface SandboxPaidState {
+  charge_id: string;
+  status: "paid";
+  local_status: string;
+  currency: string;
+  quoted_minor: number;
+  paid_minor: number;
+  payment: "full" | "partial" | "over";
+  paid_via: string;
+  wallet_id: string;
+  ledger_entry_id: string | null;
+  event: { id: string; type: string } | null;
+  simulated: boolean;
+  settled_against: string | null;
+  money_moved: false;
+  idempotent_replay: boolean;
+}
+
+export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
+
+export async function paySandboxCharge(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+  try {
+    const state = (await api.request("post", "/v1/test/charges/{chargeId}/pay" as never, {
+      path: { chargeId: chargeRef },
+      body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
+    } as never)) as SandboxPaidState;
+    return { ok: true, state };
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+}