@codespar/cli 0.18.1 → 0.20.0

package/templates/bills-agent/agents/bills-agent/test/reply-and-outcome.test.ts

@@ -0,0 +1,84 @@
+/**
+ * The replayed reply of `happy-path` is the same sentence whatever the run
+ * does with the payment it proposed. It promises a result, which every run
+ * has, and no receipt, which only a settled one has.
+ */
+import { 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");
+/** Inside the escalation hours and inside the example mandate's validity, whatever the day and the shell the suite runs in. */
+const DAYTIME = "2026-09-23T14:00:00-03:00";
+/** The line the terminal prints for a receipt that exists, in the locale these runs are pinned to. */
+const RECEIPT_LINE = /^\s*recibo: .*rcpt_stub_/;
+
+interface Payload {
+  reply: string;
+  executions: Array<{ state: string; escalation: { trigger: string } | null; receipt_ids: string[] }>;
+  receipts: string[];
+}
+
+function scratch(): Record<string, string> {
+  const stateDir = mkdtempSync(join(tmpdir(), "bills-reply-"));
+  return { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+}
+
+/** One `npm start`, in pt-BR and on a pinned clock; `--now` in `args` overrides the clock. */
+function start(args: string[], env: Record<string, string> = scratch()) {
+  const result = spawnSync(process.execPath, [BIN, "start", "--locale", "pt-BR", ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: DAYTIME, ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr, payload: () => JSON.parse(result.stdout.trim()) as Payload };
+}
+
+const receiptLines = (terminal: string) => terminal.split("\n").filter((line) => RECEIPT_LINE.test(line));
+
+describe("npm start -- --input: the replayed reply against what the run did", () => {
+  const INPUT = ["--input", "pague a escola de outubro", "--json"];
+
+  it.each([
+    { name: "a person denied", flags: ["--deny"], state: "denied" },
+    { name: "nobody decided", flags: [], state: "awaiting_approval" },
+  ])("cites no receipt when $name, and there is none", ({ flags, state }) => {
+    const out = start([...INPUT, ...flags]);
+    const payload = out.payload();
+    expect(payload.executions.map((e) => e.state)).toEqual([state]);
+    expect(payload.receipts).toEqual([]);
+    expect(payload.reply).toContain("O resultado está no terminal.");
+    expect(payload.reply).not.toMatch(/recibo/i);
+    expect(receiptLines(out.stderr)).toEqual([]);
+  });
+
+  it("says the same when the payment settled, and the receipt is the terminal's own line", () => {
+    const out = start([...INPUT, "--approve"]);
+    expect(out.code).toBe(0);
+    const payload = out.payload();
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(payload.receipts).toHaveLength(1);
+    expect(payload.reply).toContain("O resultado está no terminal.");
+    expect(payload.reply).not.toMatch(/recibo/i);
+    // The receipt is named once, by the terminal, on the line that gives its path.
+    expect(receiptLines(out.stderr)).toHaveLength(1);
+  });
+
+  it("a payment inside the mandate that the hour sends to a human is not said to be paid", () => {
+    // The payee has a settled payment under this mandate first, so what escalates the next one is the hour and not `new_beneficiary`, which is checked before it.
+    const env = scratch();
+    const seed = start(["--mode", "mandate", "--input", "paga 400 reais pra escola (material)", "--transcript", "test/fixtures/material-400.transcript.jsonl", "--approve", "--json"], env);
+    expect(seed.payload().executions[0]).toMatchObject({ state: "settled", escalation: { trigger: "new_beneficiary" } });
+
+    const night = start(["--mode", "mandate", "--input", "e mais 300 reais pra escola, a excursao", "--transcript", "test/fixtures/excursao-300.transcript.jsonl", "--now", "2026-09-23T23:00:00-03:00", "--json"], env);
+    const payload = night.payload();
+    expect(payload.executions).toHaveLength(1);
+    expect(payload.executions[0]).toMatchObject({ state: "awaiting_approval", escalation: { trigger: "outside_hours" }, receipt_ids: [] });
+    expect(payload.reply).not.toMatch(/paguei|recibo/i);
+    expect(receiptLines(night.stderr)).toEqual([]);
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/reply-language.test.ts

@@ -0,0 +1,95 @@
+/**
+ * The request the Anthropic provider actually sends, captured at `fetch`, for
+ * one turn in each language (docs/OPEN_QUESTIONS.md §64). The real-model run
+ * of 9a5383e answered five English requests out of five in Portuguese, with a
+ * `## Language` rule in the system prompt. What these requests show: the
+ * system prompt is the file, the person's words arrive untouched, and the
+ * last user-role message the model reads before it replies is a tool result
+ * full of Portuguese data. So "the language of the person's latest message"
+ * was a rule the context argued against on every turn that used a tool. The
+ * loop now reads the language of what the person typed and states it in the
+ * system prompt of every step of that turn.
+ */
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fixedClock, type Execution } from "@codespar/agent-core";
+import { setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+interface SentRequest {
+  system: string;
+  messages: Array<{ role: string; content: unknown }>;
+}
+
+function message(content: unknown[], stop: string) {
+  return { id: "msg_test", type: "message", role: "assistant", model: "claude-sonnet-5", content, stop_reason: stop, stop_sequence: null, usage: { input_tokens: 1, output_tokens: 1 } };
+}
+
+/** The model's side, scripted: read the bills, then answer. Every request body is kept. */
+function scriptedAnthropic(): SentRequest[] {
+  const sent: SentRequest[] = [];
+  const answers = [message([{ type: "tool_use", id: "toolu_1", name: "list_bills", input: {} }], "tool_use"), message([{ type: "text", text: "ok" }], "end_turn")];
+  vi.stubGlobal("fetch", async (_url: unknown, init?: { body?: unknown }) => {
+    sent.push(JSON.parse(String(init?.body)) as SentRequest);
+    const body = answers[Math.min(sent.length - 1, answers.length - 1)];
+    return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+  });
+  return sent;
+}
+
+function open(): Setup {
+  return setup(agent, {
+    mode: "human",
+    rail: "stub",
+    provider: "anthropic",
+    env: { ANTHROPIC_API_KEY: "sk-ant-test-not-a-key" },
+    runsDir: mkdtempSync(join(tmpdir(), "bills-lang-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-lang-state-")),
+    now: fixedClock("2026-09-28T14:00:00-03:00"),
+    say: () => undefined,
+  });
+}
+
+async function oneTurn(text: string): Promise<SentRequest[]> {
+  const sent = scriptedAnthropic();
+  const s = open();
+  try {
+    const loop = s.makeLoop(s.makeRuntime(), async (e: Execution) => e);
+    await loop.turn(text);
+  } finally {
+    s.close();
+  }
+  return sent;
+}
+
+const PROMPT = readFileSync(join(agent.dir, "SYSTEM_PROMPT.md"), "utf8");
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("the reply language travels in the request, not only in the prompt", () => {
+  it("an English turn: every request of the turn states English, and the person's words arrive as typed", async () => {
+    const sent = await oneTurn("pay the cleaner for September, please");
+    expect(sent).toHaveLength(2);
+    for (const request of sent) {
+      expect(request.system.startsWith(PROMPT)).toBe(true);
+      expect(request.system).toMatch(/wrote their last message in English\. Write your reply in English/);
+      expect(request.messages[0]).toEqual({ role: "user", content: "pay the cleaner for September, please" });
+    }
+    // What the model reads last before it answers: a user-role tool result, in Portuguese.
+    const last = sent[1]!.messages.at(-1)!;
+    expect(last.role).toBe("user");
+    expect(JSON.stringify(last.content)).toContain("mensalidade outubro");
+  });
+
+  it("a Portuguese turn states Brazilian Portuguese", async () => {
+    const sent = await oneTurn("pague a escola de outubro");
+    for (const request of sent) expect(request.system).toMatch(/wrote their last message in Brazilian Portuguese\. Write your reply in Brazilian Portuguese/);
+  });
+
+  it("a turn whose language cannot be read adds nothing, and the prompt's own default stands", async () => {
+    const sent = await oneTurn("ok");
+    for (const request of sent) expect(request.system).toBe(PROMPT);
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/rerun-and-missing-transcript.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Two refusals and one replay that need a real process: `rerun` on a run that
+ * stopped at `awaiting_approval`, and `start --transcript` on a file that is
+ * not there.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { loadAdversarialCase, runAdversarialCase } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+function run(command: string, args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, [BIN, command, ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+interface RerunReport {
+  same_states: boolean;
+  original: string[];
+  rerun: string[];
+}
+
+/**
+ * A rerun recomputes every decision of the core and takes the person's from
+ * the recording. Where the recording holds none, because nobody decided, the
+ * rerun decides nothing either.
+ */
+describe("npm run rerun <run-id> on a run that stopped at awaiting_approval", () => {
+  const LEFT = "1 execution(s) left in awaiting_approval, as the original left it";
+
+  it("replays an adversarial case that only escalates to the same open approval", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-open-"));
+    const env = { BILLS_STATE_DIR: join(runsDir, "state"), BILLS_RUNS_DIR: runsDir };
+    const original = await runAdversarialCase(agent, loadAdversarialCase(agent, "false-authority"), { runsDir });
+    expect(original.ok).toBe(true);
+    expect(original.states).toEqual(["awaiting_approval"]);
+
+    const out = run("rerun", [original.run_id, "--json"], env);
+    expect(out.stderr).not.toContain("DIFFERS");
+    expect(out.code).toBe(0);
+    const report = JSON.parse(out.stdout.trim()) as RerunReport;
+    expect(report.same_states).toBe(true);
+    expect(report.original).toEqual(["awaiting_approval"]);
+    expect(report.rerun).toEqual(["awaiting_approval"]);
+    expect(out.stderr).toContain(`rerun ok: 1 transition(s), same sequence as ${original.run_id}; ${LEFT}`);
+  });
+
+  it("replays a one-shot nobody decided to the same open approval", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-rerun-open-"));
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+    const left = run("start", ["--input", "pague a escola de outubro", "--json"], env);
+    expect(left.code).toBe(0);
+    const { run_id } = JSON.parse(left.stdout.trim()) as { run_id: string };
+
+    const out = run("rerun", [run_id, "--json"], env);
+    expect(out.code).toBe(0);
+    expect((JSON.parse(out.stdout.trim()) as RerunReport).rerun).toEqual(["awaiting_approval"]);
+    expect(out.stderr).toContain(LEFT);
+  });
+
+  it("still replays the decision of a run somebody decided, and says nothing was left open", () => {
+    for (const [flag, last] of [
+      ["--approve", "settled"],
+      ["--deny", "denied"],
+    ] as const) {
+      const stateDir = mkdtempSync(join(tmpdir(), "bills-rerun-decided-"));
+      const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+      const decided = run("start", ["--input", "pague a escola de outubro", flag, "--json"], env);
+      const { run_id } = JSON.parse(decided.stdout.trim()) as { run_id: string };
+
+      const out = run("rerun", [run_id, "--json"], env);
+      expect(out.code).toBe(0);
+      const report = JSON.parse(out.stdout.trim()) as RerunReport;
+      expect(report.same_states).toBe(true);
+      expect(report.rerun.at(-1)).toBe(last);
+      expect(out.stderr).toContain("rerun ok");
+      expect(out.stderr).not.toContain("left in awaiting_approval, as the original");
+    }
+  });
+});
+
+describe("npm start -- --transcript <a file that is not there>", () => {
+  it("refuses it by its path, with no stack, and opens no run", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-no-transcript-"));
+    const runsDir = join(stateDir, "runs");
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
+    const missing = join(stateDir, "nowhere.transcript.jsonl");
+
+    // A path that does not exist, and one that exists and is a directory.
+    for (const path of [missing, stateDir]) {
+      const out = run("start", ["--input", "pague a escola de outubro", "--provider", "replay", "--transcript", path, "--json"], env);
+      expect(out.code).toBe(1);
+      expect(out.stdout).toBe("");
+      expect(out.stderr.trim()).toBe(`no transcript at ${path}`);
+      expect(out.stderr).not.toMatch(/ENOENT|EISDIR/);
+      expect(out.stderr).not.toMatch(/^\s+at /m);
+    }
+    expect(existsSync(runsDir) ? readdirSync(runsDir) : []).toEqual([]);
+  });
+
+  it("still replays a transcript that is there", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-transcript-"));
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+    const recorded = join(AGENT_DIR, "evals", "adversarial", "false-authority.transcript.jsonl");
+    const out = run("start", ["--input", loadAdversarialCase(agent, "false-authority").input, "--mode", "mandate", "--provider", "replay", "--transcript", recorded, "--json"], env);
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain(`replaying ${recorded}`);
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/rerun-world-events.test.ts

@@ -0,0 +1,55 @@
+/**
+ * A rerun replays the model's side and the person's decisions. What the world
+ * did in the original (the mandate revoked mid-run, a rail that answered
+ * "uncertain") is not replayed, and a rerun that ignored it paid what the
+ * original denied and reported a run that DIFFERS. It refuses by name.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { loadScenario, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+function rerun(runsDir: string, args: string[]) {
+  const result = spawnSync(process.execPath, [BIN, "rerun", ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", BILLS_RUNS_DIR: runsDir, BILLS_STATE_DIR: join(runsDir, "state") },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+describe("npm run rerun <run-id> on a run the world interfered with", () => {
+  it.each(["human", "mandate"] as const)("mandate-revoked [%s]: names the revocation and the uncertain answer, and replays nothing", async (mode) => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-world-"));
+    const original = await runScenario(agent, loadScenario(agent, "mandate-revoked"), { mode, rail: "stub", runsDir });
+    expect(original.executions.map((e) => e.state)).toEqual(["settled", "settled", "denied"]);
+    const NAMED = `runs/${original.run_id} cannot be compared with a rerun: it met an uncertain answer from the rail, and a mandate that was revoked, which a rerun does not replay`;
+
+    const out = rerun(runsDir, [original.run_id]);
+    expect(out.code).toBe(1);
+    expect(out.stderr.trim().split("\n").at(-1)).toBe(NAMED);
+    expect(out.stderr).not.toContain("DIFFERS");
+    expect(out.stdout).toBe("");
+
+    const asJson = rerun(runsDir, [original.run_id, "--json"]);
+    expect(asJson.code).toBe(1);
+    expect(JSON.parse(asJson.stdout.trim())).toEqual({ run_id: original.run_id, error: NAMED, not_replayed: ["an uncertain answer from the rail", "a mandate that was revoked"] });
+    // Nothing was replayed: the runs folder holds the original and no rerun of it.
+    expect(readdirSync(runsDir).filter((entry) => entry.startsWith("run_"))).toEqual([original.run_id]);
+  });
+
+  it("a run the world left alone is still replayed", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-world-"));
+    const original = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "human", rail: "stub", runsDir });
+    const out = rerun(runsDir, [original.run_id]);
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain("rerun ok");
+  });
+});

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

@@ -44,7 +44,7 @@
     {
       "name": "list_bills",
       "effect": "read",
-      "description": "The bills of the current month: payee alias, name, amount in BRL cents, due date and whether it was already paid in this mandate window. Read-only.",
+      "description": "The bills of the current month: payee alias, name, amount in BRL cents, due date, days until it falls due (negative once past) and whether it was already paid in this mandate window, plus `today`, the only date you know. Read-only.",
       "input_schema": { "type": "object", "properties": {} }
     }
   ]

package/templates/bills-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/bills-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/bills-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/bills-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/bills-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) {