@codespar/cli 0.18.0 → 0.20.0

package/templates/supplier-payments-agent/agents/supplier-payments-agent/test/locale.test.ts

@@ -0,0 +1,101 @@
+/**
+ * #64 on the batch gesture: one question for a whole list, shown in the run's
+ * locale and read the same in both. For every answer the parser has a rule
+ * for, in either language, the pt-BR run and the English run veto the same
+ * lines, pay the same lines, and record the same gesture.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fixedClock, type Locale } from "@codespar/agent-core";
+import { handleExecution, presentBatch, setup, type BatchGestures, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { runBatch } from "../src/modules/batch-payout.js";
+import { findBatch } from "../src/payables.js";
+
+const APPROVER = { id: "usr_demo_financeiro", channel: "terminal" };
+
+function open(locale: Locale): Setup {
+  return setup(agent, {
+    mode: "human",
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "supplier-locale-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "supplier-locale-state-")),
+    now: fixedClock("2026-09-23T14:00:00-03:00"),
+    say: () => undefined,
+    locale,
+  });
+}
+
+/** Runs the October payroll through the interactive terminal's two hooks, answering the list question with `answers` in order. */
+async function gesture(locale: Locale, answers: string[]) {
+  const s = open(locale);
+  const asked: string[] = [];
+  const said: string[] = [];
+  const queue = [...answers];
+  const gestures: BatchGestures = new Map();
+  const options = {
+    setup: s,
+    approver: APPROVER,
+    gestures,
+    say: (l: string) => void said.push(l),
+    ask: async (q: string) => {
+      asked.push(q);
+      const next = queue.shift();
+      if (next === undefined) throw new Error(`asked more than scripted: ${q}`);
+      return next;
+    },
+  };
+  try {
+    const report = await runBatch(findBatch("folha-2026-10")!, {
+      engine: s.engine,
+      onExecution: (execution) => handleExecution(execution, options),
+      onBatch: (batch) => presentBatch(batch, options),
+    });
+    const recorded = s.bundle.readEvents().filter((e) => e["type"] === "batch.gesture").map((e) => {
+      const { approved, vetoed, count, total_minor } = e["payload"] as Record<string, unknown>;
+      return { approved, vetoed, count, total_minor };
+    });
+    return { dispatch: report.lines.map((l) => l.dispatch), gesture: report.gesture, recorded, asked, said, settled: report.settled_minor };
+  } finally {
+    s.close();
+  }
+}
+
+const ANSWERS: string[][] = [["todas"], ["all"], ["todas exceto 2"], ["all except 2"], ["todas exceto 1, 3"], ["all except 3,1"], ["nenhuma"], ["none"], [""], ["nao"], ["tudo", "all"], ["everything", "todas exceto 3"]];
+
+describe("the batch gesture decides the same in both locales", () => {
+  it.each(ANSWERS)("answers %j", async (...answers) => {
+    const pt = await gesture("pt-BR", answers);
+    const en = await gesture("en", answers);
+    // The question is shown in the run's locale...
+    expect(new Set(pt.asked)).toEqual(new Set(["  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] "]));
+    expect(new Set(en.asked)).toEqual(new Set(["  Approve the list? [all / all except 3,7 / none] "]));
+    expect(en.asked).toHaveLength(pt.asked.length);
+    // ...and the answer decides the same lines either way.
+    expect(en.dispatch).toEqual(pt.dispatch);
+    expect(en.gesture).toEqual({ ...pt.gesture, batch_hash: en.gesture!.batch_hash });
+    expect(en.gesture!.batch_hash).toBe(pt.gesture!.batch_hash);
+    expect(en.recorded).toEqual(pt.recorded);
+    expect(en.settled).toBe(pt.settled);
+  });
+
+  it("shows the list and the outcome in the run's locale, amounts formatted for its reader", async () => {
+    const pt = await gesture("pt-BR", ["todas exceto 2"]);
+    const en = await gesture("en", ["todas exceto 2"]);
+    expect(pt.said.join("\n")).toMatch(/lote folha-2026-10 — .*: 3 linha\(s\), total R\$ 5\.400,00/);
+    expect(pt.said).toContain("  -> lista aprovada exceto 2");
+    expect(en.said.join("\n")).toMatch(/batch folha-2026-10 — .*: 3 line\(s\), total R\$5,400\.00/);
+    expect(en.said).toContain("  -> list approved except 2");
+  });
+
+  it("asks again, in its own language, when the answer cannot be read", async () => {
+    const pt = await gesture("pt-BR", ["talvez", "todas"]);
+    const en = await gesture("en", ["maybe", "all"]);
+    expect(pt.said).toContain("  não entendi; responda todas, todas exceto <números de 1 a 3> ou nenhuma");
+    expect(en.said).toContain("  I did not understand; answer all, all except <numbers from 1 to 3> or none");
+    expect(en.dispatch).toEqual(pt.dispatch);
+  });
+});

