@codespar/cli 0.18.0 → 0.20.0

package/templates/bills-agent/agents/bills-agent/test/cli.test.ts

@@ -3,11 +3,13 @@
  * else, the restart in `executing` followed by `resume`, and `rerun`.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 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;
@@ -53,6 +55,37 @@ describe("npm start -- --input ... --json", () => {
     expect(out.code).toBe(1);
     expect(out.stdout).toBe("");
     expect(out.stderr).toContain("csk_test_");
+    expect(out.stderr).toContain("a live key is refused");
+  });
+});
+
+// #50: no key, the placeholder and a live key are three mistakes with three fixes, and each refusal names the .env this agent reads,
+// as the person would type it from where they ran npm (INIT_CWD): the repository root, here.
+describe("a key the kit cannot use says which mistake it is", () => {
+  const REPO = resolve(AGENT_DIR, "../..");
+  const cases = [
+    ["no key at all", "", /CODESPAR_API_KEY is not set: copy agents\/bills-agent\/\.env\.example to agents\/bills-agent\/\.env/],
+    ["the .env.example placeholder", "csk_test_your_key_here", /still the placeholder from \.env\.example \(csk_test_your_key_here\): replace it in agents\/bills-agent\/\.env/],
+    ["a live key", ["csk", "live", "0000000000"].join("_"), /a live key is refused/],
+  ] as const;
+  for (const [name, key, message] of cases) {
+    it(`consent with ${name}: its own sentence, exit 1, no stack trace`, () => {
+      const stateDir = mkdtempSync(join(tmpdir(), "bills-key-"));
+      const out = run("consent", ["--yes"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: key, INIT_CWD: REPO });
+      expect(out.code).toBe(1);
+      expect(out.stderr).toMatch(message);
+      expect(out.stderr).not.toMatch(/\n\s+at /);
+      if (key !== cases[2][1]) expect(out.stderr).not.toContain("live");
+    });
+  }
+
+  it("start --rail api names the same file, and without INIT_CWD the path is relative to where the command ran", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-key-"));
+    const fromRoot = run("start", ["--input", "pague a escola de outubro", "--rail", "api", "--json"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: "", INIT_CWD: REPO });
+    expect(fromRoot.code).toBe(1);
+    expect(fromRoot.stderr).toContain("copy agents/bills-agent/.env.example to agents/bills-agent/.env");
+    const here = run("start", ["--input", "pague a escola de outubro", "--rail", "api", "--json"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: "", INIT_CWD: "" });
+    expect(here.stderr).toContain("copy .env.example to .env");
   });
 });
 
@@ -145,6 +178,94 @@ describe("npm run rerun <run-id>", () => {
   });
 });
 
