@codespar/cli 0.18.1 → 0.21.0

package/templates/collections-agent/packages/agent-core/test/recorded-turns.ts

@@ -0,0 +1,29 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Every turn a person types in a recorded scenario or WhatsApp conversation
+ * under `root/agents`: all Portuguese. `root` is this repository, with every
+ * agent, or a scaffold made by `codespar init --template`, with one.
+ */
+export function recordedTurns(root: string): string[] {
+  const out: string[] = [];
+  for (const agent of readdirSync(join(root, "agents"))) {
+    for (const dir of ["scenarios", join("channels", "whatsapp")]) {
+      let files: string[] = [];
+      try {
+        files = readdirSync(join(root, "agents", agent, dir)).filter((f) => f.endsWith(".json") && f !== "templates.json");
+      } catch {
+        continue;
+      }
+      for (const f of files) {
+        const doc = JSON.parse(readFileSync(join(root, "agents", agent, dir, f), "utf8")) as { turns?: Array<{ input?: string; text?: string }> };
+        for (const t of doc.turns ?? []) {
+          const text = t.input ?? t.text;
+          if (typeof text === "string") out.push(text);
+        }
+      }
+    }
+  }
+  return out;
+}

package/templates/collections-agent/packages/agent-core/test/secrets.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { createCodeSparClient } from "../src/api/client.js";
-import { assertTestKey, isTestKey, NotATestKeyError, redactKey } from "../src/secrets.js";
+import { assertTestKey, CODESPAR_KEY_PLACEHOLDER, isTestKey, NotATestKeyError, redactKey, testKeyMessage, testKeyProblem } from "../src/secrets.js";
 
 // Built at runtime so the secret scan (which refuses key-shaped literals) stays honest about this file.
 const TEST = ["csk", "test", "0123456789abcdef"].join("_");
@@ -21,6 +21,45 @@ describe("sandbox by construction", () => {
     expect(createCodeSparClient({ apiKey: TEST })).toBeDefined();
   });
 