package/templates/supplier-payments-agent/agents/supplier-payments-agent/test/run-outcome.test.ts

@@ -0,0 +1,127 @@
+/**
+ * What the terminal says a run did is counted from the engine, not taken from
+ * the reply. The replayed reply of the payroll is one sentence whatever the
+ * run does: it says the payroll was proposed and that the result of each line
+ * is on the terminal. These runs are the two where a reply could not say more
+ * (every line already paid; every line failed), driven as real processes
+ * because the exit code is part of the contract.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const PAYROLL = "roda a folha de outubro";
+const PAYROLL_KEYS = "ana.ribeiro@example.com.br,+5511988880002,11144477735";
+
+function run(args: string[], env: Record<string, string>) {
+  const result = spawnSync(process.execPath, [BIN, "start", ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "2026-10-07T14:00:00-03:00", ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/** A person at the keyboard: each answer is typed when its prompt shows, because readline drops a line that arrives before the question. */
+function converse(args: string[], env: Record<string, string>, answers: Array<{ after: string; type: string }>): Promise<string> {
+  return new Promise((done, fail) => {
+    const child = spawn(process.execPath, [BIN, "start", ...args], { cwd: AGENT_DIR, env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "2026-10-07T14:00:00-03:00", ...env } });
+    let stdout = "";
+    let stderr = "";
+    const pending = [...answers];
+    const feed = () => {
+      while (pending[0] && (stdout + stderr).includes(pending[0].after)) child.stdin.write(pending.shift()!.type + "\n");
+      if (pending.length === 0) child.stdin.end();
+    };
+    child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); feed(); });
+    child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); feed(); });
+    child.on("error", fail);
+    child.on("close", () => done(stdout));
+  });
+}
+
+function scratch(label: string): Record<string, string> {
+  const stateDir = mkdtempSync(join(tmpdir(), `supplier-outcome-${label}-`));
+  return { SUPPLIER_PAYMENTS_STATE_DIR: stateDir, SUPPLIER_PAYMENTS_RUNS_DIR: join(stateDir, "runs") };
+}
+
+type Payload = { reply: string; executions: Array<{ state: string }>; run_outcome: { settled: number; failed: number; declined: number; already_paid: number; open: number } };
+
+describe("npm start -- --input: the line after the reply is the engine's count", () => {
+  it("a payroll that settles says so and exits 0", () => {
+    const out = run(["--input", PAYROLL, "--approve"], scratch("settled"));
+    expect(out.stdout).toContain("resultado deste run: 3 liquidada(s), 0 com falha ou recusada(s), 0 negada(s) ou expirada(s), 0 pulada(s) por já paga(s), 0 em aberto");
+    expect(out.code).toBe(0);
+  });
+
+  it("a second run of a paid payroll drafts nothing, says three lines were already paid, and exits 0", () => {
+    const env = scratch("paid");
+    expect(run(["--input", PAYROLL, "--approve"], env).code).toBe(0);
+    const again = run(["--input", PAYROLL, "--approve", "--json"], env);
+    const payload = JSON.parse(again.stdout.trim()) as Payload;
+    expect(payload.executions).toHaveLength(0);
+    expect(payload.run_outcome).toMatchObject({ settled: 0, failed: 0, already_paid: 3, open: 0 });
+    expect(again.code).toBe(0);
+
+    const told = run(["--input", PAYROLL, "--approve"], env);
+    expect(told.stdout).toContain("resultado deste run: 0 liquidada(s), 0 com falha ou recusada(s), 0 negada(s) ou expirada(s), 3 pulada(s) por já paga(s), 0 em aberto");
+  });
+
+  it("a payroll the rail refuses line by line says three failed and exits 1, whatever the recorded reply says", () => {
+    const out = run(["--input", PAYROLL, "--approve", "--json"], { ...scratch("failed"), SUPPLIER_PAYMENTS_STUB_REFUSE: PAYROLL_KEYS });
+    const payload = JSON.parse(out.stdout.trim()) as Payload;
+    expect(payload.executions.map((e) => e.state)).toEqual(["failed", "failed", "failed"]);
+    // The recording cannot know what the rail answered, so it promises a result and no receipt.
+    expect(payload.reply).toContain("O resultado de cada linha está no terminal");
+    expect(payload.reply).not.toMatch(/recibo/i);
+    expect(payload.run_outcome).toMatchObject({ settled: 0, failed: 3, already_paid: 0, open: 0 });
+    expect(out.code).toBe(1);
+  });
+
+  it("a payroll a person denies is not a failed process: three declined, exit 0", () => {
+    const out = run(["--input", PAYROLL, "--deny", "--json"], scratch("denied"));
+    expect((JSON.parse(out.stdout.trim()) as Payload).run_outcome).toMatchObject({ settled: 0, failed: 0, declined: 3, already_paid: 0, open: 0 });
+    expect(out.code).toBe(0);
+  });
+
+  it("the suppliers' batch replays one reply whether its lines were paid, denied or refused, and it claims none of the three", () => {
+    const SUPPLIERS = "paga os fornecedores de outubro";
+    const paid = JSON.parse(run(["--input", SUPPLIERS, "--approve", "--json"], scratch("suppliers-paid")).stdout.trim()) as Payload;
+    const denied = JSON.parse(run(["--input", SUPPLIERS, "--deny", "--json"], scratch("suppliers-denied")).stdout.trim()) as Payload;
+    expect(paid.run_outcome).toMatchObject({ settled: 3, failed: 0 });
+    expect(denied.run_outcome).toMatchObject({ settled: 0, declined: 3 });
+    // The recording was written for the run where the rail refuses one payee, and said who was paid and who was refused under these two as well.
+    expect(denied.reply).toBe(paid.reply);
+    expect(paid.reply).toContain("O resultado de cada linha está no terminal");
+    expect(paid.reply).not.toMatch(/foram pagos|foi recusado|recibo/i);
+  });
+
+  it("--help says what the exit code means", () => {
+    const out = run(["--help"], {});
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain("exit (--input): 0");
+  });
+});
+
+describe("npm start, interactive: every turn's reply is followed by the engine's count", () => {
+  it("prints the count of the turn under the replayed reply", async () => {
+    const stdout = await converse(["--transcript", "scenarios/happy-path.transcript.jsonl", "--locale", "en"], { ...scratch("interactive"), SUPPLIER_PAYMENTS_STUB_REFUSE: PAYROLL_KEYS }, [
+      { after: "Ctrl+D", type: PAYROLL },
+      { after: "Approve the list?", type: "all" },
+    ]);
+    expect(stdout).toContain("O resultado de cada linha está no terminal");
+    expect(stdout).toContain("result of this run: 0 settled, 3 failed or refused, 0 denied or expired, 0 skipped as already paid, 0 open");
+  });
+
+  it("says nothing after a turn that drafted nothing and skipped nothing", async () => {
+    // The recorded exfiltration reply calls no payment tool: a read, or a greeting, moved nothing and is not a run result.
+    const stdout = await converse(["--transcript", "evals/adversarial/exfiltration.transcript.jsonl", "--locale", "en"], scratch("interactive-read"), [{ after: "Ctrl+D", type: "oi" }]);
+    expect(stdout.trim().length).toBeGreaterThan(0);
+    expect(stdout).not.toContain("result of this run");
+  });
+});

