@codespar/cli 0.17.0 → 0.18.1

package/templates/collections-agent/packages/agent-runtime/test/whatsapp-status-replies.test.ts

@@ -0,0 +1,182 @@
+/**
+ * §46's three product gaps, as the channel now answers them, with no network:
+ * a status webhook is read (a `failed` of an outcome's message is that
+ * outcome NOT told), a tapped quick reply becomes a turn only as the intent a
+ * declared template gave it, and the registry carries a fallback for an
+ * outcome the kit has no copy for. The same behaviour against the emulator is
+ * in the repository's `test/whatsapp-emulator.integration.test.ts`, and the
+ * `check` rule that requires the fallback, asked of the shipped agents, in
+ * `test/whatsapp-fallback-check.test.ts`: both read this repository's other
+ * agents and scripts, which a template made from one agent does not carry.
+ */
+import { describe, expect, it } from "vitest";
+import type { WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { buildSendRequest, parseInbound, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
+import type { ChannelBackend, ChannelLogLine, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../src/channels/types.js";
+
+const CONTACT = "+5511987654321";
+const NOW = new Date("2026-09-23T17:00:00Z");
+
+/** A backend the test drives: it queues what the person does and hands the channel the statuses the test reports. */
+class Scripted implements ChannelBackend {
+  readonly name = "scripted";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  private listener: ((s: StatusUpdate) => void) | undefined;
+  constructor(private readonly inbox: InboundMessage[] = []) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `wamid.test.${this.delivered.length}`, state: "sent" };
+  }
+  onStatus(listener: (s: StatusUpdate) => void): void {
+    this.listener = listener;
+  }
+  report(status: StatusUpdate): void {
+    this.listener?.(status);
+  }
+  async close(): Promise<void> {}
+}
+
+const TEMPLATES: WhatsAppTemplate[] = [
+  { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Oi! {{1}} quitado." },
+  {
+    name: "acordo_cobranca_vencida",
+    language: "pt_BR",
+    description: "expired",
+    body: "Oi! A cobranca do {{1}} venceu.",
+    buttons: [
+      { id: "emitir_nova", title: "Emitir nova", intent: "quero que voce emita uma nova cobranca para o meu acordo" },
+      { id: "agora_nao", title: "Agora nao", intent: "agora nao quero uma nova cobranca" },
+    ],
+  },
+  { name: "atendimento_atualizacao", language: "pt_BR", description: "fallback", body: "Oi! Temos uma atualizacao.", fallback: true },
+];
+
+function channel(inbox: InboundMessage[] = []) {
+  const backend = new Scripted(inbox);
+  const said: string[] = [];
+  const failed: ChannelLogLine[] = [];
+  const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT, subject: "acordo-1042" }, now: () => NOW, templates: TEMPLATES, say: (l) => said.push(l), onDeliveryFailed: (l) => failed.push(l) });
+  return { ch, backend, said, failed };
+}
+
+const tap = (id: string, extra: Partial<InboundMessage["reply"]> = {}): InboundMessage => ({ id: `wamid.in.${id}`, from: CONTACT, text: "Emitir nova", timestamp: 1790190000, reply: { type: "button_reply", id, title: "Emitir nova", ...extra } });
+
+describe("1. a status webhook is read, and a failed outcome is an outcome not told", () => {
+  it("parses statuses, with Meta's errors, out of the same delivery that carries messages", () => {
+    const parsed = parseInbound({
+      entry: [{ changes: [{ value: { statuses: [{ id: "wamid.a", status: "failed", timestamp: "1790190000", errors: [{ code: 131026, title: "Message undeliverable", error_data: { details: "not on whatsapp" } }] }, { id: "wamid.b", status: "read", timestamp: "1790190001" }, { id: "wamid.c", status: "deleted" }] } }] }],
+    });
+    expect(parsed.statuses).toEqual([
+      { message_id: "wamid.a", status: "failed", timestamp: 1790190000, errors: [{ code: 131026, title: "Message undeliverable", details: "not on whatsapp" }] },
+      { message_id: "wamid.b", status: "read", timestamp: 1790190001, errors: [] },
+    ]);
+  });
+
+  it("a failed status of a message that told an outcome is recorded, reaches the operator and the outcome's owner, and names the outcome", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos, acordo quitado.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "failed", timestamp: 1790190100, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(ch.deliveryOf(sent.id)).toBe("failed");
+    const status = ch.log().find((l) => l.direction === "status")!;
+    expect(status).toMatchObject({ kind: "status", message_id: sent.id, state: "failed", about: { execution_id: "exe_1", state: "settled" }, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(failed).toEqual([status]);
+    expect(said.join("\n")).toContain("a pessoa NAO foi avisada");
+  });
+
+  it("a read is recorded and nothing more: not consent, not an acknowledgement, not a reply", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "read", timestamp: 1790190100, errors: [] });
+    expect(ch.log().filter((l) => l.direction === "status").map((l) => l.state)).toEqual(["read"]);
+    expect(failed).toEqual([]);
+    expect(said).toEqual([]);
+    // A read is not a turn either.
+    expect(await ch.next()).toBeUndefined();
+  });
+
+  it("a failure the provider reports BEFORE the send answered (the emulator posts statuses synchronously) is still tied to its outcome", async () => {
+    class Eager extends Scripted {
+      override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+        const sent = await super.deliver(to, body);
+        this.report({ message_id: sent.id, status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+        return sent;
+      }
+    }
+    const backend = new Eager();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    await ch.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"], about: { execution_id: "exe_2", state: "settled" } });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_2", state: "settled" }]);
+  });
+
+  it("a status about a message an EARLIER run sent is tied back to the outcome that run recorded", async () => {
+    const prior: ChannelLogLine = { at: NOW.toISOString(), direction: "out", contact: "+55*****4321", kind: "template", message_id: "wamid.old", state: "sent", about: { execution_id: "exe_old", state: "settled" } };
+    const backend = new Scripted();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, priorLines: [prior], onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    backend.report({ message_id: "wamid.old", status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+    expect(failed[0]?.about).toEqual({ execution_id: "exe_old", state: "settled" });
+  });
+});
+
+describe("2. a tapped quick reply is a turn, as the intent a declared template gave it", () => {
+  it("parses a button_reply, a list_reply and a template's quick-reply button, id and context kept", () => {
+    const msg = (m: Record<string, unknown>) => ({ entry: [{ changes: [{ value: { messages: [{ from: "5511987654321", timestamp: "1", ...m }] } }] }] });
+    expect(parseInbound(msg({ id: "a", type: "interactive", interactive: { type: "button_reply", button_reply: { id: "emitir_nova", title: "Emitir nova" } }, context: { id: "wamid.offer" } })).messages[0]?.reply).toEqual({ type: "button_reply", id: "emitir_nova", title: "Emitir nova", context_id: "wamid.offer" });
+    expect(parseInbound(msg({ id: "b", type: "interactive", interactive: { type: "list_reply", list_reply: { id: "3x", title: "3x", description: "tres" } } })).messages[0]?.reply).toEqual({ type: "list_reply", id: "3x", title: "3x" });
+    expect(parseInbound(msg({ id: "c", type: "button", button: { payload: "emitir_nova", text: "Emitir nova" } })).messages[0]?.reply).toEqual({ type: "button", id: "emitir_nova", title: "Emitir nova" });
+    // What this channel cannot read is still named, not turned into an empty message.
+    expect(parseInbound(msg({ id: "d", type: "image" })).ignored).toEqual([{ id: "d", type: "image" }]);
+    expect(parseInbound(msg({ id: "e", type: "interactive", interactive: { type: "nfm_reply" } })).ignored).toEqual([{ id: "e", type: "interactive:nfm_reply" }]);
+  });
+
+  it("a declared id is a turn whose text is the declared intent, never the title", async () => {
+    const { ch } = channel([tap("emitir_nova")]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("quero que voce emita uma nova cobranca para o meu acordo");
+    const line = ch.log().at(-1)!;
+    expect(line).toMatchObject({ direction: "in", kind: "reply", reply: { id: "emitir_nova", title: "Emitir nova" }, text: "quero que voce emita uma nova cobranca para o meu acordo" });
+  });
+
+  it("an id no template declares is not a turn: recorded, told to the operator, and the next real turn is what comes back", async () => {
+    const typed: InboundMessage = { id: "wamid.in.text", from: CONTACT, text: "oi", timestamp: 1790190001 };
+    const { ch, said } = channel([tap("pagar_tudo", { title: "Pagar tudo" }), typed]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("oi");
+    expect(ch.log()[0]).toMatchObject({ kind: "reply", refused: { rule: "reply_not_offered" }, reply: { id: "pagar_tudo" } });
+    expect(said.join("\n")).toContain("reply_not_offered");
+  });
+
+  it("a tap that names a message this conversation did not send with that reply is not a turn either", async () => {
+    const { ch } = channel([tap("emitir_nova", { context_id: "wamid.somebody_else" })]);
+    expect(await ch.next()).toBeUndefined();
+    expect(ch.log()[0]?.refused?.rule).toBe("reply_not_offered");
+  });
+
+  it("a template goes out with the quick replies its declaration offers, and the log says which", async () => {
+    const { ch, backend } = channel();
+    await ch.send({ kind: "template", template: "acordo_cobranca_vencida", language: "pt_BR", variables: ["acordo-1042"] });
+    expect((backend.delivered[0] as { buttons?: unknown }).buttons).toEqual([{ id: "emitir_nova", title: "Emitir nova" }, { id: "agora_nao", title: "Agora nao" }]);
+    expect(ch.log()[0]?.offered).toEqual(["emitir_nova", "agora_nao"]);
+    const config: CloudApiConfig = { baseUrl: "http://sim", phoneNumberId: "1", accessToken: "t", verifyToken: "v", appSecret: "s", apiVersion: "v22.0", webhookPort: 0 };
+    const request = buildSendRequest(config, CONTACT, backend.delivered[0]!) as { body: string };
+    expect(JSON.parse(request.body).template.components).toEqual([
+      { type: "body", parameters: [{ type: "text", text: "acordo-1042" }] },
+      { type: "button", sub_type: "quick_reply", index: "0", parameters: [{ type: "payload", payload: "emitir_nova" }] },
+      { type: "button", sub_type: "quick_reply", index: "1", parameters: [{ type: "payload", payload: "agora_nao" }] },
+    ]);
+  });
+});

package/templates/collections-agent/scripts/whatsapp-emulator.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Runs the WhatsApp Cloud API emulator the channel's `simulator` backend talks
+ * to: `dyvit-wa-sim`, published as `@dyvit/whatsapp-simulator-cli` (MIT) from
+ * https://github.com/fabianocruz/whatsapp-simulator. It is not ours and it is
+ * not a dependency of this workspace.
+ *
+ * WHY NOT A DEPENDENCY. It is a development tool. Nothing in `packages/` or
+ * `agents/` imports it, so `npm ci` has no reason to fetch it and a contributor
+ * who never runs the WhatsApp gate never downloads it. `npx` fetches the exact
+ * version into its own cache the first time it is needed; nothing is vendored,
+ * nothing is installed globally, and the repository's tree is untouched.
+ *
+ * WHY PINNED TO A VERSION. A moving `latest` would make our gate fail on
+ * somebody else's release. `--version` overrides, and there is no `latest`.
+ * The spec handed to `npx` is exact, so it cannot resolve anything else.
+ *
+ * Usage:
+ *   node scripts/whatsapp-emulator.mjs                   start it (foreground)
+ *   node scripts/whatsapp-emulator.mjs --prepare         fetch only
+ *   node scripts/whatsapp-emulator.mjs --version <v>     a different release
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const EMULATOR_PACKAGE = "@dyvit/whatsapp-simulator-cli";
+/** The release the gate is measured against. Bump deliberately, never automatically. */
+export const EMULATOR_VERSION = "0.3.0";
+export const EMULATOR_PORT = 4290;
+/** Must match `WHATSAPP_SIM_APP_SECRET`. A local development value, not a credential. */
+export const EMULATOR_APP_SECRET = "dev";
+/** Where the channel's own receiver listens; the emulator posts its webhooks there. */
+export const EMULATOR_WEBHOOK_PORT = 4399;
+
+function spec(version) {
+  return `${EMULATOR_PACKAGE}@${version}`;
+}
+
+/** Warms `npx`'s cache so the start below does not race a download. */
+export function prepare(version = EMULATOR_VERSION, say = (l) => process.stderr.write(l + "\n")) {
+  say(`whatsapp emulator: fetching ${spec(version)}`);
+  const result = spawnSync("npx", ["--yes", spec(version), "--help"], { stdio: ["ignore", "ignore", "inherit"] });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`could not fetch ${spec(version)} (npx exited ${result.status}). Is the version published, and is the network reachable?`);
+  }
+  return spec(version);
+}
+
+function serve(version, webhookUrl) {
+  const child = spawn(
+    "npx",
+    ["--yes", spec(version), "serve", "--port", String(EMULATOR_PORT), "--webhook", webhookUrl, "--app-secret", EMULATOR_APP_SECRET],
+    // Its own process group: `npx` is a wrapper around the real server, and a
+    // signal sent to the wrapper alone leaves the port held by an orphan.
+    { cwd: ROOT, stdio: "inherit", detached: true },
+  );
+  const stop = () => {
+    try {
+      process.kill(-child.pid, "SIGTERM");
+    } catch {
+      child.kill("SIGTERM");
+    }
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  const argv = process.argv.slice(2);
+  const version = argv.includes("--version") ? argv[argv.indexOf("--version") + 1] : EMULATOR_VERSION;
+  const webhookUrl = argv.includes("--webhook") ? argv[argv.indexOf("--webhook") + 1] : `http://127.0.0.1:${EMULATOR_WEBHOOK_PORT}/`;
+  if (argv.includes("--prepare")) {
+    prepare(version);
+    process.stderr.write(`whatsapp emulator ready: ${spec(version)}\n`);
+  } else {
+    process.stderr.write(`whatsapp emulator: ${spec(version)} on :${EMULATOR_PORT}, webhooks to ${webhookUrl}\n`);
+    serve(version, webhookUrl);
+  }
+}

package/templates/hello-agent/README.md

@@ -1,7 +1,7 @@
 # {{name}}
 
 Scaffolded by `codespar init --template hello-agent` from the `hello-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 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.
 

package/templates/hello-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/hello-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/hello-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/hello-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/hello-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);
 }