+/**
+ * The kit reads `CODESPAR_API_URL` and `CODESPAR_PROJECT_ID`; the CodeSpar CLI
+ * reads `CODESPAR_BASE_URL` and `CODESPAR_PROJECT`. A command that talks to
+ * the API stops when the two disagree; the stub rail reads neither.
+ */
+describe("the two names for the deployment and the project", () => {
+  const STAGING = "https://api.staging.codespar.dev";
+  const DISAGREE = { CODESPAR_API_URL: "https://api.codespar.dev", CODESPAR_BASE_URL: STAGING };
+  const scratch = () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-env-names-"));
+    return { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs"), CODESPAR_API_URL: "", CODESPAR_PROJECT_ID: "", CODESPAR_BASE_URL: "", CODESPAR_PROJECT: "" };
+  };
+  const ONE_SHOT = ["--input", "pague a escola de outubro", "--approve", "--json"];
+
+  it("with a key, two that disagree stop the command with both named, no stack, nothing run", () => {
+    // Not the placeholder; the underscore keeps it below the secret scan's key shape.
+    const out = run("start", ONE_SHOT, { ...scratch(), ...DISAGREE, CODESPAR_API_KEY: "csk_test_unit_0000" });
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("CODESPAR_API_URL=https://api.codespar.dev");
+    expect(out.stderr).toContain(`CODESPAR_BASE_URL=${STAGING}`);
+    expect(out.stderr).not.toMatch(/^\s+at /m);
+  });
+
+  it("on the stub rail the same disagreement is not read, and the run goes on", () => {
+    const out = run("start", ONE_SHOT, { ...scratch(), ...DISAGREE });
+    expect(out.code).toBe(0);
+    expect(out.stderr).not.toContain("disagree");
+  });
+
+  it("runs with only the CLI's names set", () => {
+    const out = run("start", ONE_SHOT, { ...scratch(), CODESPAR_BASE_URL: STAGING, CODESPAR_PROJECT: "prj_cli" });
+    expect(out.code).toBe(0);
+  });
+});
+
+/**
+ * `rerun` replays the model's side of a run. An adversarial case of
+ * `kind: events` has none: it drives rail deliveries and never asks the
+ * model, so its bundle holds no `transcript.jsonl`.
+ */
+describe("npm run rerun <run-id> on a run with no model turn", () => {
+  const NOTHING = "has no model turn in transcript.jsonl, so there is nothing to replay";
+
+  it("refuses the adversarial events case by name of what is missing, with no stack", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-adv-"));
+    const env = { BILLS_STATE_DIR: join(runsDir, "state"), BILLS_RUNS_DIR: runsDir };
+    const original = await runAdversarialCase(agent, loadAdversarialCase(agent, "webhook-replay"), { runsDir });
+    expect(original.ok).toBe(true);
+    expect(existsSync(join(runsDir, original.run_id, "transcript.jsonl"))).toBe(false);
+
+    const out = run("rerun", [original.run_id], env);
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain(`runs/${original.run_id} ${NOTHING}`);
+    expect(out.stderr).not.toContain("ENOENT");
+    expect(out.stderr).not.toMatch(/^\s+at /m);
+
+    // A script reading stdout gets the refusal as data, not an empty line.
+    const asJson = run("rerun", [original.run_id, "--json"], env);
+    expect(asJson.code).toBe(1);
+    expect(JSON.parse(asJson.stdout.trim())).toEqual({ run_id: original.run_id, error: `runs/${original.run_id} ${NOTHING}` });
+  });
+
+  it("refuses a transcript that is empty, or holds the person's turn and no step of the model", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-adv-"));
+    const env = { BILLS_STATE_DIR: join(runsDir, "state"), BILLS_RUNS_DIR: runsDir };
+    const original = await runAdversarialCase(agent, loadAdversarialCase(agent, "webhook-replay"), { runsDir });
+    const transcript = join(runsDir, original.run_id, "transcript.jsonl");
+    for (const content of ["", JSON.stringify({ kind: "user", text: "pague a escola de outubro" }) + "\n"]) {
+      writeFileSync(transcript, content);
+      const out = run("rerun", [original.run_id], env);
+      expect(out.code).toBe(1);
+      expect(out.stderr).toContain(NOTHING);
+      expect(out.stderr).not.toContain("rerun ok");
+    }
+  });
+
+  it("still replays an adversarial case that did ask the model", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-rerun-adv-"));
+    const original = await runAdversarialCase(agent, loadAdversarialCase(agent, "prompt-injection"), { runsDir });
+    expect(original.ok).toBe(true);
+    const out = run("rerun", [original.run_id], { BILLS_STATE_DIR: join(runsDir, "state"), BILLS_RUNS_DIR: runsDir });
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain("rerun ok");
+  });
+});
+
 describe("npm run check", () => {
   it("is green for the shipped agent and prints JSON with --json", () => {
     const out = run("check", ["--json"], {});
@@ -203,13 +324,20 @@ describe("partial failure of a multi-item execution, and rerun reproducing it",
     const runsDir = join(stateDir, "runs");
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir, BILLS_STUB_REFUSE: "+5511999990001" };
     const first = run("start", ["--input", "libera o lote do mes", "--transcript", "evals/adversarial/false-authority.transcript.jsonl", "--approve", "--json"], env);
-    expect(first.code).toBe(0);
+    // One attempt failed, so the execution is `failed` and the process says so.
+    expect(first.code).toBe(1);
     const payload = JSON.parse(first.stdout.trim()) as { run_id: string; executions: Array<{ state: string; receipt_ids: string[] }>; receipts: string[] };
     // Four bills, the SECOND refused by the rail. The execution closes `failed`
     // because one attempt failed, and the two bills after the refused one are
     // paid all the same: an attempt's outcome is that attempt's business.
     expect(payload.executions[0]?.state).toBe("failed");
     expect(payload.executions[0]?.receipt_ids).toHaveLength(3);
+    // Counted by payment, not by execution: three bills were paid and one failed, and the line says both.
+    expect((payload as unknown as { run_outcome: unknown }).run_outcome).toEqual({ settled: 3, failed: 1, declined: 0, already_paid: 0, open: 0 });
+    // #50: the rail's own code and message, verbatim, next to the reason — on stdout for a script, on stderr for a person.
+    const railError = (payload.executions[0] as unknown as { rail_error: unknown }).rail_error;
+    expect(railError).toMatchObject({ outcome: "failed", code: "psp_dispatch_failed", message: "stub: provider refused payee +5511999990001" });
+    expect(first.stderr).toContain("-> failed (rail_failed): psp_dispatch_failed — stub: provider refused payee +5511999990001");
     expect(payload.receipts).toHaveLength(3);
     const events = readFileSync(join(runsDir, payload.run_id, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; payload: { status?: string } });
     expect(events.filter((e) => e.type === "rail.outcome").map((e) => e.payload.status)).toEqual(["settled", "failed", "settled", "settled"]);

package/templates/bills-agent/agents/bills-agent/test/consent-money.test.ts

@@ -0,0 +1,25 @@
+/**
+ * The consent is what a person reads before signing a mandate, so its caps
+ * are money as a person writes it, not the minor units the API takes.
+ */
+import { describe, expect, it } from "vitest";
+import { STRINGS } from "../src/strings.js";
+
+describe("the consent summary says its amounts in reais", () => {
+  it("the three caps, in pt-BR and in English", () => {
+    expect(STRINGS["pt-BR"].consentCaps(250000, 600000, 7200000)).toBe("  teto por pagamento: R$ 2.500,00    teto do mês: R$ 6.000,00    vitalício: R$ 72.000,00");
+    expect(STRINGS.en.consentCaps(250000, 600000, 7200000)).toBe("  cap per payment: R$2,500.00    cap per month: R$6,000.00    lifetime: R$72,000.00");
+  });
+
+  it("the sandbox credit too", () => {
+    expect(STRINGS["pt-BR"].consentFunded(600000, "acc_1", "dep_1")).toBe("Sandbox creditado: R$ 6.000,00 em acc_1 (deposit dep_1).");
+    expect(STRINGS.en.consentFunded(600000, "acc_1", "dep_1")).toBe("Sandbox credited: R$6,000.00 to acc_1 (deposit dep_1).");
+  });
+
+  it("no line of the consent counts in cents", () => {
+    for (const locale of ["pt-BR", "en"] as const) {
+      const lines = [STRINGS[locale].consentCaps(250000, 600000, 7200000), STRINGS[locale].consentFunded(600000, "acc_1", "dep_1")];
+      for (const line of lines) expect(line).not.toMatch(/centavos|cents|250000|600000|7200000/);
+    }
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/dates-and-approval.test.ts

@@ -0,0 +1,98 @@
+/**
+ * What the first real-model runs showed (docs/OPEN_QUESTIONS.md §64): with no
+ * date of its own, the model called a bill due next week "venceu dia 05"; told
+ * both approval modes exist and not which one ran, it said a payment the
+ * titular approved needed "no extra approval". The tools now carry both facts.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { daysUntil, fixedClock, localDate, type Execution, type ToolContext } from "@codespar/agent-core";
+import { setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { codesparPay, listBills } from "../src/modules/pix-out.js";
+
+function open(mode: "human" | "mandate", now: string): Setup {
+  return setup(agent, {
+    mode,
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-dates-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-dates-state-")),
+    now: fixedClock(now),
+    say: () => undefined,
+  });
+}
+
+function context(s: Setup, decide: boolean): ToolContext {
+  return {
+    engine: s.engine,
+    onExecution: async (execution: Execution) => {
+      let current = execution;
+      if (decide && current.state === "awaiting_approval") current = s.engine.approve(current.id, { id: "usr_demo", channel: "terminal" });
+      if (current.state === "approved") current = await s.engine.execute(current.id);
+      return current;
+    },
+  };
+}
+
+describe("the calendar the model reads", () => {
+  it("localDate is the day in the timezone, not in UTC", () => {
+    // 23:30 in Sao Paulo on the 28th is already the 29th in UTC.
+    expect(localDate(new Date("2026-09-29T02:30:00Z"), "America/Sao_Paulo")).toBe("2026-09-28");
+    expect(localDate(new Date("2026-09-29T02:30:00Z"), "UTC")).toBe("2026-09-29");
+  });
+
+  it("daysUntil counts whole days, negative once past", () => {
+    expect(daysUntil("2026-09-28", "2026-10-05")).toBe(7);
+    expect(daysUntil("2026-10-05", "2026-10-05")).toBe(0);
+    expect(daysUntil("2026-10-06", "2026-10-05")).toBe(-1);
+  });
+
+  it("list_bills carries today, from the pinned clock, and days_until_due per bill", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      const out = (await listBills({}, context(s, false))) as { today: string; bills: Array<{ alias: string; due: string; days_until_due: number }> };
+      expect(out.today).toBe("2026-09-28");
+      const mercado = out.bills.find((b) => b.alias === "mercado")!;
+      expect(mercado.due).toBe("2026-10-05");
+      expect(mercado.days_until_due).toBe(7);
+    } finally {
+      s.close();
+    }
+  });
+});
+
+describe("codespar_pay says who approved, so the model does not guess", () => {
+  const PIX = { action: "pix", items: [{ payee: "mercado", amount_minor: 64000 }] };
+
+  it("a person's approval is `human`", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      expect(await codesparPay(PIX, context(s, true))).toMatchObject({ status: "settled", approved_by: "human" });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("nobody has approved an execution still waiting: `null`", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      expect(await codesparPay(PIX, context(s, false))).toMatchObject({ status: "awaiting_approval", approved_by: null });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("the signed allowance's approval is `mandate`", async () => {
+    const s = open("mandate", "2026-09-28T14:00:00-03:00");
+    try {
+      // Warm the payee so `new_beneficiary` does not send it to a person.
+      await s.kit.warmUp!(s, ["mercado"], { id: "usr_demo", channel: "terminal" });
+      expect(await codesparPay(PIX, context(s, false))).toMatchObject({ status: "settled", approved_by: "mandate" });
+    } finally {
+      s.close();
+    }
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/eval-runs.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `npm run eval` writes a proof bundle per case and per scenario run, dozens a
+ * pass. They go to `runs/eval/`, so `runs/` holds what the person ran, and
+ * `inspect` and `rerun` still find an eval run by its id.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+describe("npm run eval beside a person's own runs", () => {
+  const stateDir = mkdtempSync(join(tmpdir(), "bills-eval-runs-"));
+  const runsDir = join(stateDir, "runs");
+  const run = (command: string, args: string[]) => {
+    const result = spawnSync(process.execPath, [BIN, command, ...args], {
+      cwd: AGENT_DIR,
+      env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir },
+      encoding: "utf8",
+      timeout: 120_000,
+    });
+    return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+  };
+  let mine = "";
+  let evalRuns: string[] = [];
+
+  beforeAll(() => {
+    const own = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"]);
+    mine = (JSON.parse(own.stdout.trim()) as { run_id: string }).run_id;
+    expect(run("eval", []).code).toBe(0);
+    evalRuns = readdirSync(join(runsDir, "eval")).sort();
+  }, 120_000);
+
+  it("leaves runs/ with the person's run and one folder for the suite's", () => {
+    expect(readdirSync(runsDir).sort()).toEqual(["eval", mine].sort());
+    // 8 adversarial cases and 11 scenario runs.
+    expect(evalRuns).toHaveLength(19);
+    expect(evalRuns.some((id) => id.startsWith("run_adv_"))).toBe(true);
+  });
+
+  it("inspect finds an eval run by its id alone, and by eval/<id>", () => {
+    const id = evalRuns.find((r) => r.startsWith("run_adv_prompt-injection"))!;
+    for (const arg of [id, `eval/${id}`]) {
+      const out = run("inspect", [arg, "--json"]);
+      expect(out.code).toBe(0);
+      expect((JSON.parse(out.stdout.trim()) as { run: { run_id: string } }).run.run_id).toBe(id);
+    }
+    expect(run("inspect", [mine, "--json"]).code).toBe(0);
+  });
+
+  it("an unknown id lists the person's runs and counts the suite's, without listing them", () => {
+    const out = run("inspect", ["run_nope"]);
+    expect(out.code).toBe(1);
+    expect(out.stderr).toContain(`  ${mine}`);
+    expect(out.stderr).toContain(`19 more from \`npm run eval\` in ${join(runsDir, "eval")}`);
+    expect(out.stderr).not.toContain("run_adv_");
+    expect(out.stderr).not.toMatch(/^ {2}eval$/m);
+  });
+
+  it("the folder itself is not a run, and a path out of runs/ is not one either", () => {
+    for (const arg of ["eval", "eval/", "eval/../..", "../runs"]) {
+      const out = run("inspect", [arg]);
+      expect([arg, out.code]).toEqual([arg, 1]);
+      expect(out.stderr).toContain(`no proof bundle for run ${arg}`);
+      expect(out.stderr).not.toMatch(/^\s+at /m);
+    }
+  });
+
+  it("rerun replays an eval run by its id and leaves the rerun beside it, not among the person's", () => {
+    const id = evalRuns.find((r) => r.startsWith("run_adv_prompt-injection"))!;
+    const out = run("rerun", [id, "--json"]);
+    expect(out.code).toBe(0);
+    const report = JSON.parse(out.stdout.trim()) as { same_states: boolean; rerun_id: string };
+    expect(report.same_states).toBe(true);
+    expect(readdirSync(join(runsDir, "eval"))).toContain(report.rerun_id);
+    expect(readdirSync(runsDir).sort()).toEqual(["eval", mine].sort());
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/fixtures/excursao-300.transcript.jsonl

@@ -1,2 +1,2 @@
-{"kind":"assistant_step","tool_calls":[{"id":"tc_4","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":30000,"description":"excursao"}]}}]}
-{"kind":"assistant_step","reply":"Paguei R$ 300,00 para a Escola Aurora (excursao) dentro da alcada; o recibo esta no terminal."}
+{"kind":"assistant_step","tool_calls":[{"id":"tc_4","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":30000,"description":"excursão"}]}}]}
+{"kind":"assistant_step","reply":"Propus R$ 300,00 para a Escola Aurora (excursão). O resultado está no terminal."}

package/templates/bills-agent/agents/bills-agent/test/fixtures/material-400.transcript.jsonl

@@ -1,2 +1,2 @@
 {"kind":"assistant_step","tool_calls":[{"id":"tc_1","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":40000,"description":"material"}]}}]}
-{"kind":"assistant_step","reply":"Propus R$ 400,00 para a Escola Aurora (material). Como e o primeiro pagamento a esse favorecido, o mandato pediu sua aprovacao."}
+{"kind":"assistant_step","reply":"Propus R$ 400,00 para a Escola Aurora (material). Como é o primeiro pagamento a esse favorecido, o mandato pediu sua aprovação."}

package/templates/bills-agent/agents/bills-agent/test/locale.test.ts

@@ -0,0 +1,161 @@
+/**
+ * #64 on the approval path: the locale changes what the titular READS and
+ * nothing about what their answer DECIDES. The same answer to the pt-BR
+ * question and to the English one ends in the same state, and the approval
+ * artifact names the same approver.
+ *
+ * And the resolution, end to end: `--locale` beats `agent.yaml`, which beats
+ * the default, and the run's bundle records the locale it ran in.
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fixedClock, type Locale } from "@codespar/agent-core";
+import { handleExecution, parseApproval, setup, type Setup } 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");
+const APPROVER = { id: "usr_demo_titular", channel: "terminal" };
+/** Every answer the `[s/N]` parser has a rule for, both languages, plus what falls through to no. */
+const ANSWERS = ["s", "sim", "y", "yes", " SIM ", "Yes", "n", "nao", "não", "no", "", "talvez", "si"];
+
+function open(locale: Locale | undefined, dir = AGENT_DIR): Setup {
+  return setup(dir === AGENT_DIR ? agent : { ...agent, dir }, {
+    mode: "human",
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-locale-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-locale-state-")),
+    now: fixedClock("2026-09-23T14:00:00-03:00"),
+    say: () => undefined,
+    ...(locale ? { locale } : {}),
+  });
+}
+
+/** Proposes one payment and answers the approval question with `answer`; returns the final state, the question asked and the console. */
+async function decideOnce(locale: Locale, answer: string) {
+  const s = open(locale);
+  const asked: string[] = [];
+  const said: string[] = [];
+  try {
+    const draft = await s.engine.draft({ items: [{ payee: "escola", amount: 185000, description: "mensalidade de outubro" }] });
+    if (!draft.ok) throw new Error(draft.reason);
+    const final = await handleExecution(draft.execution, {
+      setup: s,
+      approver: APPROVER,
+      ask: async (q) => {
+        asked.push(q);
+        return answer;
+      },
+      say: (l) => void said.push(l),
+    });
+    const approvers = s.bundle.readApprovals().map((a) => a.approver);
+    return { state: final.state, asked, said, approvers };
+  } finally {
+    s.close();
+  }
+}
+
+describe("the approval question decides the same in both locales", () => {
+  it.each(ANSWERS)("answer %j", async (answer) => {
+    const pt = await decideOnce("pt-BR", answer);
+    const en = await decideOnce("en", answer);
+    // What was shown differs...
+    expect(pt.asked).toEqual(["  Aprovar este pagamento? [s/N] "]);
+    expect(en.asked).toEqual(["  Approve this payment? [y/N] "]);
+    // ...and what was decided does not.
+    expect(en.state).toBe(pt.state);
+    expect(en.approvers).toEqual(pt.approvers);
+    expect(pt.state).toBe(parseApproval(answer) === "approve" ? "settled" : "denied");
+  });
+
+  it("prints the execution in the run's locale, accents included", async () => {
+    const pt = await decideOnce("pt-BR", "s");
+    const en = await decideOnce("en", "y");
+    expect(pt.said.join("\n")).toContain("execução exe_");
+    expect(pt.said.join("\n")).toContain("total (calculado pelo core): R$ 1.850,00");
+    expect(pt.said.join("\n")).toMatch(/recibo: /);
+    expect(en.said.join("\n")).toContain("execution exe_");
+    expect(en.said.join("\n")).toContain("total (computed by the core): R$1,850.00");
+    expect(en.said.join("\n")).toMatch(/receipt: /);
+  });
+});
+
+describe("which locale a run speaks", () => {
+  function copyWithLocale(locale: string | undefined): string {
+    const dir = mkdtempSync(join(tmpdir(), "bills-locale-agent-"));
+    cpSync(AGENT_DIR, dir, { recursive: true, filter: (src) => !/node_modules|\/runs|\.codespar/.test(src) });
+    const yaml = readFileSync(join(dir, "agent.yaml"), "utf8").replace(/^locale:.*\n/m, locale ? `locale: ${locale}\n` : "");
+    writeFileSync(join(dir, "agent.yaml"), yaml);
+    return dir;
+  }
+
+  it("is --locale, else agent.yaml's locale, else pt-BR; and the bundle records it", () => {
+    const cases: Array<[string | undefined, Locale | undefined, Locale]> = [
+      [undefined, undefined, "pt-BR"],
+      ["en", undefined, "en"],
+      ["en", "pt-BR", "pt-BR"],
+      ["pt-BR", "en", "en"],
+    ];
+    for (const [manifest, flag, expected] of cases) {
+      const s = open(flag, copyWithLocale(manifest));
+      try {
+        expect(s.locale).toBe(expected);
+        expect(s.bundle.readMeta()?.["locale"]).toBe(expected);
+        expect(s.strings).toBe(agent.kit.strings[expected]);
+      } finally {
+        s.close();
+      }
+    }
+  });
+
+  function run(args: string[]) {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-locale-cli-"));
+    const result = spawnSync(NODE, [BIN, "start", ...args], {
+      cwd: AGENT_DIR,
+      env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") },
+      encoding: "utf8",
+      timeout: 60_000,
+    });
+    const runs = join(stateDir, "runs");
+    let meta: Record<string, unknown> | undefined;
+    try {
+      const [dir] = readdirSync(runs);
+      meta = JSON.parse(readFileSync(join(runs, dir!, "run.json"), "utf8")) as Record<string, unknown>;
+    } catch {
+      meta = undefined;
+    }
+    return { code: result.status, stdout: result.stdout, stderr: result.stderr, meta };
+  }
+
+  it("`npm start -- --locale en` prints the code's lines in English and pays the same", () => {
+    const pt = run(["--input", "pague a escola de outubro", "--approve", "--json"]);
+    const en = run(["--input", "pague a escola de outubro", "--approve", "--json", "--locale", "en"]);
+    expect(pt.code).toBe(0);
+    expect(en.code).toBe(0);
+    expect(pt.stderr).toContain("execução");
+    expect(pt.stderr).toContain("calculado pelo core");
+    expect(en.stderr).toContain("execution");
+    expect(en.stderr).toContain("computed by the core");
+    expect(en.stderr).not.toContain("execução");
+    expect(pt.meta?.["locale"]).toBe("pt-BR");
+    expect(en.meta?.["locale"]).toBe("en");
+    // The machine output is the same contract in both: same states, same receipts, no locale-dependent field.
+    const shape = (o: string) => {
+      const p = JSON.parse(o) as { executions: Array<{ state: string; total_minor: number; receipt_ids: string[] }> };
+      return p.executions.map((e) => ({ state: e.state, total_minor: e.total_minor, receipts: e.receipt_ids.length }));
+    };
+    expect(shape(en.stdout)).toEqual(shape(pt.stdout));
+  });
+
+  it("an unknown --locale is a usage error, before anything runs", () => {
+    const out = run(["--input", "pague a escola de outubro", "--locale", "es"]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--locale must be pt-BR or en");
+    expect(out.meta).toBeUndefined();
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/mandate-state.test.ts

@@ -0,0 +1,108 @@
+/**
+ * What the kit says about a mandate after it was revoked: `inspect` on the
+ * run that met the revocation, and the consent that replaces the mandate.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { ApiClient } from "@codespar/sdk";
+import { ProofBundle, loadMandate, type Mandate } from "@codespar/agent-core";
+import { assembleTimeline, loadScenario, renderText, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { runEmbeddedConsent } from "../src/modules/embedded-consent.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+
+describe("npm run inspect on the run that met a revocation", () => {
+  it("the header says revoked, from the source that answered, and no longer says active", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-inspect-revoked-"));
+    const run = await runScenario(agent, loadScenario(agent, "mandate-revoked"), { mode: "human", runsDir });
+    const text = renderText(assembleTimeline(ProofBundle.open(runsDir, run.run_id)!));
+    const header = text.split("\n")[2]!;
+
+    // The line two below it, which the header used to contradict.
+    expect(text).toMatch(/was revoked \(source: stub\)/);
+    expect(header).toMatch(/^ {2}mandate revoked \(source: stub, \d\d:\d\d:\d\d; active in the snapshot at the start of the run\), expires /);
+    expect(text).not.toMatch(/^ {2}mandate active,/m);
+  });
+
+  it("a run that met none still says active", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-inspect-active-"));
+    const run = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "human", runsDir });
+    expect(renderText(assembleTimeline(ProofBundle.open(runsDir, run.run_id)!)).split("\n")[2]).toMatch(/^ {2}mandate active, expires /);
+  });
+});
+
+/** The four calls a consent makes, answered as the sandbox answers them; `status` is what `GET /v1/mandates/{id}` says of the mandate the file already holds. */
+function fakeApi(example: Mandate, status: string | Error): { api: ApiClient; reads: string[] } {
+  const reads: string[] = [];
+  const api = {
+    post: async (path: string) => {
+      if (path === "/v1/consents/init") return { token: "tok_test", expires_at: "2026-09-23T18:30:00.000Z" };
+      if (path === "/v1/consents/{token}/submit") {
+        return {
+          mandate_id: "cm_new",
+          signature: "0".repeat(64),
+          mandate: { consumer_id: example.consumer_id, agent_id: example.agent_id, purpose: example.purpose, currency: "BRL", cap_minor: example.cap_minor, per_tx_cap_minor: example.per_tx_cap_minor, merchant_pin_kind: "pix-key", merchant_allowlist: example.beneficiaries.map((b) => b.payee), expires_at: 1821312000 },
+        };
+      }
+      return { amount_minor: 600000, account: "acc_test", deposit_id: "dep_test" };
+    },
+    get: async (_path: string, options: { path: { id: string } }) => {
+      reads.push(options.path.id);
+      if (status instanceof Error) throw status;
+      return { status, expires_at: "2027-09-23T00:00:00.000Z", org_paused: false };
+    },
+  };
+  return { api: api as unknown as ApiClient, reads };
+}
+
+describe("npm run consent", () => {
+  const example = loadMandate(join(AGENT_DIR, "mandate.example.json"));
+  const NOT_YET = "O mandato ainda não existe.";
+
+  async function consent(options: { previous?: Mandate; status?: string | Error; locale?: "pt-BR" | "en" }) {
+    const dir = mkdtempSync(join(tmpdir(), "bills-consent-"));
+    const mandatePath = join(dir, ".codespar", "mandate.json");
+    if (options.previous) {
+      mkdirSync(join(dir, ".codespar"));
+      writeFileSync(mandatePath, JSON.stringify(options.previous));
+    }
+    const said: string[] = [];
+    const { api, reads } = fakeApi(example, options.status ?? "active");
+    const mandate = await runEmbeddedConsent({ api, example, mandatePath, say: (l) => said.push(l), confirm: async () => true, now: () => new Date("2026-09-23T18:00:00.000Z"), ...(options.locale ? { locale: options.locale } : {}) });
+    return { said, reads, mandate, mandatePath, file: relative(process.cwd(), mandatePath) };
+  }
+
+  it("with no mandate in the file, says it does not exist yet and reads no status", async () => {
+    const out = await consent({});
+    expect(out.said[1]).toContain(NOT_YET);
+    expect(out.reads).toEqual([]);
+  });
+
+  it("after a revocation, names the revoked mandate the file holds instead of saying none exists", async () => {
+    const previous = { ...example, id: "cm_old" };
+    const out = await consent({ previous, status: "revoked" });
+    expect(out.reads).toEqual(["cm_old"]);
+    expect(out.said[1]).toBe(`Já existe um mandato em ${out.file}: cm_old, revogado na API. Este é o consentimento de um mandato novo, que passa a ser o do arquivo (sandbox):`);
+    expect(out.said.join("\n")).not.toContain(NOT_YET);
+    // And the file is the new mandate's afterwards, as the line said.
+    expect((JSON.parse(readFileSync(out.mandatePath, "utf8")) as { id: string }).id).toBe("cm_new");
+    expect(out.mandate.id).toBe("cm_new");
+  });
+
+  it("says the state the API answers, whatever it is, and says so when it does not answer", async () => {
+    const previous = { ...example, id: "cm_old" };
+    expect((await consent({ previous, status: "active" })).said[1]).toContain("cm_old, ativo na API.");
+    expect((await consent({ previous, status: "paused" })).said[1]).toContain("cm_old, pausado na API.");
+    expect((await consent({ previous, status: new Error("ECONNRESET") })).said[1]).toContain("cm_old, com estado que a API não respondeu.");
+    expect((await consent({ previous, status: "revoked", locale: "en" })).said[1]).toContain("already holds a mandate: cm_old, revoked on the API.");
+  });
+
+  it("a file it cannot read does not stop a new consent", async () => {
+    const out = await consent({ previous: { id: "not a mandate" } as unknown as Mandate });
+    expect(out.said[1]).toContain(NOT_YET);
+    expect(out.mandate.id).toBe("cm_new");
+  });
+});