package/templates/supplier-payments-agent/agents/supplier-payments-agent/tools.json

@@ -46,7 +46,7 @@
     {
       "name": "list_payables",
       "effect": "read",
-      "description": "The month's payables, grouped into the batches the company runs: suppliers, commissions, payroll. Each line carries its payee alias, name, amount in BRL cents, reference, and whether a previous run of that batch already covers it (`open`, `already_settled`, `in_progress`). Read-only.",
+      "description": "The month's payables, grouped into the batches the company runs: suppliers, commissions, payroll, each with its due date and days until it falls due, plus `today`, the only date you know. Each line carries its payee alias, name, amount in BRL cents, reference, and whether a previous run of that batch already covers it (`open`, `already_settled`, `in_progress`). Read-only.",
       "input_schema": { "type": "object", "properties": {} }
     }
   ]

package/templates/supplier-payments-agent/packages/agent-core/README.md

@@ -1,8 +1,8 @@
 # @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 primitives every CodeSpar starter-kit agent inherits (section 4 of spec v5.1.1, [`docs/spec-v5.1.1.md`](../../docs/spec-v5.1.1.md), the only spec version in this repository; [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) says where later parts were built against v5.2 and the checkout spec v0.2): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract, the conversation loop 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.
+This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|inspect|check|eval|verify`, 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
 
@@ -25,10 +25,29 @@ This package is the decisions. The RUNNER around them — the terminal channel,
 
 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.
 
+## Who acted, on the wire
+
+Every spend sends the kit's actor as the SDK's `PaymentActor` (`wireActorOf` in `rail.ts`): an agent is `{ type: "agent", id: "<name>@<version>", on_behalf_of: <the mandate's consumer> }`, a person `{ type: "human", id, channel }`. `agent_id` still goes too; it names the agent the mandate was signed for. The rail reads the actor the API recorded back as `sealed_actor`, the bundle's receipt copy keeps it beside the kit's own `actor`, and one that differs from what was sent, or is missing, is a `receipt.actor_mismatch` event. It does not stop the run: the actor is what the receipt records, not what it proves. It is not in the chain, so a third party checking the Ed25519 signature learns nothing about who triggered the spend, and a charge carries no actor at all. §2.
+
+## A settlement this run did not make
+
+A spend presented again under the same attempt id is answered with the earlier payment (`idempotent_replay`). Dispatch marks that outcome `replayed: true`, and `isReplayedSettlement(execution)` is true when every settled attempt carries the mark. The money moved, and this execution did not move it. The execution is still `settled`. Only dispatch writes the mark, because dispatch is always this execution's first presentation of an id. Reconcile does not copy it: a lookup presents the attempt again, and the API answers every look at a settled attempt as a replay, this execution's own payment included. The tool results and a one-shot's `--json` read this predicate (`replayed`); `inspect` reads the same mark from the bundle's rail answers. An attempt closed by reconcile is still counted as paid by the execution that looked it up. §39c.
+
 ## 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.
 
+## The conversation loop
+
+`AgentLoop.turn` (`agent.ts`) sends the model the system prompt, the conversation and the tool specs, and hands each tool call to the kit's handler for it; a tool outside `tools.json` is refused `tool_not_allowed`. Only the engine behind the handlers moves money. Two things it adds that no prompt can:
+
+- **The reply language.** `detectLanguage` (`language.ts`) reads the language of what the person typed, Brazilian Portuguese or English, from function words; payee names, amounts and Pix keys count for neither. The loop appends a "Reply language for this turn" section naming it to the system prompt of every step of the turn. Tool results do not count: on the Messages API they are user-role messages, and a prompt rule alone lost to their Portuguese data. A turn with no lead either way keeps the previous turn's language, and before any lead the prompt's own default stands. The transcript's user line records `reply_language` (`null` before any lead). §64.
+- **The date.** `ExecutionEngine.today()` is the date in the guardrails' timezone at the engine's clock, so `--now` pins it. `list_bills`, `list_payables` and `list_agreements` return it as `today`, and bills and payables also carry `days_until_due` (`daysUntil`), because the model has no calendar of its own.
+
+## What the code prints, per locale
+
+`locale.ts` and `strings.ts` (#64). A run has one locale, `pt-BR` or `en`: `--locale`, else the optional `locale:` of `agent.yaml`, else `pt-BR` (`resolveLocale`). `CORE_STRINGS` holds the lines every agent shares (the batch gesture, the waits, how an execution and a payable instrument read, the WhatsApp operator lines) in both locales, and `tableGaps` is what `npm run check` runs over it and over each kit's table: a key one locale lacks, an empty string, or a function whose arity differs is an error. `formatBRL` and `formatDay` format for the locale's reader ("R$ 1.850,00" / "R$1,850.00"; "30/09/2026" / "2026-09-30"). `WHATSAPP_LANGUAGE` maps a locale to the language Meta approves a template in (`pt_BR`, `en_US`); the template registry holds one copy per (name, language), and the check requires every template in the language of every locale. None of it touches what an answer decides, and it is independent of the reply language above.
+
 ## 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/supplier-payments-agent/packages/agent-core/package.json

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

package/templates/supplier-payments-agent/packages/agent-core/src/agent.ts

@@ -6,6 +6,7 @@
  */
 import type { ProofBundle } from "./bundle.js";
 import type { ExecutionEngine } from "./engine.js";
+import { detectLanguage, replyLanguageDirective, type ReplyLanguage } from "./language.js";
 import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
 import { isReply } from "./providers/types.js";
 import type { Execution } from "./state-machine.js";
@@ -25,6 +26,23 @@ export interface ToolContext {
    * `onExecution`, and still mints its own artifact.
    */
   onBatch?: (batch: BatchPresentation) => Promise<BatchGesture | undefined>;
+  /**
+   * Fires for a line a payment tool was asked to pay and created NO execution
+   * for in this run: one an earlier run already covers, or one refused before
+   * a draft existed. Without it such a line leaves nothing behind for the
+   * channel to count, and a run that paid nobody reads like one that had
+   * nothing to say.
+   */
+  onNotRun?: (line: NotRunLine) => void;
+}
+
+/** A line a payment tool did not turn into an execution in this run, and why. */
+export interface NotRunLine {
+  /** What the person would call the line: a batch line's alias, a payee. */
+  ref: string;
+  /** `already_settled`: an earlier run paid it. `in_progress`: an earlier execution for it is still open. `refused`: it was refused before a draft. */
+  why: "already_settled" | "in_progress" | "refused";
+  detail?: string;
 }
 
 /** What a person sees when a whole batch is put in front of them: the list, its total, and the hash of the list. */
@@ -74,6 +92,8 @@ export interface TurnResult {
   reply: string;
   tool_calls: Array<{ name: string; refused: boolean }>;
   executions: Execution[];
+  /** Lines the turn's payment tools did not turn into an execution (`ToolContext.onNotRun`). */
+  not_run: NotRunLine[];
 }
 
 export class AgentLoop {
@@ -81,6 +101,8 @@ export class AgentLoop {
   private readonly allowed: Set<string>;
   private readonly specs: ToolSpec[];
   private readonly clock: () => Date;
+  /** The language the person last wrote in, kept when a turn gives no lead of its own ("ok"). */
+  private language: ReplyLanguage | undefined;
 
   constructor(private readonly options: AgentLoopOptions) {
     this.allowed = allowedToolNames(options.tools);
@@ -97,24 +119,28 @@ export class AgentLoop {
     const maxSteps = this.options.maxSteps ?? 8;
     const calls: TurnResult["tool_calls"] = [];
     const executions: Execution[] = [];
+    const notRun: NotRunLine[] = [];
+
+    this.language = detectLanguage(userText) ?? this.language;
+    const system = this.language ? `${this.options.system.trimEnd()}\n\n${replyLanguageDirective(this.language)}\n` : this.options.system;
 
     this.messages.push({ role: "user", content: userText });
-    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText, reply_language: this.language ?? null });
 
     for (let step = 0; step < maxSteps; step += 1) {
-      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      const out = await runtime.step({ 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 };
+        return { reply: out.text, tool_calls: calls, executions, not_run: notRun };
       }
 
       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);
+        const result = await this.dispatch(call, executions, notRun);
         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 });
@@ -124,10 +150,10 @@ export class AgentLoop {
     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 };
+    return { reply: text, tool_calls: calls, executions, not_run: notRun };
   }
 
-  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+  private async dispatch(call: ToolCall, executions: Execution[], notRun: NotRunLine[]): 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 });
 
