@codespar/cli 0.18.1 → 0.21.0

package/templates/bills-agent/agents/bills-agent/src/modules/embedded-consent.ts

@@ -13,14 +13,17 @@
  * bundle, never committed.
  */
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, relative } from "node:path";
 import type { ApiClient } from "@codespar/sdk";
-import { MandateSchema, windowCap, type Mandate, describeApiError } from "@codespar/agent-core";
+import { ApiMandateStatusSource, MandateSchema, windowCap, type Locale, type Mandate, describeApiError } from "@codespar/agent-core";
+import { STRINGS } from "../strings.js";
 
 export interface ConsentOptions {
   api: ApiClient;
   example: Mandate;
   mandatePath: string;
+  /** The language of the lines below. Default pt-BR. */
+  locale?: Locale;
   /** Where to write the lines the person reads. */
   say: (line: string) => void;
   /** Asks the titular to authorize. Returns true on yes. */
@@ -37,8 +40,27 @@ export function loadLocalMandate(path: string): Mandate | undefined {
   return MandateSchema.parse(JSON.parse(readFileSync(path, "utf8")));
 }
 
+/** The words for what the API says of the mandate the file already holds; `unknown` is the API not answering. */
+const PREVIOUS = {
+  active: "consentPreviousActive",
+  paused: "consentPreviousPaused",
+  revoked: "consentPreviousRevoked",
+  expired: "consentPreviousExpired",
+  unknown: "consentPreviousUnknown",
+} as const;
+
+/** The mandate the file holds before this consent, when it holds one this kit can read. A file it cannot read is not a reason to stop a new consent. */
+function previousMandate(path: string): Mandate | undefined {
+  try {
+    return loadLocalMandate(path);
+  } catch {
+    return undefined;
+  }
+}
+
 export async function runEmbeddedConsent(options: ConsentOptions): Promise<Mandate> {
   const { api, example, say } = options;
+  const text = STRINGS[options.locale ?? "pt-BR"];
   const now = options.now ?? (() => new Date());
   const consumerId = options.consumerId ?? example.consumer_id;
 
@@ -54,20 +76,24 @@ export async function runEmbeddedConsent(options: ConsentOptions): Promise<Manda
         merchant_allowlist: example.beneficiaries.map((b) => b.payee),
         merchant_pin_kind: "pix-key",
         ...(example.periodic_cap ? { periodic_cap: example.periodic_cap } : {}),
-        display_name: "bills-agent: contas do mes",
-        intent_note: `Pagar as contas do mes aos favorecidos nomeados: ${example.beneficiaries.map((b) => b.name).join(", ")}.`,
+        display_name: "bills-agent: contas do mês",
+        intent_note: `Pagar as contas do mês aos favorecidos nomeados: ${example.beneficiaries.map((b) => b.name).join(", ")}.`,
       },
       surface: "partner",
     },
   });
 
+  // A consent after a revocation is not a first one: the file holds the mandate it replaces, and the API says what became of it.
+  const previous = previousMandate(options.mandatePath);
+  const state = previous ? (await new ApiMandateStatusSource(api, now).check(previous.id)).status : undefined;
+
   say("");
-  say("O mandato ainda nao existe. Este e o consentimento que o titular assina (sandbox):");
-  say(`  agente: ${example.agent_id}    finalidade: ${example.purpose}`);
-  say(`  teto por pagamento: ${example.per_tx_cap_minor} centavos    teto do mes: ${windowCap(example)} centavos    vitalicio: ${example.cap_minor} centavos`);
-  for (const b of example.beneficiaries) say(`  favorecido: ${b.name} (${b.alias})`);
-  say(`  validade: 1 ano    (o token do consentimento vale ate ${init.expires_at})`);
-  const yes = await options.confirm("  Voce e o titular e autoriza este mandato? [s/N] ");
+  say(previous && state ? text.consentReplaces(previous.id, text[PREVIOUS[state]], relative(process.cwd(), options.mandatePath)) : text.consentHeader);
+  say(text.consentAgent(example.agent_id, example.purpose));
+  say(text.consentCaps(example.per_tx_cap_minor, windowCap(example), example.cap_minor));
+  for (const b of example.beneficiaries) say(text.consentPayee(b.name, b.alias));
+  say(text.consentValidity(init.expires_at));
+  const yes = await options.confirm(text.consentQuestion);
   if (!yes) throw new Error("consent not authorized by the titular; nothing was created");
 
   // The consumer's "browser" is this terminal: the submit is the same call the hosted page makes,
@@ -108,19 +134,20 @@ export async function runEmbeddedConsent(options: ConsentOptions): Promise<Manda
   mkdirSync(dirname(options.mandatePath), { recursive: true });
   writeFileSync(options.mandatePath, JSON.stringify(mandate, null, 2) + "\n", { mode: 0o600 });
   chmodSync(options.mandatePath, 0o600);
