@codespar/cli 0.18.1 → 0.21.0

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");
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/refused-before-draft.test.ts

@@ -0,0 +1,81 @@
+/**
+ * A request made under a revoked mandate creates no execution: the engine
+ * refuses it before a draft. The terminal used to say nothing about it (the
+ * recorded reply even says "see the result on the terminal"), and only
+ * `inspect` showed the event. Driven as real processes, over a scratch state
+ * whose stub mandate is revoked between two runs.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync } 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";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const SCHOOL = "pague a escola de outubro";
+const BASE_ENV = { ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "2026-10-07T14:00:00-03:00" };
+
+function run(args: string[], env: Record<string, string>) {
+  const result = spawnSync(process.execPath, [BIN, "start", ...args], { cwd: AGENT_DIR, env: { ...process.env, ...BASE_ENV, ...env }, encoding: "utf8", timeout: 60_000 });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/** A scratch state holding one settled payment, with the stub mandate then revoked: what `codespar mandate revoke` leaves behind. */
+function revoked(label: string): Record<string, string> {
+  const stateDir = mkdtempSync(join(tmpdir(), `bills-refused-${label}-`));
+  const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+  const first = run(["--input", SCHOOL, "--approve", "--json"], env);
+  expect(first.code).toBe(0);
+  const mandateId = (JSON.parse(first.stdout.trim()) as { mandate_id: string }).mandate_id;
+  const db = new DatabaseSync(join(stateDir, "state.db"));
+  db.prepare("INSERT OR REPLACE INTO stub_mandate_status (mandate_id, status, reason, updated_at) VALUES (?, 'revoked', 'revoked by the test', ?)").run(mandateId, new Date().toISOString());
+  db.close();
+  return env;
+}
+
+describe("a request under a revoked mandate, one-shot", () => {
+  it("names the refusal and its reason on the terminal, counts it, and exits 1", () => {
+    const out = run(["--input", SCHOOL, "--approve"], revoked("text"));
+    expect(out.stderr).toContain("-> refused_before_draft (mandate_revoked)");
+    expect(out.stdout).toContain("resultado deste run: 0 liquidada(s), 1 com falha ou recusada(s)");
+    expect(out.code).toBe(1);
+  });
+
+  it("carries the same refusal in --json, with no execution", () => {
+    const out = run(["--input", SCHOOL, "--approve", "--json"], revoked("json"));
+    const payload = JSON.parse(out.stdout.trim()) as { executions: unknown[]; run_outcome: { failed: number }; refused_before_draft: Array<{ reason: string; detail: string }> };
+    expect(payload.executions).toHaveLength(0);
+    expect(payload.refused_before_draft).toHaveLength(1);
+    expect(payload.refused_before_draft[0]).toMatchObject({ reason: "mandate_revoked" });
+    expect(payload.refused_before_draft[0]?.detail).not.toBe("");
+    expect(payload.run_outcome.failed).toBe(1);
+    expect(out.code).toBe(1);
+  });
+});
+
+describe("a request under a revoked mandate, interactive", () => {
+  it("names the refusal under the turn that made it", async () => {
+    const env = revoked("interactive");
+    const out = await new Promise<{ stdout: string; stderr: string }>((done, fail) => {
+      const child = spawn(process.execPath, [BIN, "start", "--transcript", "scenarios/mandate-revoked.transcript.jsonl"], { cwd: AGENT_DIR, env: { ...process.env, ...BASE_ENV, ...env } });
+      let stdout = "";
+      let stderr = "";
+      let typed = false;
+      // Typed when the prompt shows: readline drops a line that arrives before the question.
+      const feed = () => {
+        if (!typed && stderr.includes("> ")) {
+          typed = true;
+          child.stdin.end(SCHOOL + "\n");
+        }
+      };
+      child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+      child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); feed(); });
+      child.on("error", fail);
+      child.on("close", () => done({ stdout, stderr }));
+    });
+    expect(out.stderr).toContain("-> refused_before_draft (mandate_revoked)");
+    expect(out.stdout).toContain("1 com falha ou recusada(s)");
+  });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * Issue #60 on the one-off payment: `codespar_pay` says `paid: true` only for
+ * a payment this call made. A bill's attempt id comes from its own execution,
+ * so the rail cannot replay one at dispatch today; the rail is scripted to
+ * answer the way the API answers a repeat, so the report is pinned before
+ * anything makes that reachable.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fixedClock, type Execution, type StubRail, type ToolContext } from "@codespar/agent-core";
+import { setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { codesparPay } from "../src/modules/pix-out.js";
+
+const APPROVER = { id: "usr_demo", channel: "terminal" };
+
+function open(): Setup {
+  return setup(agent, {
+    mode: "human",
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-replay-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-replay-state-")),
+    now: fixedClock("2026-09-23T14:00:00-03:00"),
+    say: () => undefined,
+  });
+}
+
+function context(s: Setup): ToolContext {
+  return {
+    engine: s.engine,
+    onExecution: async (execution: Execution) => {
+      let current = execution;
+      if (current.state === "awaiting_approval") current = s.engine.approve(current.id, APPROVER);
+      if (current.state === "approved") current = await s.engine.execute(current.id);
+      return current;
+    },
+  };
+}
+
+const PIX = { action: "pix", items: [{ payee: "mercado", amount_minor: 64000, description: "compras da semana" }] };
+
+describe("codespar_pay: a settlement this call did not make is not reported as paid (#60)", () => {
+  it("a payment this call made is paid, and not replayed", async () => {
+    const s = open();
+    try {
+      const result = await codesparPay(PIX, context(s));
+      expect(result).toMatchObject({ status: "settled", paid: true, replayed: false });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("a payment the rail answered from an earlier presentation is settled, replayed, and not paid by this call", async () => {
+    const s = open();
+    try {
+      const rail = s.rail as StubRail;
+      const pay = rail.pay.bind(rail);
+      rail.pay = async (payment) => {
+        const outcome = await pay(payment);
+        return outcome.status === "settled" ? { ...outcome, replayed: true } : outcome;
+      };
+      const result = (await codesparPay(PIX, context(s))) as { status: string; paid: boolean; replayed: boolean; receipt_ids: string[] };
+      expect(result).toMatchObject({ status: "settled", paid: false, replayed: true });
+      expect(result.receipt_ids).toHaveLength(1);
+
+      const oneShot = agent.kit.oneShotPayload({ setup: s, reply: "", toolCalls: [], executions: s.engine.list(), startedAt: 0 }) as { executions: Array<{ state: string; replayed: boolean }> };
+      expect(oneShot.executions).toEqual([expect.objectContaining({ state: "settled", replayed: true })]);
+      expect(agent.kit.describeExecution(s.engine.list()[0]!, s).join("\n")).toContain("esta execução não moveu dinheiro");
+    } finally {
+      s.close();
+    }
+  });
+});

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);
+  });
+});