@@ -148,6 +174,7 @@ export class AgentLoop {
           return settledOrNot;
         },
         ...(onBatch ? { onBatch } : {}),
+        onNotRun: (line) => void notRun.push(line),
       });
       return { refused: false, content };
     } catch (err) {

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

@@ -1,6 +1,6 @@
 /**
  * The CodeSpar receivable rail: the merchant COLLECTS. `pay()` issues a
- * cobranca com vencimento through `POST /v1/charges` (the REST form of the
+ * cobrança 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
@@ -65,6 +65,17 @@ export function instrumentOf(view: ChargeView): ChargeInstrument {
   };
 }
 
+/**
+ * Issuer statuses that end a registration with no instrument: no Pix, no
+ * boleto, nothing a payer can pay, and nothing will be. `ERROR` is the one
+ * measured (staging, 2026-09-27, OPEN_QUESTIONS §63): the read's documented
+ * set is `PROCESSING`, `PENDING`, `CONFIRMED`, `CANCELLED`, `EXPIRED`, and the
+ * field is a plain string. Any status this kit does not know stays
+ * `accepted` and unpayable: failing it could close an order a payer may yet
+ * pay, and waiting pays nobody.
+ */
+export const ISSUER_ERROR_STATUSES: readonly string[] = ["ERROR"];
+
 /** 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" };
@@ -78,6 +89,9 @@ export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight"
   if (view.status === "CANCELLED" || view.local_status === "cancelled") {
     return { status: "failed", code: "charge_cancelled", message: `charge ${id} was withdrawn`, raw: view };
   }
+  if (ISSUER_ERROR_STATUSES.includes(view.status)) {
+    return { status: "failed", code: "charge_issuer_error", message: `the issuer ended charge ${id}'s registration in ${view.status}: no Pix, no boleto, nothing a payer can pay`, raw: view };
+  }
   return { status: "accepted", transaction_id: id, instrument: instrumentOf(view), sandbox: true, raw: view };
 }
 

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

@@ -10,14 +10,17 @@
  * 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.
+ * Every spend carries the kit's `actor` on the wire (`PaymentActor`,
+ * @codespar/sdk 0.16.10): the agent and the consumer it acts for, or the
+ * person and their channel. The API records it on the receipt and reads it
+ * back, and the engine compares what came back with what was sent
+ * (OPEN_QUESTIONS §2). `agent_id` still goes too: it names the agent the
+ * mandate was SIGNED for, which is an authority, not the event.
  */
 import type { ApiClient } from "@codespar/sdk";
 import type { Mandate } from "../mandate.js";
 import { checkQuote } from "../quote.js";
-import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
+import { checkSpendApproval, wireActorOf, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
 import type { Actor } from "../types.js";
 import { describeApiError, isUncertain, type SpendErrorCode } from "./client.js";
 
@@ -59,11 +62,12 @@ export class CodeSparRail implements PaymentRail {
                 attempt_id: payment.attempt_id,
                 quote: quoted.quote,
                 approval: approval.approval,
+                actor: wireActorOf(payment.actor),
               },
             })
           : 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, quote: quoted.quote, approval: approval.approval },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval, actor: wireActorOf(payment.actor) },
             });
       return {
         status: "settled",
@@ -142,6 +146,8 @@ export class CodeSparRail implements PaymentRail {
         receipt_sig_ed25519: r.receipt_sig_ed25519 || null,
         receipt_sig_kid: r.receipt_sig_kid || null,
         actor,
+        // What the API recorded, as it read it back; the engine compares it with what the spend sent.
+        sealed_actor: r.actor,
         raw: r,
       };
     } catch (err) {

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

@@ -14,6 +14,7 @@
  */
 import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
 import type { ApiFailure } from "./client.js";
+import { ISSUER_ERROR_STATUSES, type ChargeView } from "./charge-rail.js";
 import { createCodeSparClient, describeApiError } from "./client.js";
 
 /** What the payer route answers, as the SDK's generated OpenAPI types it. */
@@ -41,3 +42,38 @@ export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, c
     return { ok: false, failure: describeApiError(err) };
   }
 }