-  say(`Mandato assinado: ${mandate.id} (consumidor ${mandate.consumer_id}).`);
+  say(text.consentSigned(mandate.id, mandate.consumer_id));
 
-  await fundSandbox(api, mandate, say);
+  await fundSandbox(api, mandate, say, options.locale);
   return mandate;
 }
 
 /** Best effort: the sandbox account is credited with one window's cap. A `pix-consent` source has no Celcoin account to credit, and the sandbox spend does not need one. */
-export async function fundSandbox(api: ApiClient, mandate: Mandate, say: (line: string) => void): Promise<void> {
+export async function fundSandbox(api: ApiClient, mandate: Mandate, say: (line: string) => void, locale: Locale = "pt-BR"): Promise<void> {
+  const text = STRINGS[locale];
   try {
     const funded = await api.post("/v1/test/fund", { body: { consumer_id: mandate.consumer_id, amount_minor: windowCap(mandate) } });
-    say(`Sandbox creditado: ${funded.amount_minor} centavos em ${funded.account} (deposit ${funded.deposit_id}).`);
+    say(text.consentFunded(funded.amount_minor, funded.account, funded.deposit_id));
   } catch (err) {
     const f = describeApiError(err);
-    say(`Sandbox nao creditado (${f.code}); o gasto de teste sob pix-consent nao depende disso.`);
+    say(text.consentNotFunded(f.code));
   }
 }

package/templates/bills-agent/agents/bills-agent/src/modules/pix-out.ts

@@ -4,7 +4,7 @@
  * whatever the core decided); it cannot pay. `codespar_ledger` and
  * `list_bills` are reads.
  */
-import type { ToolHandler } from "@codespar/agent-core";
+import { daysUntil, isReplayedSettlement, type Execution, type ToolHandler } from "@codespar/agent-core";
 import { formatBRL } from "../bills.js";
 import { BILLS, MONTH } from "../bills.js";
 
@@ -17,9 +17,11 @@ interface PayInput {
 export const listBills: ToolHandler = async (_input, ctx) => {
   const settled = ctx.engine.list({ state: "settled" });
   const paidAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
+  const today = ctx.engine.today();
   return {
     month: MONTH,
-    bills: BILLS.map((b) => ({ ...b, amount: formatBRL(b.amount_minor), paid_this_window: paidAliases.has(b.alias) })),
+    today,
+    bills: BILLS.map((b) => ({ ...b, amount: formatBRL(b.amount_minor), days_until_due: daysUntil(today, b.due), paid_this_window: paidAliases.has(b.alias) })),
     payees: ctx.engine.mandate.beneficiaries.map((b) => ({ alias: b.alias, name: b.name })),
   };
 };
@@ -38,6 +40,8 @@ export const codesparPay: ToolHandler = async (raw, ctx) => {
 
   const draft = await ctx.engine.draft({ items, ...claimed });
   if (!draft.ok) {
+    // Refused before a draft: no execution will ever say so, and the run's count is taken from this.
+    ctx.onNotRun?.({ ref: items.map((item) => item.payee).join(", "), why: "refused", detail: draft.reason });
     return { status: "refused", reason: draft.reason, message: draft.message, paid: false };
   }
   const execution = await ctx.onExecution(draft.execution);
@@ -49,8 +53,11 @@ export const codesparPay: ToolHandler = async (raw, ctx) => {
     items: execution.items.map((i) => ({ payee: i.beneficiary, amount: formatBRL(i.amount) })),
     ...(execution.reason ? { reason: execution.reason, detail: execution.detail } : {}),
     ...(execution.escalation ? { escalated_by: execution.escalation.trigger } : {}),
+    approved_by: approvedBy(execution),
     receipt_ids: execution.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
-    paid: execution.state === "settled",
+    // Settled by an earlier presentation of the same attempt: the payment exists, and this call did not make it.
+    replayed: isReplayedSettlement(execution),
+    paid: execution.state === "settled" && !isReplayedSettlement(execution),
   };
 };
 
@@ -71,3 +78,14 @@ export const codesparLedger: ToolHandler = async (raw, ctx) => {
   }
   throw new Error(`codespar_ledger: unsupported action ${String(input.action)}`);
 };
+
+/**
+ * Who moved the execution to `approved`: the person (`human`), the signed
+ * allowance (`mandate`), or nobody yet (`null`). The model is told which
+ * approval modes exist but not which one ran, and without this it guesses.
+ */
+export function approvedBy(execution: Execution): "human" | "mandate" | null {
+  const step = execution.history.find((h) => h.to === "approved");
+  if (!step) return null;
+  return step.actor.type === "human" ? "human" : "mandate";
+}

package/templates/bills-agent/agents/bills-agent/src/strings.ts

