@codespar/cli 0.18.0 → 0.20.0

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

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"
   }