+  it("tells the three mistakes apart (#50): no key, the placeholder, a key that is not a test key", () => {
+    for (const missing of [undefined, "", "   "]) expect(testKeyProblem(missing)).toBe("missing");
+    expect(testKeyProblem(CODESPAR_KEY_PLACEHOLDER)).toBe("placeholder");
+    expect(testKeyProblem(LIVE)).toBe("not_test");
+    expect(testKeyProblem("csk_test_")).toBe("not_test");
+    expect(testKeyProblem(TEST)).toBeUndefined();
+    expect(isTestKey(CODESPAR_KEY_PLACEHOLDER)).toBe(false);
+    for (const [key, problem] of [[undefined, "missing"], [CODESPAR_KEY_PLACEHOLDER, "placeholder"], [LIVE, "not_test"]] as const) {
+      try {
+        assertTestKey(key);
+        throw new Error("accepted");
+      } catch (err) {
+        expect(err).toBeInstanceOf(NotATestKeyError);
+        expect((err as NotATestKeyError).problem).toBe(problem);
+      }
+    }
+  });
+
+  it("gives each its own remediation, naming the file the agent reads", () => {
+    const file = "agents/bills-agent/.env";
+    const missing = testKeyMessage("missing", file);
+    const placeholder = testKeyMessage("placeholder", file);
+    const live = testKeyMessage("not_test", file);
+    expect(missing).toContain("CODESPAR_API_KEY is not set");
+    expect(missing).toContain(`copy ${file}.example to ${file}`);
+    expect(missing).not.toContain("live");
+    expect(placeholder).toContain(`still the placeholder from .env.example (${CODESPAR_KEY_PLACEHOLDER})`);
+    expect(placeholder).toContain(file);
+    expect(placeholder).not.toContain("live");
+    expect(live).toContain("a live key is refused");
+    expect(new Set([missing, placeholder, live]).size).toBe(3);
+    expect(new NotATestKeyError("missing", file).message).toBe(missing);
+  });
+
+  it("refuses to build a client on the placeholder too, before any network", () => {
+    expect(() => createCodeSparClient({ apiKey: CODESPAR_KEY_PLACEHOLDER })).toThrow(/placeholder/);
+    expect(() => createCodeSparClient({ apiKey: undefined })).toThrow(/is not set/);
+  });
+
   it("redacts keys for logs", () => {
     expect(redactKey(TEST)).toBe("csk_test_…cdef");
     expect(redactKey(TEST)).not.toContain("0123456789");

package/templates/collections-agent/packages/agent-runtime/README.md

@@ -33,11 +33,33 @@ nothing else.
   `--conversation`, `--scripted`), `consent`, `approve`, `deny`, `resume`,
   `rerun`, `reconcile`, `inspect` (`--json`, `--html <file>`), `poll`
   (`--channel`, `--conversation`, `--backend`, `--wait`, `--simulate-payer`,
-  `--payer`, `--now`, `--json`), `webhook`, `check`, `eval`.
+  `--payer`, `--now`, `--json`), `webhook`, `check`, `eval`, `verify`
+  (`--from-api`, `--json`, `--keys`/`--url`, `--approval`), which needs no
+  agent directory.
+- What a report says about a settlement the API replayed: the terminal line
+  "já estava pago", `replayed` on the executions of a paying agent's one-shot
+  `--json`, and "replayed, not paid by this run" in `inspect`. The first two
+  read agent-core's `isReplayedSettlement`; `inspect` reads the same mark from
+  the bundle's rail answers (`docs/OPEN_QUESTIONS.md` §39c).
+- What `verify` prints: the verdict, the chain it recomputed, the approval it
+  matched and, off a body that bound, `sandbox` and `money_moved` as the chain
+  sealed them. Nothing else of the API's read, which still carries
+  `mandate.sig` (§47).
 - Setup: the manifest, the guardrails, the tools file, the system prompt, the
   local state, the signer, the proof bundle, the provider (Anthropic with a
   real key, replay without one), and the pinned clock (`--now`,
-  `CODESPAR_AGENT_NOW`).
+  `CODESPAR_AGENT_NOW`), which also pins the `today` the list tools return.
+- The locale of what the code prints (#64). `setup` resolves it once per run:
+  `--locale`, else `locale:` in `agent.yaml`, else `pt-BR`, and records it in
+  the bundle's `run.json`. The terminal's own lines come from agent-core's
+  `CORE_STRINGS` and the kit's from `kit.strings`, both in that locale; the
+  parsers do not change with it (`parseApproval`, `parseBatchGesture` read both
+  languages whatever is shown). A command that tells an outcome later (`poll`,
+  `webhook`, `approve`) tells the counterparty in the locale of the run that
+  proposed it, and `poll --channel whatsapp` sends the template copy in the
+  conversation's recorded language and refuses a `--locale` that disagrees.
+  The model's reply language is a different thing, read per turn from what
+  the person types.
 - The section 9 adversarial runner and the section 12 scenario runner.
 - The `csk_test_` guard and the `.env.example` placeholder rule.
 
@@ -57,11 +79,16 @@ export const agent = defineAgent(import.meta.url, {
 ```
 
 `AgentKit` (in `src/kit.ts`) is the whole seam: the rail adapter
-(`buildRail`), the tool handlers, the `policyExtension`, the console labels,
-what a one-shot prints as JSON, and — for an agent whose money comes IN — the
+(`buildRail`), the tool handlers, the `policyExtension`, the console words
+(`strings`, one entry per locale, and `labels`, which holds what must not vary
+by locale: who approves and the record kinds), what a one-shot prints as JSON, and — for an agent whose money comes IN — the
 sandbox payer and the one message per outcome. An agent that declares none of
 it gets `defaultKit`: the stub rail, the example mandate, no tools.
 
+`npm run check` fails when a key of `kit.strings` or of `CORE_STRINGS` is
+missing from one locale (`strings_incomplete`), so an English run never prints
+`undefined` where a Portuguese one prints a word.
+
 `defineAgent(import.meta.url, kit)` finds the nearest `agent.yaml` above the
 module, which is what makes every path (`scenarios/`, `evals/`, `.codespar/`,
 `runs/`) and every test-only environment variable (`BILLS_STATE_DIR`,

package/templates/collections-agent/packages/agent-runtime/src/channels/rules.ts

@@ -24,7 +24,7 @@
  * Every rule can only REFUSE. None of them rewrites a message: a message
  * that is edited on the way out is not the message the transcript shows.
  */
-import { isOutsideHours, localClock } from "@codespar/agent-core";
+import { CORE_STRINGS, isOutsideHours, localClock, type Locale } from "@codespar/agent-core";
 import type { Conversation, OutboundBody } from "./types.js";
 
 export interface ChannelRefusal {
@@ -44,6 +44,8 @@ export interface RuleContext {
   now: () => Date;
   /** Agreement aliases this agent knows, so "names another agreement" is decidable. */
   knownSubjects?: readonly string[] | undefined;
+  /** The language of the refusal details. It never changes what is refused. Default pt-BR. */
+  locale?: Locale | undefined;
 }
 
 /** `123.456.789-00`, `12345678900`, `12.345.678/0001-95`, `12345678000195`. */
@@ -90,7 +92,7 @@ export function checkOutbound(to: string, body: OutboundBody, ctx: RuleContext):
     if (isOutsideHours(`${close}-${open}`, ctx.now(), ctx.hours.timezone)) {
       return {
         rule: "collection_hours",
-        detail: `fora do horario de cobranca (${ctx.hours.window} ${ctx.hours.timezone}); agora sao ${localClock(ctx.now(), ctx.hours.timezone)}`,
+        detail: CORE_STRINGS[ctx.locale ?? "pt-BR"].outsideCollectionHours(ctx.hours.window, ctx.hours.timezone, localClock(ctx.now(), ctx.hours.timezone)),
       };
     }
   }

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/emulator.ts

@@ -25,7 +25,7 @@
  * fetches `@dyvit/whatsapp-simulator-cli` at a pinned version and runs it;
  * `npm run whatsapp:emulator` is the command.
  */
-import type { ConversationScript } from "@codespar/agent-core";
+import { CORE_STRINGS, type ConversationScript, type Locale } from "@codespar/agent-core";
 import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
 import { WhatsAppCloudApi, type CloudApiOptions } from "./cloud-api.js";
 
@@ -129,6 +129,8 @@ export interface EmulatorBackendOptions extends CloudApiOptions {
   ask?: ((question: string) => Promise<string>) | undefined;
   /** Where the console draws the conversation as it goes. */
   render: (line: string) => void;
+  /** The language of the console lines above. Default pt-BR. */
+  locale?: Locale | undefined;
 }
 
 /**
@@ -147,7 +149,7 @@ export class WhatsAppEmulator implements ChannelBackend {
   private closed = false;
 
   constructor(private readonly options: EmulatorBackendOptions) {
-    const { driver: _driver, script: _script, pinAt: _pinAt, ask: _ask, render: _render, ...api } = options;
+    const { driver: _driver, script: _script, pinAt: _pinAt, ask: _ask, render: _render, locale: _locale, ...api } = options;
     this.api = new WhatsAppCloudApi(api);
   }
 
@@ -156,7 +158,7 @@ export class WhatsAppEmulator implements ChannelBackend {
     await this.options.driver.health();
     if (this.options.pinAt) await this.options.driver.pin(this.options.pinAt);
     this.options.render("");
-    this.options.render(`  ┌─ WhatsApp (dyvit-wa-sim, emulador local da Cloud API — sem rede externa, sem conta Meta)`);
+    this.options.render(this.text.waEmulatorOpen);
   }
 
   async next(): Promise<InboundMessage | undefined> {
@@ -193,7 +195,7 @@ export class WhatsAppEmulator implements ChannelBackend {
     if (!this.options.ask) return undefined;
     let answer: string;
     try {
-      answer = await this.options.ask("  │ voce> ");
+      answer = await this.options.ask(this.text.waYou);
     } catch {
       return undefined;
     }
@@ -207,10 +209,14 @@ export class WhatsAppEmulator implements ChannelBackend {
     return this.api.deliver(to, body);
   }
 
+  private get text() {
+    return CORE_STRINGS[this.options.locale ?? "pt-BR"];
+  }
+
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
     await this.api.close();
-    this.options.render("  └─ fim da conversa");
+    this.options.render(this.text.waEmulatorClosed);
   }
 }

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/index.ts

@@ -13,12 +13,22 @@
  * caller and have no path to this object at all — not a check, a shape: there
  * is no method here that an operator line could be handed to.
  */
-import { declaredReplies, type ProofBundle, type QuickReply, type WhatsAppTemplate } from "@codespar/agent-core";
+import { CORE_STRINGS, WHATSAPP_LANGUAGE, declaredReplies, type CoreStrings, type Locale, type ProofBundle, type QuickReply, type WhatsAppTemplate } from "@codespar/agent-core";
 import { checkOutbound, type HoursRule, type RuleContext } from "../rules.js";
 import type { Channel, ChannelBackend, ChannelLogLine, Conversation, DeliveryState, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
 import { maskContact } from "../contact.js";
 import { SessionWindow, type SessionState } from "./session.js";
 
+/**
+ * How far along a message a status puts it. Status webhooks are not ordered:
+ * the emulator dispatches a send's own `sent` and `delivered` while a status
+ * posted meanwhile goes out between them, and Meta does not promise order
+ * either. A `delivered` that lands after a `failed` must not un-fail the
+ * message (#63), so `failed` ranks above everything, and a late `sent` does
+ * not rewind a `read`.
+ */
+const PROGRESS: Record<DeliveryState, number> = { queued: 0, sent: 1, delivered: 2, read: 3, failed: 4 };
+
 export interface WhatsAppChannelOptions {
   backend: ChannelBackend;
   conversation: Conversation;
@@ -52,6 +62,12 @@ export interface WhatsAppChannelOptions {
   onDeliveryFailed?: ((line: ChannelLogLine) => void) | undefined;
   /** Lines an earlier run wrote for this conversation, so a status about a message it sent can be tied back to what that message was. */
   priorLines?: ReadonlyArray<ChannelLogLine> | undefined;
+  /**
+   * The conversation's locale. It picks the language of every template this
+   * channel sends and of the quick replies it reads a tap by, and the words of
+   * the operator's lines. Fixed for the conversation. Default pt-BR.
+   */
+  locale?: Locale | undefined;
 }
 
 export class WhatsAppChannel implements Channel {
@@ -61,7 +77,7 @@ export class WhatsAppChannel implements Channel {
   private readonly lines: ChannelLogLine[] = [];
   private lastInbound: InboundMessage | undefined;
   private readonly replies: Map<string, QuickReply>;
-  /** The latest state the provider reported per message id, this process. */
+  /** The furthest state the provider reported per message id (`PROGRESS`), this process. */
   private readonly delivery = new Map<string, DeliveryState>();
   /**
    * Failures reported for a message not yet in the log. A provider can post
@@ -71,10 +87,16 @@ export class WhatsAppChannel implements Channel {
    */
   private readonly earlyFailures = new Map<string, ChannelLogLine>();
 
+  /** Meta's language code for this conversation: the one every template send carries. */
+  readonly language: string;
+  private readonly text: CoreStrings;
+
   constructor(private readonly options: WhatsAppChannelOptions) {
     this.conversation = options.conversation;
+    this.language = WHATSAPP_LANGUAGE[options.locale ?? "pt-BR"];
+    this.text = CORE_STRINGS[options.locale ?? "pt-BR"];
     this.session = new SessionWindow(options.templates ?? [], options.session);
-    this.replies = declaredReplies(options.templates ?? []);
+    this.replies = declaredReplies(options.templates ?? [], this.language);
   }
 
   get backend(): string {
@@ -111,9 +133,9 @@ export class WhatsAppChannel implements Channel {
     return (this.options.templates ?? []).find((t) => t.fallback)?.name;
   }
 
-  /** What the agent declared about a template it is about to send. The language is the registry's, never the sender's guess. */
+  /** The copy of a template declared in this conversation's language, for a caller about to send it. */
   declaredTemplate(name: string): WhatsAppTemplate | undefined {
-    return this.session.declared(name);
+    return this.session.declared(name, this.language);
   }
 
   async open(): Promise<void> {
@@ -160,7 +182,7 @@ export class WhatsAppChannel implements Channel {
           : undefined;
       if (refusal) {
         this.record({ ...base, kind: "reply", reply: tapped, refused: refusal });
-        this.options.say?.(`  [whatsapp] toque ignorado (${refusal.rule}): ${refusal.detail}`);
+        this.options.say?.(this.text.waTapIgnored(refusal.rule, refusal.detail));
         continue;
       }
       this.record({ ...base, kind: "reply", reply: tapped, text: declared!.intent });
@@ -182,7 +204,8 @@ export class WhatsAppChannel implements Channel {
    */
   private observeStatus(status: StatusUpdate): void {
     const sent = [...(this.options.priorLines ?? []), ...this.lines].find((l) => l.direction === "out" && l.message_id === status.message_id);
-    this.delivery.set(status.message_id, status.status);
+    const known = this.delivery.get(status.message_id);
+    if (known === undefined || PROGRESS[status.status] > PROGRESS[known]) this.delivery.set(status.message_id, status.status);
     const line: ChannelLogLine = {
       at: this.options.now().toISOString(),
       direction: "status",
@@ -206,13 +229,11 @@ export class WhatsAppChannel implements Channel {
   private reportFailure(line: ChannelLogLine): void {
     const status = { message_id: line.message_id, errors: line.errors ?? [] };
     const codes = status.errors.map((e) => `${e.code ?? "?"}${e.details ? ` ${e.details}` : ""}`).join("; ") || "no error given";
-    this.options.say?.(
-      `  [operador] ENTREGA FALHOU da mensagem ${status.message_id} (${codes})${line.about ? ` — era o aviso de ${line.about.execution_id} (${line.about.state}): a pessoa NAO foi avisada` : ""}`,
-    );
+    this.options.say?.(this.text.waDeliveryFailed(status.message_id, codes, line.about ? `${line.about.execution_id} (${line.about.state})` : undefined));
     this.options.onDeliveryFailed?.(line);
   }
 
-  /** The latest status the provider reported for a message this process saw a status for. */
+  /** The furthest status the provider reported for a message this process saw a status for; a `failed` stays `failed`. */
   deliveryOf(messageId: string): DeliveryState | undefined {
     return this.delivery.get(messageId);
   }
@@ -234,6 +255,7 @@ export class WhatsAppChannel implements Channel {
       hours: this.options.hours,
       now: this.options.now,
       knownSubjects: this.options.knownSubjects,
+      locale: this.options.locale,
     };
 
     // The house rules first: a message the law refuses is not a message the provider should ever see.
@@ -241,15 +263,15 @@ export class WhatsAppChannel implements Channel {
     if (refusal) {
       const sent: SentMessage = { id: "", state: "failed", refused: refusal };
       this.logOutbound(body, sent);
-      this.options.say?.(`  [whatsapp] recusado (${refusal.rule}): ${refusal.detail}`);
+      this.options.say?.(this.text.waRefused(refusal.rule, refusal.detail));
       return sent;
     }
 
     // A template carries the quick replies its declaration offers, and only those.
-    const buttons = body.kind === "template" ? this.session.declared(body.template)?.buttons : undefined;
+    const buttons = body.kind === "template" ? this.session.declared(body.template, body.language)?.buttons : undefined;
     const outgoing: OutboundBody = body.kind === "template" && buttons?.length ? { ...body, buttons: buttons.map((b) => ({ id: b.id, title: b.title })) } : body;
     const sent = await this.options.backend.deliver(to, outgoing);
-    if (sent.refused) this.options.say?.(`  [whatsapp] recusado pelo backend (${sent.refused.rule}): ${sent.refused.detail}`);
+    if (sent.refused) this.options.say?.(this.text.waRefusedByBackend(sent.refused.rule, sent.refused.detail));
     if (sent.refused?.rule === "session_window_closed") this.session.observeProviderShut();
     this.logOutbound(outgoing, sent);
     return sent;
@@ -310,24 +332,24 @@ export class WhatsAppChannel implements Channel {
   private record(line: ChannelLogLine): void {
     this.lines.push(line);
     this.options.bundle?.channel({ ...line, channel: "whatsapp", backend: this.backend });
-    this.options.render?.(`  │ ${draw(line)}`);
+    this.options.render?.(`  │ ${draw(line, this.text)}`);
   }
 }
 
 /** One console line for one message. The refusals are visible: a message nobody got is part of the conversation's story. */
-function draw(line: ChannelLogLine): string {
+function draw(line: ChannelLogLine, text: CoreStrings): string {
   if (line.direction === "status") return `(status ${line.message_id}: ${line.state}${line.errors?.length ? ` ${line.errors.map((e) => e.code).join(",")}` : ""})`;
-  if (line.kind === "reply") return `${line.contact}: [toque: ${line.reply?.title ?? "?"}]${line.refused ? ` (ignorado: ${line.refused.rule})` : ` -> ${line.text ?? ""}`}`;
-  const who = line.direction === "in" ? `${line.contact}:` : "loja:";
+  if (line.kind === "reply") return `${line.contact}: ${text.waTap(line.reply?.title ?? "?")}${line.refused ? text.waTapIgnoredMark(line.refused.rule) : ` -> ${line.text ?? ""}`}`;
+  const who = line.direction === "in" ? `${line.contact}:` : text.waShop;
   const what =
     line.kind === "instrument"
-      ? `[copia e cola] ${line.text ?? ""}`
+      ? `${text.waCopyPaste} ${line.text ?? ""}`
       : line.kind === "media"
-        ? "[imagem: QR Pix]"
+        ? text.waQrImage
         : line.kind === "template"
           ? line.text ?? "[template]"
           : line.text ?? "";
-  return line.refused ? `${who} (nao enviada: ${line.refused.rule}) ${what}` : `${who} ${what}`;
+  return line.refused ? `${who} ${text.waNotSent(line.refused.rule)} ${what}` : `${who} ${what}`;
 }
 
 function textOf(body: OutboundBody): string | undefined {

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/open.ts

@@ -144,6 +144,7 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
       driver,
       say,
       render: options.render ?? say,
+      locale: s.locale,
       ...(options.script ? { script: options.script } : {}),
       ...(options.ask ? { ask: options.ask } : {}),
       ...(options.pinAt ? { pinAt: options.pinAt } : {}),
@@ -166,6 +167,8 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
     ...(options.session ? { session: options.session } : {}),
     ...(options.priorLines ? { priorLines: options.priorLines } : {}),
     onDeliveryFailed: (line) => recordDeliveryFailure(s, line),
+    // The run's locale, which for a poll is the conversation's recorded one: the templates go out in its language.
+    locale: s.locale,
   });
 
   return { channel, ...(driver ? { driver } : {}), ...(sessionKey ? { sessionKey } : {}) };

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/present.ts

@@ -11,21 +11,22 @@
  * its OWN message underneath, because a code inside a picture cannot be
  * copied and a code inside a paragraph cannot be tapped.
  */
-import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import { CORE_STRINGS, formatDay, type ChargeInstrument, type Execution, type Locale } from "@codespar/agent-core";
 import type { OutboundBody } from "../types.js";
 
-export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string): OutboundBody[] {
-  const money = new Intl.NumberFormat("pt-BR", { style: "currency", currency });
+export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string, locale: Locale = "pt-BR"): OutboundBody[] {
+  const text = CORE_STRINGS[locale];
+  const money = new Intl.NumberFormat(locale === "en" ? "en-US" : "pt-BR", { style: "currency", currency });
   const item = execution.items[instalment - 1];
   const count = execution.items.length;
   const bodies: OutboundBody[] = [
     {
       kind: "text",
       text: [
-        count > 1 ? `Parcela ${instalment}/${count}: ` : "",
+        count > 1 ? text.instalmentOf(instalment, count) : "",
         item ? money.format(item.amount / 100) : "",
-        instrument.due_date ? `, vence ${formatDate(instrument.due_date)}` : "",
-        ` — cobranca ${chargeId}`,
+        instrument.due_date ? text.dueOn(formatDay(instrument.due_date, locale)) : "",
+        text.chargeRef(chargeId),
       ].join(""),
     },
   ];
@@ -34,14 +35,9 @@ export function instrumentBodies(execution: Execution, instalment: number, charg
     bodies.push({ kind: "instrument", instrument: "pix_copy_paste", value: instrument.pix_copy_paste });
   }
   if (instrument.boleto_bank_line) {
-    bodies.push({ kind: "text", text: "Ou pelo boleto, linha digitavel:" });
+    bodies.push({ kind: "text", text: text.boletoLine });
     bodies.push({ kind: "instrument", instrument: "boleto_bank_line", value: instrument.boleto_bank_line });
   }
   return bodies;
 }
 
-/** `2026-09-30` -> `30/09/2026`. */
-export function formatDate(iso: string): string {
-  const [y, m, d] = iso.split("-");
-  return `${d}/${m}/${y}`;
-}

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/run.ts

@@ -15,7 +15,7 @@
  * a code inside a picture cannot be copied and a code inside a paragraph
  * cannot be tapped.
  */
-import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import type { ChargeInstrument, Execution, NotRunLine } from "@codespar/agent-core";
 import { handleExecution, type TerminalOptions } from "../../terminal.js";
 import type { Setup } from "../../setup.js";
 import type { OutboundBody } from "../types.js";
@@ -42,6 +42,8 @@ export interface ConverseResult {
   replies: string[];
   toolCalls: Array<{ name: string; refused: boolean }>;
   executions: Execution[];
+  /** Lines a tool did not run, across every turn: the run's count needs them. */
+  notRun: NotRunLine[];
 }
 
 /** Keeps outbound messages in the order the run produced them, across await points. */
@@ -67,10 +69,11 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
   let toldOutcome = false;
   const replies: string[] = [];
   const toolCalls: Array<{ name: string; refused: boolean }> = [];
+  const notRun: NotRunLine[] = [];
   let turns = 0;
 
   const presentInstrument = (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument): Promise<void> => {
-    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency)) outbox.push(body);
+    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency, s.locale)) outbox.push(body);
     // Awaited by the poll: the person has the code in hand before the next look, not after the cycle closed.
     return outbox.drain();
   };
@@ -95,7 +98,7 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
   const runtime = s.makeRuntime();
   const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, terminalOptions));
 
-  say(`${s.manifest.manifest.name} ${s.manifest.manifest.version} — canal: whatsapp (${channel.backend}) — approval: ${s.mode} — trilho: ${s.railKind} — ${s.kit.labels.mandateWord} ${s.mandate.id}`);
+  say(s.coreStrings.waBanner(s.manifest.manifest.name, s.manifest.manifest.version, channel.backend, s.mode, s.railKind, s.strings.mandateWord, s.mandate.id));
 
   try {
     for (;;) {
@@ -104,6 +107,7 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
       turns += 1;
       const result = await loop.turn(message.text);
       toolCalls.push(...result.tool_calls);
+      notRun.push(...result.not_run);
       // Whatever the execution put in the conversation goes first: the QR before the sentence that explains it.
       await outbox.drain();
       if (result.reply.trim()) await channel.say(result.reply);
@@ -116,5 +120,5 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
     await channel.close();
   }
 
-  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId) };
+  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId), notRun };
 }

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/session.ts

@@ -31,13 +31,15 @@ export interface SessionState {
 export type TemplateRefusal = { rule: string; detail: string } | undefined;
 
 export class SessionWindow {
-  private readonly templates: Map<string, WhatsAppTemplate>;
+  /** Every declared copy, by name: one per language, since Meta approves a template per (name, language). */
+  private readonly templates: Map<string, WhatsAppTemplate[]>;
   private lastInboundAt: number | undefined;
   /** The provider said the window is shut (131047) after ours read it open. Holds until the person writes again. */
   private shutByProvider = false;
 
   constructor(templates: readonly WhatsAppTemplate[], initial?: SessionState) {
-    this.templates = new Map(templates.map((t) => [t.name, t]));
+    this.templates = new Map();
+    for (const t of templates) this.templates.set(t.name, [...(this.templates.get(t.name) ?? []), t]);
     this.lastInboundAt = initial?.lastInboundAt;
   }
 
@@ -67,9 +69,9 @@ export class SessionWindow {
     return this.remainingSeconds(now) > 0;
   }
 
-  /** The declaration, for a caller that has to build a send: the language is the registry's, never the caller's guess. */
-  declared(name: string): WhatsAppTemplate | undefined {
-    return this.templates.get(name);
+  /** The copy declared in `language`, for a caller that has to build a send. `undefined` when the name or that language was never declared. */
+  declared(name: string, language: string): WhatsAppTemplate | undefined {
+    return this.templates.get(name)?.find((t) => t.language === language);
   }
 
   /**
@@ -80,17 +82,18 @@ export class SessionWindow {
    * delivers nothing, so each is refused here instead.
    */
   refuse(body: { template: string; language: string; variables: readonly string[] }): TemplateRefusal {
-    const declared = this.templates.get(body.template);
-    if (!declared) {
+    const copies = this.templates.get(body.template);
+    if (!copies) {
       return {
         rule: "template_unknown",
         detail: `the agent declares no template named ${body.template}; Meta only delivers templates it approved, and this one was never registered here`,
       };
     }
-    if (declared.language !== body.language) {
+    const declared = copies.find((t) => t.language === body.language);
+    if (!declared) {
       return {
         rule: "template_language_unknown",
-        detail: `${body.template} is declared in ${declared.language}, not ${body.language}; a template approved in one language does not exist in another`,
+        detail: `${body.template} is declared in ${copies.map((t) => t.language).join(", ")}, not ${body.language}; a template approved in one language does not exist in another`,
       };
     }
     const expected = templateArity(declared.body);

package/templates/collections-agent/packages/agent-runtime/src/cli.ts

@@ -5,7 +5,11 @@
  */
 import { stderr } from "node:process";
 import { loadAgent, type Agent } from "./agent.js";
-import { readDotEnv } from "./setup.js";
+import { NotATestKeyError } from "@codespar/agent-core";
+import { readAgentEnv } from "./env.js";
+import { envFileOf, localeFlag, resolveRailKind } from "./setup.js";
+import { loadManifest, resolveLocale } from "@codespar/agent-core";
+import { join } from "node:path";
 import { check } from "./commands/check.js";
 import { decide } from "./commands/decide.js";
 import { runEval } from "./commands/eval.js";
@@ -42,8 +46,23 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   }
   if (AGENTLESS.includes(command)) return verify(rest);
   const agent = await loadAgent(dir);
-  readDotEnv(agent.dir);
-  return run(agent, command, rest);
+  // The CLI's names for the deployment and the project are aliases of the kit's. Two that disagree stop a command that talks to the API; on the stub rail neither is read, and the run goes on.
+  const disagreement = readAgentEnv(agent.dir);
+  const railFlag = rest.includes("--rail") ? rest[rest.indexOf("--rail") + 1] : undefined;
+  if (disagreement && resolveRailKind(process.env, railFlag === "api" || railFlag === "stub" ? railFlag : undefined) === "api") {
+    stderr.write(disagreement.message + "\n");
+    return 1;
+  }
+  try {
+    return await run(agent, command, rest);
+  } catch (err) {
+    // A key refusal is the first thing a newcomer meets (#50): one sentence naming the file this agent reads, never a stack trace.
+    if (err instanceof NotATestKeyError) {
+      stderr.write(new NotATestKeyError(err.problem, envFileOf(agent.dir)).message + "\n");
+      return 1;
+    }
+    throw err;
+  }
 }
 
 async function run(agent: Agent, command: string, argv: string[]): Promise<number> {
@@ -56,7 +75,14 @@ async function run(agent: Agent, command: string, argv: string[]): Promise<numbe
         stderr.write(`${agent.slug}: this agent has no consent step (its policy is its own file, not a signed mandate)\n`);
         return 2;
       }
-      return agent.kit.consent({ agentDir: agent.dir, argv, say: (l) => void stderr.write(l + "\n") });
+      let locale;
+      try {
+        locale = resolveLocale(localeFlag(argv), loadManifest(join(agent.dir, "agent.yaml")).manifest);
+      } catch (err) {
+        stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+      }
+      return agent.kit.consent({ agentDir: agent.dir, argv, locale, say: (l) => void stderr.write(l + "\n") });
     }
     case "approve":
       return decide(agent, "approve", argv);