@@ -0,0 +1,68 @@
+/**
+ * What this agent prints, per locale: the runner's words for it and the
+ * consent the titular reads before signing. Every key exists in both entries
+ * (`npm run check`). The answers are read the same whatever the locale: the
+ * approval question and the consent question take s, sim, y and yes.
+ *
+ * What goes to the API is not here: the consent's display name and intent
+ * note are part of the consent the API records, not lines on this terminal.
+ */
+import { formatBRL, type LocaleTable } from "@codespar/agent-core";
+import type { KitStrings } from "@codespar/agent-runtime";
+
+const pt = {
+  mandateWord: "mandato",
+  receiptWord: "recibo",
+  intro: 'Diga o que pagar ("pague a escola de outubro"). Ctrl+D ou "sair" encerra.',
+  prompt: "> ",
+  approveQuestion: "  Aprovar este pagamento? [s/N] ",
+  uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita o pagamento)",
+  notAuthorized: "o mandato não autoriza",
+
+  consentHeader: "O mandato ainda não existe. Este é o consentimento que o titular assina (sandbox):",
+  consentReplaces: (mandateId: string, state: string, file: string) => `Já existe um mandato em ${file}: ${mandateId}, ${state}. Este é o consentimento de um mandato novo, que passa a ser o do arquivo (sandbox):`,
+  consentPreviousActive: "ativo na API",
+  consentPreviousPaused: "pausado na API",
+  consentPreviousRevoked: "revogado na API",
+  consentPreviousExpired: "expirado",
+  consentPreviousUnknown: "com estado que a API não respondeu",
+  consentAgent: (agentId: string, purpose: string) => `  agente: ${agentId}    finalidade: ${purpose}`,
+  consentCaps: (perTx: number, window: number, lifetime: number) => `  teto por pagamento: ${formatBRL(perTx, "pt-BR")}    teto do mês: ${formatBRL(window, "pt-BR")}    vitalício: ${formatBRL(lifetime, "pt-BR")}`,
+  consentPayee: (name: string, alias: string) => `  favorecido: ${name} (${alias})`,
+  consentValidity: (tokenExpiresAt: string) => `  validade: 1 ano    (o token do consentimento vale até ${tokenExpiresAt})`,
+  consentQuestion: "  Você é o titular e autoriza este mandato? [s/N] ",
+  consentSigned: (mandateId: string, consumerId: string) => `Mandato assinado: ${mandateId} (consumidor ${consumerId}).`,
+  consentFunded: (amount: number, account: string, depositId: string) => `Sandbox creditado: ${formatBRL(amount, "pt-BR")} em ${account} (deposit ${depositId}).`,
+  consentNotFunded: (code: string) => `Sandbox não creditado (${code}); o gasto de teste sob pix-consent não depende disso.`,
+  consentSaved: (mandateId: string) => `mandato ${mandateId} salvo em .codespar/mandate.json`,
+};
+
+export const STRINGS: LocaleTable<typeof pt & KitStrings> = {
+  "pt-BR": pt,
+  en: {
+    mandateWord: "mandate",
+    receiptWord: "receipt",
+    intro: 'Say what to pay ("pay the school for October"). Ctrl+D or "exit" ends.',
+    prompt: "> ",
+    approveQuestion: "  Approve this payment? [y/N] ",
+    uncertainDispatch: "  outcome unknown on the rail; run `npm run resume` to reconcile (never repeat the payment)",
+    notAuthorized: "the mandate does not authorize it",
+
+    consentHeader: "The mandate does not exist yet. This is the consent the account holder signs (sandbox):",
+    consentReplaces: (mandateId, state, file) => `${file} already holds a mandate: ${mandateId}, ${state}. This is the consent for a new one, which becomes the one in the file (sandbox):`,
+    consentPreviousActive: "active on the API",
+    consentPreviousPaused: "paused on the API",
+    consentPreviousRevoked: "revoked on the API",
+    consentPreviousExpired: "expired",
+    consentPreviousUnknown: "in a state the API did not answer",
+    consentAgent: (agentId, purpose) => `  agent: ${agentId}    purpose: ${purpose}`,
+    consentCaps: (perTx, window, lifetime) => `  cap per payment: ${formatBRL(perTx, "en")}    cap per month: ${formatBRL(window, "en")}    lifetime: ${formatBRL(lifetime, "en")}`,
+    consentPayee: (name, alias) => `  payee: ${name} (${alias})`,
+    consentValidity: (tokenExpiresAt) => `  valid for: 1 year    (the consent token is valid until ${tokenExpiresAt})`,
+    consentQuestion: "  Are you the account holder, and do you authorize this mandate? [y/N] ",
+    consentSigned: (mandateId, consumerId) => `Mandate signed: ${mandateId} (consumer ${consumerId}).`,
+    consentFunded: (amount, account, depositId) => `Sandbox credited: ${formatBRL(amount, "en")} to ${account} (deposit ${depositId}).`,
+    consentNotFunded: (code) => `Sandbox not credited (${code}); the test spend under pix-consent does not depend on it.`,
+    consentSaved: (mandateId) => `mandate ${mandateId} saved to .codespar/mandate.json`,
+  },
+};

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