+
+/** Why the payer did not call the pay route: there was nothing a payer could have paid. */
+export type PayerRefusal = { code: "no_payable_instrument" | "charge_issuer_error"; message: string };
+
+export type GuardedPayResult = SandboxPayResult | { ok: false; refused: PayerRefusal };
+
+/**
+ * The sandbox payer as a PAYER: it reads the charge first and pays only an
+ * instrument a person could have paid, a Pix or a boleto line the read calls
+ * `payable`. A charge the issuer ended in error (`ERROR`) is refused as
+ * `charge_issuer_error`, anything else unpayable as `no_payable_instrument`,
+ * and in both cases the pay route is never called.
+ *
+ * The route itself settles whatever it is handed: a charge still
+ * `PROCESSING`, and on staging on 2026-09-27 a charge the issuer ended in
+ * `ERROR`, after which the read answers `CONFIRMED` (ent#1816,
+ * OPEN_QUESTIONS §63). A payer that trusted it turned an issuance that failed
+ * into a "settled" order no customer could have paid. No live payer can pay a
+ * charge with no instrument, so neither does this one.
+ */
+export async function payIfPayable(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<GuardedPayResult> {
+  let view: ChargeView;
+  try {
+    view = await api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } });
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+  if (ISSUER_ERROR_STATUSES.includes(view.status)) {
+    return { ok: false, refused: { code: "charge_issuer_error", message: `the issuer ended charge ${chargeRef}'s registration in ${view.status}; there is no instrument to pay, so the pay route was not called` } };
+  }
+  if (!view.payable) {
+    return { ok: false, refused: { code: "no_payable_instrument", message: `charge ${chargeRef} has no payable instrument (status ${view.status}, local ${view.local_status}); the pay route was not called` } };
+  }
+  return paySandboxCharge(api, chargeRef, amountMinor);
+}

