@codespar/cli 0.18.1 → 0.21.0

package/templates/collections-agent/agents/collections-agent/src/modules/bolepix-receivables.ts

@@ -3,12 +3,13 @@
  * `codespar_charge` hands the proposal to the engine and gets an execution in
  * `drafted` (then whatever the core decided); it cannot issue anything.
  * `list_agreements` is a read. The real call (`POST /v1/charges`, one
- * cobranca com vencimento per instalment, `idempotency_key` per attempt) is
+ * cobrança com vencimento per instalment, `idempotency_key` per attempt) is
  * built by the rail from the execution the core approved.
  */
-import type { ToolHandler } from "@codespar/agent-core";
+import type { Locale, ToolHandler } from "@codespar/agent-core";
 import { AGREEMENTS, agreementByAlias, formatBRL, formatDate } from "../agreements.js";
 import type { Envelope } from "../envelope.js";
+import { STRINGS } from "../strings.js";
 
 interface ChargeInput {
   action?: unknown;
@@ -18,8 +19,9 @@ interface ChargeInput {
   execution_id?: unknown;
 }
 
-export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
+export function makeHandlers(envelope: Envelope, locale: () => Locale = () => "pt-BR"): Record<string, ToolHandler> {
   const listAgreements: ToolHandler = async (_input, ctx) => {
+    const text = STRINGS[locale()];
     const settled = ctx.engine.list({ state: "settled" });
     const open = ctx.engine.list({ state: "executing" });
     // Issued, then its reference turned ambiguous: the charge exists and may be paid. Not open, and the core refuses another until it is reconciled.
@@ -28,6 +30,8 @@ export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
     const settledAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
     const issuedAliases = new Set(open.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
     return {
+      // Due dates are proposed by the model inside `due_date_window_days` of today; it has no calendar but this one.
+      today: ctx.engine.today(),
       agreements: AGREEMENTS.map((a) => ({
         alias: a.alias,
         debtor_first_name: a.first_name,
@@ -36,12 +40,12 @@ export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
         origin: a.origin,
         opened_at: a.opened_at,
         status: settledAliases.has(a.alias)
-          ? "quitado"
+          ? text.statusSettled
           : issuedAliases.has(a.alias)
-            ? "cobranca emitida, aguardando pagamento"
+            ? text.statusIssued
             : unreconciledAliases.has(a.alias)
-              ? "cobranca emitida, em conferencia: nao emitir outra"
-              : "em aberto",
+              ? text.statusUnreconciled
+              : text.statusOpen,
       })),
       envelope: {
         max_discount_pct: envelope.max_discount_pct,
@@ -82,7 +86,11 @@ export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
     const claimed = typeof input.total_minor === "number" ? { claimed_total: input.total_minor } : {};
 
     const draft = await ctx.engine.draft({ items, ...claimed });
-    if (!draft.ok) return { status: "refused", reason: draft.reason, message: draft.message, issued: false, paid: false };
+    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: alias, why: "refused", detail: draft.reason });
+      return { status: "refused", reason: draft.reason, message: draft.message, issued: false, paid: false };
+    }
     const execution = await ctx.onExecution(draft.execution);
     return describe(execution);
   };

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

@@ -0,0 +1,91 @@
+/**
+ * What this agent prints, per locale: the runner's words for it, the lines an
+ * execution reads as, the one message per outcome the debtor receives, and the
+ * refusal details the envelope writes. Every key exists in both entries (`npm
+ * run check`).
+ *
+ * The envelope's details and the agreement statuses are read by the model too,
+ * as tool results; the model explains them in the reply language whatever the
+ * locale. The reason CODES next to them (`outside_envelope`, `outside_hours`)
+ * are machine words and are the same in every locale.
+ */
+import type { LocaleTable } from "@codespar/agent-core";
+import type { KitStrings } from "@codespar/agent-runtime";
+
+const pt = {
+  mandateWord: "política",
+  receiptWord: "registro",
+  intro: 'Você é o pagador. Diga algo ("oi, recebi a mensagem sobre o acordo do pedido 1042"). Ctrl+D ou "sair" encerra.',
+  prompt: "pagador> ",
+  approveQuestion: "  [operador] Aprovar a emissão desta cobrança? [s/N] ",
+  uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a emissão)",
+  notAuthorized: "a política não autoriza",
+  waitingForPayer: (round: number) => `  aguardando o pagador... (${round} consultas)`,
+
+  agreementOf: (debtor: string, alias: string) => `acordo de ${debtor} (${alias})`,
+  instalmentLine: (instalment: number, count: number, amount: string, due: string) => `parcela ${instalment}/${count}: ${amount}, vence ${due}`,
+  chargeLine: (instalment: number) => `cobrança ${instalment}`,
+
+  toldSettled: (chargeIds: string) => `Recebemos, acordo quitado. Obrigado! (${chargeIds})`,
+  toldExpired: "A cobrança venceu sem pagamento. Se quiser, emito uma nova dentro das mesmas condições.",
+  toldCancelled: "A cobrança foi cancelada. Nada foi pago.",
+  toldAmbiguous: "A cobrança deste acordo já foi emitida e estamos conferindo a situação dela. Não pague de novo; te aviso assim que estiver conferida.",
+  toldFailed: (reason: string | undefined) => `Não consegui emitir a cobrança (${reason ?? "falha no trilho"}). Nada foi cobrado.`,
+  toldDenied: (reason: string | undefined) => `Não posso emitir nesses termos (${reason ?? "recusado"}).`,
+  toldUndecided: (state: string) => `A proposta expirou sem decisão (${state}).`,
+
+  statusSettled: "quitado",
+  statusIssued: "cobrança emitida, aguardando pagamento",
+  statusUnreconciled: "cobrança emitida, em conferência: não emitir outra",
+  statusOpen: "em aberto",
+
+  envelopeTooManyInstalments: (count: number, max: number) => `${count} parcelas; o envelope permite até ${max}`,
+  envelopeBelowFloor: (total: number, pct: number, principal: number, maxPct: number, floor: number) =>
+    `total ${total} é ${pct}% abaixo do principal ${principal}; o desconto máximo é ${maxPct}% (piso ${floor})`,
+  envelopeAbovePrincipal: (total: number, principal: number) => `total ${total} acima do principal ${principal}; não se cobra mais do que se deve`,
+  envelopeInstalmentTooSmall: (amount: number, min: number) => `parcela de ${amount} abaixo do mínimo ${min}`,
+  envelopeNoDueDate: (instalment: number) => `parcela ${instalment} sem vencimento`,
+  envelopeDuePassed: (due: string, instalment: number, today: string) => `vencimento ${due} da parcela ${instalment} já passou (hoje é ${today})`,
+  envelopeDueOutsideWindow: (due: string, instalment: number, days: number, last: string) => `vencimento ${due} da parcela ${instalment} fora da janela de ${days} dias (até ${last})`,
+  envelopeDueOutOfOrder: (instalment: number) => `parcela ${instalment} vence antes da anterior`,
+};
+
+export const STRINGS: LocaleTable<typeof pt & KitStrings> = {
+  "pt-BR": pt,
+  en: {
+    mandateWord: "policy",
+    receiptWord: "record",
+    intro: 'You are the payer. Say something ("hi, I got the message about the agreement for order 1042"). Ctrl+D or "exit" ends.',
+    prompt: "payer> ",
+    approveQuestion: "  [operator] Approve issuing this charge? [y/N] ",
+    uncertainDispatch: "  outcome unknown on the rail; run `npm run resume` to reconcile (never repeat the issuance)",
+    notAuthorized: "the policy does not authorize it",
+    waitingForPayer: (round) => `  waiting for the payer... (${round} looks)`,
+
+    agreementOf: (debtor, alias) => `agreement of ${debtor} (${alias})`,
+    instalmentLine: (instalment, count, amount, due) => `instalment ${instalment}/${count}: ${amount}, due ${due}`,
+    chargeLine: (instalment) => `charge ${instalment}`,
+
+    toldSettled: (chargeIds) => `Payment received, the agreement is settled. Thank you! (${chargeIds})`,
+    toldExpired: "The charge reached its due date unpaid. If you like, I can issue a new one on the same terms.",
+    toldCancelled: "The charge was cancelled. Nothing was paid.",
+    toldAmbiguous: "The charge for this agreement was already issued and we are checking where it stands. Do not pay again; I will let you know as soon as it is checked.",
+    toldFailed: (reason) => `I could not issue the charge (${reason ?? "rail failure"}). Nothing was charged.`,
+    toldDenied: (reason) => `I cannot issue on those terms (${reason ?? "refused"}).`,
+    toldUndecided: (state) => `The proposal expired without a decision (${state}).`,
+
+    statusSettled: "settled",
+    statusIssued: "charge issued, awaiting payment",
+    statusUnreconciled: "charge issued, under review: do not issue another",
+    statusOpen: "open",
+
+    envelopeTooManyInstalments: (count, max) => `${count} instalments; the envelope allows up to ${max}`,
+    envelopeBelowFloor: (total, pct, principal, maxPct, floor) => `total ${total} is ${pct}% below the principal ${principal}; the maximum discount is ${maxPct}% (floor ${floor})`,
+    envelopeAbovePrincipal: (total, principal) => `total ${total} above the principal ${principal}; nobody is charged more than they owe`,
+    envelopeInstalmentTooSmall: (amount, min) => `instalment of ${amount} below the minimum ${min}`,
+    envelopeNoDueDate: (instalment) => `instalment ${instalment} has no due date`,
+    envelopeDuePassed: (due, instalment, today) => `due date ${due} of instalment ${instalment} has passed (today is ${today})`,
+    envelopeDueOutsideWindow: (due, instalment, days, last) => `due date ${due} of instalment ${instalment} is outside the ${days}-day window (until ${last})`,
+    envelopeDueOutOfOrder: (instalment) => `instalment ${instalment} falls due before the previous one`,
+  },
+};

package/templates/collections-agent/agents/collections-agent/test/ambiguous-charge.test.ts

@@ -36,7 +36,7 @@ describe("a receivable closed charge_reference_ambiguous: reconcile, never reiss
       const handlers = s.kit.handlers(s);
       const ctx = { engine: s.engine, onExecution: async (e: Execution) => e };
       const listed = (await handlers["list_agreements"]!({}, ctx)) as { agreements: Array<{ alias: string; status: string }> };
-      expect(listed.agreements.find((a) => a.alias === "acordo-1042")?.status).toBe("cobranca emitida, em conferencia: nao emitir outra");
+      expect(listed.agreements.find((a) => a.alias === "acordo-1042")?.status).toBe("cobrança emitida, em conferência: não emitir outra");
 
       const again = (await handlers["codespar_charge"]!({ action: "create", agreement: "acordo-1042", instalments: [{ amount_minor: 108000, due_date: "2026-10-15" }] }, ctx)) as Record<string, unknown>;
       expect(again).toMatchObject({ status: "denied", reason: "charge_reference_ambiguous", issued: false, charges: [] });
@@ -46,7 +46,7 @@ describe("a receivable closed charge_reference_ambiguous: reconcile, never reiss
       const told: string[] = [];
       announceOutcome(closed, s, (l) => told.push(l));
       expect(told).toHaveLength(1);
-      expect(told[0]).toContain("ja foi emitida");
+      expect(told[0]).toContain("já foi emitida");
       expect(told[0]).not.toContain("Nada foi cobrado");
     } finally {
       s.close();

package/templates/collections-agent/agents/collections-agent/test/check.test.ts

@@ -28,7 +28,10 @@ describe("npm run check: the manifest is the index", () => {
     writeFileSync(join(dir, "tools.json"), JSON.stringify({ ...t, meta_tools: t.meta_tools.filter((x) => x.effect !== "charge") }));
     expect(codes(dir)).toContain("tools_contradict_manifest");
     const again = copyAgent();
-    writeFileSync(join(again, "agent.yaml"), readFileSync(join(again, "agent.yaml"), "utf8").replace("  bolepix-receivables: sandbox\n", ""));
+    const manifest = readFileSync(join(again, "agent.yaml"), "utf8");
+    const dropped = manifest.replace(/^  bolepix-receivables:.*\n/m, "");
+    expect(dropped).not.toBe(manifest);
+    writeFileSync(join(again, "agent.yaml"), dropped);
     expect(codes(again)).toContain("tools_contradict_manifest");
   });
 

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

@@ -72,7 +72,7 @@ describe("npm start -- --input ... --json", () => {
       expect(payload.executions).toHaveLength(1);
       expect(payload.executions[0]).toMatchObject({ state: "denied", reason: "outside_hours", charges: [] });
       expect(payload.receipts).toHaveLength(0);
-      expect(out.stderr).toContain("agora sao 20:08");
+      expect(out.stderr).toContain("agora são 20:08");
     });
 
     it("at 14:00 America/Sao_Paulo the same command settles, whatever the wall clock says", () => {

package/templates/collections-agent/agents/collections-agent/test/envelope.test.ts

@@ -28,11 +28,11 @@ describe("the negotiation envelope is deterministic code", () => {
     expect(checkEnvelope(items([{ amount: 101999, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.reason).toBe("outside_envelope");
     expect(checkEnvelope(items([{ amount: 120001, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.detail).toContain("acima do principal");
     expect(checkEnvelope(items([{ amount: 30000, due_date: "2026-09-30" }, { amount: 30000, due_date: "2026-10-30" }, { amount: 30000, due_date: "2026-11-30" }, { amount: 30000, due_date: "2026-12-15" }]), envelope, NOW, TZ)?.detail).toContain("parcelas");
-    expect(checkEnvelope(items([{ amount: 118000, due_date: "2026-09-30" }, { amount: 2000, due_date: "2026-10-30" }]), envelope, NOW, TZ)?.detail).toContain("minimo");
+    expect(checkEnvelope(items([{ amount: 118000, due_date: "2026-09-30" }, { amount: 2000, due_date: "2026-10-30" }]), envelope, NOW, TZ)?.detail).toContain("mínimo");
   });
 
   it("due dates: in the past, beyond the window, out of order, missing", () => {
-    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-09-22" }]), envelope, NOW, TZ)?.detail).toContain("ja passou");
+    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-09-22" }]), envelope, NOW, TZ)?.detail).toContain("já passou");
     expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-12-23" }]), envelope, NOW, TZ)?.detail).toContain("fora da janela");
     expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-12-22" }]), envelope, NOW, TZ)).toBeUndefined();
     expect(checkEnvelope(items([{ amount: 60000, due_date: "2026-10-30" }, { amount: 60000, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.detail).toContain("antes da anterior");

package/templates/collections-agent/agents/collections-agent/test/fixtures/accept-1103.transcript.jsonl

@@ -1,2 +1,2 @@
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "create", "agreement": "acordo-1103", "instalments": [{"amount_minor": 40500, "due_date": "2026-09-25"}], "total_minor": 40500}}]}
-{"kind": "assistant_step", "reply": "A cobranca venceu sem pagamento. Se quiser, emito uma nova."}
+{"kind": "assistant_step", "reply": "A cobrança venceu sem pagamento. Se quiser, emito uma nova."}

package/templates/collections-agent/agents/collections-agent/test/fixtures/tap-emitir-nova-1042.transcript.jsonl

@@ -1,2 +1,2 @@
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "create", "agreement": "acordo-1042", "instalments": [{"amount_minor": 108000, "due_date": "2026-09-30"}], "total_minor": 108000}}]}
-{"kind": "assistant_step", "reply": "Pronto, Joana: emiti uma nova cobranca de R$ 1.080,00, vencendo em 30/09. O codigo esta acima."}
+{"kind": "assistant_step", "reply": "Pronto, Joana: emiti uma nova cobrança de R$ 1.080,00, vencendo em 30/09. O código está acima."}

package/templates/collections-agent/agents/collections-agent/test/payable-instrument.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The false green of OPEN_QUESTIONS §63: on staging (2026-09-27) the issuer
+ * ended the bolepix in ERROR, with no QR and no boleto line, and the run still
+ * answered `settled` with a cycle time, because the sandbox payer paid what
+ * nobody could have paid and the API's test route settled it (ent#1816). The
+ * stub scripts both halves here: an issuer that ends in ERROR, and a charge
+ * that is settled without ever becoming payable.
+ */
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { checkScenario, loadScenario, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "collections-payable-"));
+/** The buyer the happy path issues to. */
+const BUYER = "11144477735";
+
+function events(bundleDir: string): Array<{ type: string; payload: Record<string, unknown> }> {
+  return readFileSync(join(bundleDir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; payload: Record<string, unknown> });
+}
+
+describe("a cycle closes on a payable instrument, or it does not close", () => {
+  const scenario = loadScenario(agent, "happy-path");
+
+  it("an issuer that ends the registration in ERROR fails the order with the issuer's code: never settled, never paid, no cycle to boast of", async () => {
+    const run = await runScenario(agent, scenario, { mode: "human", runsDir, stubRail: { issuerErrorPayees: [BUYER] } });
+    expect(run.executions.map((e) => [e.state, e.reason])).toEqual([["failed", "charge_issuer_error"]]);
+    expect(run.settled_total).toBe(0);
+    expect(run.receipts).toBe(0);
+    expect(run.payer_calls).toEqual([]);
+    expect(run.executions[0]!.payable_seen).toBeNull();
+    const told = events(run.bundle_dir).filter((e) => e.type === "message.debtor").map((e) => String(e.payload["text"]));
+    expect(told).toEqual([expect.stringContaining("charge_issuer_error")]);
+    expect(told[0]).not.toMatch(/Recebemos/);
+    expect(checkScenario(scenario, run).ok).toBe(false);
+  });
+
+  it("a charge settled with no payable instrument seen first is refused by the gate as no_payable_instrument, and no cycle is reported", async () => {
+    const run = await runScenario(agent, scenario, { mode: "human", runsDir, stubRail: { settlesUnpayablePayees: [BUYER] } });
+    expect(run.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(run.executions[0]!.payable_seen).toBe(false);
+    expect(run.cycle_seconds).toBeNull();
+    const check = checkScenario(scenario, run);
+    expect(check.ok).toBe(false);
+    expect(check.failures).toEqual([expect.stringMatching(/^no_payable_instrument: /)]);
+  });
+
+  it("the ordinary happy path saw its QR before the payment, and reports its cycle", async () => {
+    const run = await runScenario(agent, scenario, { mode: "human", runsDir });
+    expect(run.executions[0]!.payable_seen).toBe(true);
+    expect(run.cycle_seconds).toEqual(expect.any(Number));
+    expect(checkScenario(scenario, run).failures).toEqual([]);
+  });
+});

package/templates/collections-agent/agents/collections-agent/test/rerun-clock.test.ts

@@ -0,0 +1,54 @@
+/**
+ * A rerun replays the run on the run's own clock. The scenario issues an
+ * instalment due 2026-09-30 on a run that started 2026-09-23; replayed on
+ * today's date the due date has passed, the envelope refuses the agreement,
+ * and the rerun reported a run that DIFFERS from one it had every byte of.
+ */
+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";
+import { ProofBundle } from "@codespar/agent-core";
+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, runId: string, env: Record<string, string> = {}) {
+  const result = spawnSync(process.execPath, [BIN, "rerun", runId, "--json"], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "", COLLECTIONS_RUNS_DIR: runsDir, COLLECTIONS_STATE_DIR: join(runsDir, "state"), ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stderr: result.stderr, report: JSON.parse(result.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[]; rerun_id: string } };
+}
+
+describe("npm run rerun <run-id> on a run from another day", () => {
+  it.each(["human", "mandate"] as const)("replays happy-path [%s] to the same states, on the clock the run started on", async (mode) => {
+    const runsDir = mkdtempSync(join(tmpdir(), "collections-rerun-clock-"));
+    const original = await runScenario(agent, loadScenario(agent, "happy-path"), { mode, rail: "stub", runsDir });
+    expect(original.executions.map((e) => e.state)).toEqual(["settled"]);
+    // The run is on the scenario's date, which is not today's: what a rerun used to ignore.
+    const startedAt = String(ProofBundle.open(runsDir, original.run_id)!.readMeta()!["started_at"]);
+    expect(startedAt.slice(0, 10)).toBe("2026-09-23");
+    expect(Math.abs(Date.now() - Date.parse(startedAt))).toBeGreaterThan(24 * 3600 * 1000);
+
+    const out = rerun(runsDir, original.run_id);
+    expect(out.stderr).not.toContain("já passou");
+    expect(out.report.rerun).toEqual(out.report.original);
+    expect(out.report.same_states).toBe(true);
+    expect(out.code).toBe(0);
+    // The rerun's own bundle says when it ran: where the original did.
+    expect(ProofBundle.open(runsDir, out.report.rerun_id)!.readMeta()!["started_at"]).toBe(startedAt);
+  });
+
+  it("the run's clock wins over one the shell pins", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "collections-rerun-clock-"));
+    const original = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "mandate", rail: "stub", runsDir });
+    const out = rerun(runsDir, original.run_id, { CODESPAR_AGENT_NOW: "2027-01-15T12:00:00.000Z" });
+    expect(out.report.same_states).toBe(true);
+  });
+});

package/templates/collections-agent/agents/collections-agent/test/whatsapp-poll.test.ts

@@ -118,10 +118,21 @@ function poll(env: Record<string, string>, extra: string[] = []) {
   return { ...out, payload: JSON.parse(lines[0]!) as PollPayload };
 }
 
+/**
+ * Every call this file makes to the emulator closes its connection. An agent
+ * run here is a `spawnSync`, which blocks this process's event loop for longer
+ * than the emulator's keep-alive (`Keep-Alive: timeout=5`), so fetch never gets
+ * to expire the socket it pooled; the next call writes to a socket the
+ * emulator already closed and dies `fetch failed … ECONNRESET`. A retry would
+ * hide that too, but `/_sim/clock` advances and `/_sim/status` marks: a call
+ * the emulator did receive, retried, would apply twice.
+ */
+const FRESH_CONNECTION = { connection: "close" } as const;
+
 async function advanceConversationClock(hours: number) {
   const response = await fetch(`${EMULATOR}/_sim/clock`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers: { "content-type": "application/json", ...FRESH_CONNECTION },
     body: JSON.stringify({ advance_hours: hours }),
     signal: AbortSignal.timeout(5000),
   });
@@ -145,7 +156,7 @@ function countEvents(env: Record<string, string>, type: string): number {
 
 const emulatorUp = await (async () => {
   try {
-    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+    return (await fetch(`${EMULATOR}/health`, { headers: FRESH_CONNECTION, signal: AbortSignal.timeout(2000) })).ok;
   } catch {
     return false;
   }
@@ -252,7 +263,63 @@ describe.skipIf(!emulatorUp)("a charge paid after the 24-hour window closed", ()
   });
 });
 
+/** The `payload` of every `message.debtor` event this state holds: which template, in which language. */
+function debtorMessages(env: Record<string, string>): Array<Record<string, unknown>> {
+  const db = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+  try {
+    return (db.prepare("SELECT payload FROM events WHERE type = 'message.debtor' ORDER BY seq").all() as Array<{ payload: string }>).map((r) => JSON.parse(r.payload) as Record<string, unknown>);
+  } finally {
+    db.close();
+  }
+}
+
+describe.skipIf(!emulatorUp)("a conversation keeps the locale it started in (#64)", () => {
+  it("agreed in English, confirmed days later by the en_US copy of the template, and a --locale that disagrees is refused", async () => {
+    const env = scratch("locale-en");
+    const agreed = agent(
+      ["start", "--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--mode", "mandate", "--transcript", AGREED, "--now", TUESDAY, "--locale", "en", "--json"],
+      { ...env, COLLECTIONS_STUB_PAYER: "never" },
+    );
+    expect(agreed.code).toBe(3);
+    const opened = JSON.parse(agreed.stdout.split("\n").filter(Boolean).pop()!) as { channel: { log: string } };
+    // The line that introduces the payable code is the code's, so it is English; the QR and the code itself are the rail's.
+    const introduced = conversationOf(opened.channel.log).filter((l) => l.direction === "out" && l.kind === "text").map((l) => l.text ?? "");
+    expect(introduced.some((t) => /R\$1,080\.00, due 2026-09-30 — charge /.test(t))).toBe(true);
+    // The model's own replies are the recorded ones, in Portuguese; what must not be Portuguese is the code's line.
+    expect(introduced.some((t) => /, vence 30\/09\/2026 — cobrança /.test(t))).toBe(false);
+
+    await advanceConversationClock(ADVANCE_HOURS);
+
+    // Nothing is sent, nothing is paid: the refusal comes before the channel opens.
+    const conflicting = agent(["poll", "--channel", "whatsapp", "--conversation", "acordo-1042", "--json", "--simulate-payer", "--now", AFTER_WINDOW, "--locale", "pt-BR"], env);
+    expect(conflicting.code).toBe(2);
+    expect(conflicting.stderr).toContain("--locale pt-BR");
+    expect(debtorMessages(env)).toEqual([]);
+
+    // No flag: the poll takes the conversation's recorded locale.
+    const polled = poll(env, ["--simulate-payer", "--now", AFTER_WINDOW]);
+    expect(polled.code).toBe(0);
+    expect(polled.payload.polled[0]).toMatchObject({ state: "settled", session_open: false, delivery: { told: true, carrier: "template", template: "acordo_quitado" } });
+    expect(debtorMessages(env)).toEqual([expect.objectContaining({ template: "acordo_quitado", language: "en_US", variables: ["acordo-1042"] })]);
+  });
+
+  it("the same conversation in the default locale is confirmed by the pt_BR copy", async () => {
+    const env = scratch("locale-pt");
+    expect(agree(env).code).toBe(3);
+    await advanceConversationClock(ADVANCE_HOURS);
+    const polled = poll(env, ["--simulate-payer", "--now", AFTER_WINDOW]);
+    expect(polled.payload.polled[0]!.delivery).toMatchObject({ told: true, template: "acordo_quitado" });
+    expect(debtorMessages(env)).toEqual([expect.objectContaining({ template: "acordo_quitado", language: "pt_BR" })]);
+  });
+});
+
 describe("what the poll refuses to be asked, with no emulator in sight", () => {
+  it("refuses a --locale that is not one of the two", () => {
+    const out = agent(["poll", "--channel", "whatsapp", "--conversation", "acordo-1042", "--json", "--locale", "es"], scratch("locale-bad"));
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--locale must be pt-BR or en");
+  });
+
   it("nothing waiting for a payer is a clean no-op, not an error: a cron that fails on an empty queue gets turned off", () => {
     const env = scratch("noop");
     const out = poll(env, ["--now", TUESDAY]);

package/templates/collections-agent/agents/collections-agent/test/whatsapp-status-replies.test.ts

@@ -25,9 +25,20 @@ const AFTER_WINDOW = new Date(new Date(TUESDAY).getTime() + 26 * 3600_000).toISO
 const AGREED = "test/fixtures/agreed-1042-awaiting-payer.transcript.jsonl";
 const CONTACT = "5511987654321";
 
+/**
+ * Every call this file makes to the emulator closes its connection. An agent
+ * run here is a `spawnSync`, which blocks this process's event loop for longer
+ * than the emulator's keep-alive (`Keep-Alive: timeout=5`), so fetch never gets
+ * to expire the socket it pooled; the next call writes to a socket the
+ * emulator already closed and dies `fetch failed … ECONNRESET`. A retry would
+ * hide that too, but `/_sim/clock` advances and `/_sim/status` marks: a call
+ * the emulator did receive, retried, would apply twice.
+ */
+const FRESH_CONNECTION = { connection: "close" } as const;
+
 const emulatorUp = await (async () => {
   try {
-    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+    return (await fetch(`${EMULATOR}/health`, { headers: FRESH_CONNECTION, signal: AbortSignal.timeout(2000) })).ok;
   } catch {
     return false;
   }
@@ -48,7 +59,7 @@ function run(args: string[], env: Record<string, string>) {
 const lastJson = (stdout: string) => JSON.parse(stdout.split("\n").filter(Boolean).pop()!) as Record<string, unknown>;
 
 async function sim(path: string, body?: unknown) {
-  const r = await fetch(`${EMULATOR}${path}`, body === undefined ? {} : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  const r = await fetch(`${EMULATOR}${path}`, body === undefined ? { headers: FRESH_CONNECTION } : { method: "POST", headers: { "content-type": "application/json", ...FRESH_CONNECTION }, body: JSON.stringify(body) });
   return (await r.json()) as Record<string, unknown>;
 }
 
@@ -88,7 +99,9 @@ describe.skipIf(!emulatorUp)("§46 on the collections-agent, against the emulato
       if (!template) await new Promise((r) => setTimeout(r, 50));
     }
     expect(template).toBeDefined();
-    await sim("/_sim/status", { status: "failed", message_id: template, reason: "not on whatsapp" });
+    // The emulator answers after its webhook did: a 200 here means the poll's receiver heard the failure inside its grace.
+    const marked = await sim("/_sim/status", { status: "failed", message_id: template, reason: "not on whatsapp" });
+    expect(marked["webhook"]).toMatchObject({ status: 200 });
 
     expect(await exit).toBe(1);
     const polled = (lastJson(stdout)["polled"] as Array<{ state: string; delivery: { told: boolean; reason?: string } }>)[0]!;

package/templates/collections-agent/agents/collections-agent/test/whatsapp.test.ts

@@ -84,10 +84,19 @@ function conversationOf(payload: Payload): ChannelLine[] {
 }
 
 const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+/**
+ * The probe closes its connection, as every emulator call in these tests does.
+ * An agent run here is a `spawnSync`, which blocks this process's event loop
+ * for longer than the emulator's keep-alive (`Keep-Alive: timeout=5`), so a
+ * pooled socket is never expired by fetch and the next call on it dies
+ * `fetch failed … ECONNRESET`. This file makes one call today; the header is
+ * here so the next one does not inherit a pooled socket.
+ */
+const FRESH_CONNECTION = { connection: "close" } as const;
 /** Probed at module level: `describe.skipIf` is read when the file is collected, before any hook runs. */
 const emulatorUp = await (async () => {
   try {
-    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+    return (await fetch(`${EMULATOR}/health`, { headers: FRESH_CONNECTION, signal: AbortSignal.timeout(2000) })).ok;
   } catch {
     return false;
   }
@@ -127,7 +136,7 @@ describe.skipIf(!emulatorUp)("the cycle closes over the WhatsApp channel", () =>
     const payload = payloadOf(out.stdout);
     expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
     // The question is the operator's and is on the console; nothing like it is in the conversation.
-    for (const line of conversationOf(payload)) expect(line.text ?? "").not.toMatch(/operador|Aprovar a emissao/i);
+    for (const line of conversationOf(payload)) expect(line.text ?? "").not.toMatch(/operador|Aprovar a emiss[aã]o/i);
   });
 
   it("writes the conversation into the bundle with the contact masked", () => {
@@ -150,8 +159,11 @@ describe.skipIf(!emulatorUp)("the cycle closes over the WhatsApp channel", () =>
     const outbound = conversationOf(payload).filter((l) => l.direction === "out");
     expect(outbound.some((l) => l.kind === "media")).toBe(true);
     // The kit's one-per-outcome message, sent once however many looks carried the event.
-    // The model's own reply also says the charge expired, which is the terminal's behaviour too.
-    expect(outbound.filter((l) => String(l.text ?? "").startsWith("A cobranca venceu sem pagamento"))).toHaveLength(1);
+    // The model's own reply also says the charge expired, which is the terminal's behaviour too, and since #64 both
+    // spell "cobrança"; the kit's message is the one that carries the outcome it tells (`about`).
+    const told = outbound.filter((l) => (l as { about?: unknown }).about !== undefined);
+    expect(told.filter((l) => String(l.text ?? "").startsWith("A cobrança venceu sem pagamento"))).toHaveLength(1);
+    expect(told).toHaveLength(1);
   });
 
   it("refuses to say anything at all outside the collection hours, and issues nothing", () => {

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

@@ -3,7 +3,7 @@
     {
       "name": "codespar_charge",
       "effect": "charge",
-      "description": "Propose the receivable(s) of an agreement the payer accepted: one instalment per bolepix (cobranca com vencimento: the payer settles by Pix or by boleto). This does NOT issue anything: it creates an execution in `drafted` that the code checks against the collection policy and the negotiation envelope (discount ceiling, instalment count, due-date window, collection hours) and, depending on the approval mode, asks the operator or issues. The code builds the real call (`POST /v1/charges`, `method: boleto`, the debtor's name and document from the agreement, `idempotency_key` per instalment) and presents the QR and the copy-and-paste; you never see or pass a document. action=status reads back the state of a receivable this run issued.",
+      "description": "Propose the receivable(s) of an agreement the payer accepted: one instalment per bolepix (cobrança com vencimento: the payer settles by Pix or by boleto). This does NOT issue anything: it creates an execution in `drafted` that the code checks against the collection policy and the negotiation envelope (discount ceiling, instalment count, due-date window, collection hours) and, depending on the approval mode, asks the operator or issues. The code builds the real call (`POST /v1/charges`, `method: boleto`, the debtor's name and document from the agreement, `idempotency_key` per instalment) and presents the QR and the copy-and-paste; you never see or pass a document. action=status reads back the state of a receivable this run issued.",
       "input_schema": {
         "type": "object",
         "properties": {
@@ -33,7 +33,7 @@
     {
       "name": "list_agreements",
       "effect": "read",
-      "description": "The open agreements this merchant collects: alias, debtor's first name, principal in BRL cents, origin, and the envelope you may negotiate inside (maximum discount, maximum instalments, due-date window). Read-only. Documents are not returned.",
+      "description": "The open agreements this merchant collects, with `today` (the date every due date is counted from): alias, debtor's first name, principal in BRL cents, origin, and the envelope you may negotiate inside (maximum discount, maximum instalments, due-date window). Read-only. Documents are not returned.",
       "input_schema": { "type": "object", "properties": {} }
     }
   ]

package/templates/collections-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/collections-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"
   }