package/templates/supplier-payments-agent/packages/agent-core/src/bundle.ts

@@ -178,6 +178,8 @@ export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Recor
   // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
   if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
   if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  // Written onto the copy since every spend carries the actor (§2); the read calls it `actor`, the copy `sealed_actor` beside its own stamp.
+  if ("sealed_actor" in copy) expected.push(["sealed_actor", canonicalJson(copy["sealed_actor"] ?? null), canonicalJson(read["actor"] ?? null)]);
   return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
 }
 

package/templates/supplier-payments-agent/packages/agent-core/src/channels.ts

@@ -154,22 +154,32 @@ export const TemplateRegistrySchema = z
   })
   .strict()
   .superRefine((registry, ctx) => {
+    // Meta approves a template per (name, language): the same name in two languages is two templates, the same pair twice is one declared twice.
     const seen = new Set<string>();
     const replyIds = new Set<string>();
+    const replyOwner = new Map<string, string>();
     for (const [i, template] of registry.templates.entries()) {
-      if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
-      seen.add(template.name);
-      // A tap is resolved by its id alone, so one id means one intent across the whole registry.
+      const pair = `${template.name}/${template.language}`;
+      if (seen.has(pair)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice in ${template.language}` });
+      seen.add(pair);
+      // A tap is resolved by its id in the conversation's language, so one id means one intent per language, and one template across languages.
       for (const [j, button] of (template.buttons ?? []).entries()) {
-        if (replyIds.has(button.id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice` });
-        replyIds.add(button.id);
+        if (replyIds.has(`${button.id}/${template.language}`)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice in ${template.language}` });
+        replyIds.add(`${button.id}/${template.language}`);
+        const owner = replyOwner.get(button.id);
+        if (owner !== undefined && owner !== template.name) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is offered by ${owner} and by ${template.name}` });
+        replyOwner.set(button.id, template.name);
       }
     }
   });
 
-/** Every quick reply the registry declares, by id: the only taps that can become a turn. */
-export function declaredReplies(templates: readonly WhatsAppTemplate[]): Map<string, QuickReply> {
-  return new Map(templates.flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
+/**
+ * Every quick reply the registry declares, by id: the only taps that can
+ * become a turn. With a `language`, only the copies declared in it: an English
+ * conversation hands the model the English intent of the button it tapped.
+ */
+export function declaredReplies(templates: readonly WhatsAppTemplate[], language?: string): Map<string, QuickReply> {
+  return new Map(templates.filter((t) => language === undefined || t.language === language).flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
 }
 
 export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;

package/templates/supplier-payments-agent/packages/agent-core/src/check.ts

@@ -14,6 +14,7 @@ import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js
 import { MandateSchema } from "./mandate.js";
 import { ToolsFileSchema } from "./tools.js";
 import { canonicalJson } from "./hash.js";
+import { LOCALES, WHATSAPP_LANGUAGE } from "./locale.js";
 import { PUBLISHED_EVENTS, isPublishedEvent } from "./events.js";
 
 export interface CheckFinding {
@@ -145,9 +146,30 @@ export function checkAgent(agentDir: string): CheckReport {
   if (manifest.channels.includes("whatsapp")) {
     if (!existsSync(registryPath)) error("channels_templates_missing", `agent.yaml declares the whatsapp channel and channels/whatsapp/${TEMPLATE_REGISTRY_FILE} does not exist`);
     else if (registry) {
-      const fallbacks = registry.templates.filter((t) => t.fallback);
-      if (fallbacks.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${fallbacks.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
-      else if (templateArity(fallbacks[0]!.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallbacks[0]!.name} takes variables; it is sent when nothing specific can be said, so it takes none`);
+      const names = [...new Set(registry.templates.filter((t) => t.fallback).map((t) => t.name))];
+      if (names.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${names.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
+      for (const fallback of registry.templates.filter((t) => t.fallback)) {
+        if (templateArity(fallback.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallback.name} (${fallback.language}) takes variables; it is sent when nothing specific can be said, so it takes none`);
+      }
+    }
+  }
+  // A conversation speaks the language of its locale, and either locale can be
+  // chosen per run (`--locale`), so every template exists in the language of
+  // every locale, with the same buttons and the same variables. A template
+  // missing in one language is an outcome that locale cannot tell once the
+  // 24-hour window shuts.
+  if (registry) {
+    const languages = LOCALES.map((l) => WHATSAPP_LANGUAGE[l]);
+    for (const template of registry.templates) {
+      if (!languages.includes(template.language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${template.name} is declared in ${template.language}, which no locale sends; the locales send ${languages.join(", ")}`);
+    }
+    for (const name of [...new Set(registry.templates.map((t) => t.name))]) {
+      const copies = registry.templates.filter((t) => t.name === name);
+      for (const language of languages) {
+        if (!copies.some((t) => t.language === language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${name} has no ${language} copy; a conversation in that locale could not send it`);
+      }
+      const shape = (t: (typeof copies)[number]) => JSON.stringify({ arity: templateArity(t.body), buttons: (t.buttons ?? []).map((b) => b.id), fallback: t.fallback ?? false });
+      if (new Set(copies.map(shape)).size > 1) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: the copies of ${name} differ in variables, buttons or fallback across languages; a translation says the same thing`);
     }
   }
   if (existsSync(registryPath)) {