@codespar/cli 0.18.0 → 0.20.0

package/templates/hello-agent/packages/agent-core/test/locale.test.ts

@@ -0,0 +1,137 @@
+/**
+ * #64: the language of the strings the code prints. Resolved once per run
+ * (flag, manifest, default), declared in `agent.yaml` as an optional field,
+ * and backed by tables whose every key exists in every locale.
+ */
+import { describe, expect, it } from "vitest";
+import { CORE_STRINGS, DEFAULT_LOCALE, LOCALES, WHATSAPP_LANGUAGE, formatBRL, formatDay, parseLocale, parseManifest, parseTemplateRegistry, resolveLocale, tableGaps } from "../src/index.js";
+
+const MANIFEST = `
+schema: 1
+name: bills-agent
+version: 0.1.0
+approval: [human, mandate]
+default_approval: human
+mcp: "@codespar/mcp@0.5.8"
+cli: "@codespar/cli@0.18.1"
+tools: ./tools.json
+guardrails: ./guardrails.json
+mandate_schema: ./mandate.example.json
+events: [commerce.payment.succeeded]
+channels: [terminal]
+maturity:
+  pix-out: sandbox
+scenarios: ./scenarios/
+evals: ./evals/
+agents_md: ./AGENTS.md
+`;
+
+/** Calls a table entry with placeholder arguments of the arity it declares, so a function key is read as the text it prints. */
+function render(value: unknown): string {
+  if (typeof value === "string") return value;
+  const fn = value as (...args: unknown[]) => string;
+  return fn(...Array.from({ length: fn.length }, (_, i) => (i % 2 === 0 ? "X" : 2)));
+}
+
+describe("the locale of a run", () => {
+  it("is the flag, else the manifest's, else pt-BR", () => {
+    expect(resolveLocale("en", { locale: "pt-BR" })).toBe("en");
+    expect(resolveLocale(undefined, { locale: "en" })).toBe("en");
+    expect(resolveLocale(undefined, {})).toBe("pt-BR");
+    expect(DEFAULT_LOCALE).toBe("pt-BR");
+  });
+
+  it("is one of the two the kits speak, and anything else is refused by name", () => {
+    expect(parseLocale("en")).toBe("en");
+    expect(parseLocale("pt-BR")).toBe("pt-BR");
+    for (const bad of ["pt", "pt_BR", "en-US", "es", "EN", ""]) expect(() => parseLocale(bad)).toThrow(/--locale must be pt-BR or en/);
+  });
+
+  it("is an optional agent.yaml field: absent parses as before, en parses, anything else is refused", () => {
+    expect(parseManifest(MANIFEST).locale).toBeUndefined();
+    expect(parseManifest(MANIFEST + "locale: en\n").locale).toBe("en");
+    expect(parseManifest(MANIFEST + "locale: pt-BR\n").locale).toBe("pt-BR");
+    expect(() => parseManifest(MANIFEST + "locale: es\n")).toThrow();
+  });
+
+  it("sends a WhatsApp template in the language Meta approved it in for that locale", () => {
+    expect(WHATSAPP_LANGUAGE).toEqual({ "pt-BR": "pt_BR", en: "en_US" });
+  });
+
+  it("formats money and dates for its reader, from the same minor units", () => {
+    expect(formatBRL(185000, "pt-BR")).toBe("R$ 1.850,00");
+    expect(formatBRL(185000, "en")).toBe("R$1,850.00");
+    expect(formatBRL(-9, "pt-BR")).toBe("-R$ 0,09");
+    expect(formatBRL(-9, "en")).toBe("-R$0.09");
+    expect(formatDay("2026-09-30", "pt-BR")).toBe("30/09/2026");
+    expect(formatDay("2026-09-30", "en")).toBe("2026-09-30");
+  });
+});
+
+describe("the shared string table", () => {
+  it("has every key in every locale, with the same shape", () => {
+    expect(tableGaps("CORE_STRINGS", CORE_STRINGS)).toEqual([]);
+    expect(Object.keys(CORE_STRINGS.en).sort()).toEqual(Object.keys(CORE_STRINGS["pt-BR"]).sort());
+  });
+
+  it("prints text for every key in both locales, and never the word undefined", () => {
+    for (const locale of LOCALES) {
+      for (const [key, value] of Object.entries(CORE_STRINGS[locale])) {
+        const text = render(value);
+        expect(text.trim(), `${locale}.${key}`).not.toBe("");
+        expect(text, `${locale}.${key}`).not.toContain("undefined");
+      }
+    }
+  });
+
+  it("offers the answers the parsers read, in the language it asks in", () => {
+    expect(CORE_STRINGS["pt-BR"].batchQuestion).toContain("todas / todas exceto 3,7 / nenhuma");
+    expect(CORE_STRINGS.en.batchQuestion).toContain("all / all except 3,7 / none");
+  });
+
+  it("writes the Portuguese with its accents (#64)", () => {
+    const pt = CORE_STRINGS["pt-BR"];
+    expect(pt.execution).toBe("execução");
+    expect(pt.onlyDeny).toContain("o único desfecho possível é negar");
+    expect(pt.boletoLine).toBe("Ou pelo boleto, linha digitável:");
+    expect(pt.batchUnreadable(3)).toContain("não entendi");
+  });
+});
+
+describe("tableGaps: what npm run check reports", () => {
+  it("names a key one locale lacks, an empty string, a string against a function, and a different arity", () => {
+    const gaps = tableGaps("t", {
+      "pt-BR": { a: "a", b: "b", c: (x: string) => x, d: (x: string, y: string) => x + y, e: "" },
+      en: { a: "a", c: "c", d: (x: string) => x, e: "e" },
+    });
+    expect(gaps).toEqual([
+      "t.b is missing in en",
+      "t.c differs in shape across locales: pt-BR function/1, en string",
+      "t.d differs in shape across locales: pt-BR function/2, en function/1",
+      "t.e is empty string in pt-BR",
+      "t.e differs in shape across locales: pt-BR empty string, en string",
+    ]);
+  });
+
+  it("names a locale with no entry at all", () => {
+    expect(tableGaps("t", { "pt-BR": { a: "a" } })).toContain("t has no en entry");
+  });
+});
+
+describe("the template registry holds one copy per (name, language)", () => {
+  const template = (language: string, extra: Record<string, unknown> = {}) => ({ name: "acordo_quitado", language, description: "paid", body: "{{1}} quitado", ...extra });
+
+  it("accepts the same name in two languages, which is two templates to Meta", () => {
+    expect(parseTemplateRegistry(JSON.stringify({ channel: "whatsapp", templates: [template("pt_BR"), template("en_US")] })).templates).toHaveLength(2);
+  });
+
+  it("refuses the same pair declared twice", () => {
+    expect(() => parseTemplateRegistry(JSON.stringify({ channel: "whatsapp", templates: [template("pt_BR"), template("pt_BR")] }))).toThrow(/acordo_quitado is declared twice in pt_BR/);
+  });
+
+  it("refuses one reply id offered by two different templates, which would make a tap ambiguous", () => {
+    const button = { id: "emitir_nova", title: "Emitir nova", intent: "emita" };
+    const doc = { channel: "whatsapp", templates: [template("pt_BR", { buttons: [button] }), { ...template("pt_BR", { buttons: [button] }), name: "outro" }] };
+    expect(() => parseTemplateRegistry(JSON.stringify(doc))).toThrow(/reply id emitir_nova/);
+  });
+});

package/templates/hello-agent/packages/agent-core/test/mandate-status.test.ts

@@ -75,8 +75,8 @@ beforeEach(() => {
 });
 
 function apiClient(timeoutMs = 5_000) {
-  // The placeholder passes the `csk_test_` guard and is the one test-key-shaped string the secret scan allows.
-  return createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs });
+  // Not the placeholder, which the guard refuses (#50); the underscore keeps it below the secret scan's key shape.
+  return createCodeSparClient({ apiKey: "csk_test_unit_0000", baseUrl, timeoutMs });
 }
 
 function apiSource(timeoutMs = 5_000): ApiMandateStatusSource {

package/templates/hello-agent/packages/agent-core/test/manifest.test.ts

@@ -12,7 +12,7 @@ escalate_above:
   new_beneficiary: true
   outside_hours: "22:00-07:00"
 mcp: "@codespar/mcp@0.5.8"
-cli: "@codespar/cli@0.14.0"
+cli: "@codespar/cli@0.18.1"
 tools: ./tools.json
 guardrails: ./guardrails.json
 mandate_schema: ./mandate.example.json
@@ -36,7 +36,7 @@ describe("section 4.3: agent.yaml schema 1", () => {
 
   it("refuses an unpinned mcp or cli, a wrong schema, and an unknown field", () => {
     expect(() => parseManifest(valid.replace('"@codespar/mcp@0.5.8"', '"@codespar/mcp"'))).toThrow(/mcp/);
-    expect(() => parseManifest(valid.replace('"@codespar/cli@0.14.0"', '"@codespar/cli@latest"'))).toThrow(/cli/);
+    expect(() => parseManifest(valid.replace('"@codespar/cli@0.18.1"', '"@codespar/cli@latest"'))).toThrow(/cli/);
     expect(() => parseManifest(valid.replace("schema: 1", "schema: 2"))).toThrow();
     expect(() => parseManifest(valid + "telemetry: true\n")).toThrow(/unrecognized/i);
     expect(() => parseManifest(valid.replace("default_approval: human", "default_approval: mandate").replace("approval: [human, mandate]", "approval: [human]"))).toThrow(/default_approval/);

package/templates/hello-agent/packages/agent-core/test/rail-errors.test.ts

@@ -0,0 +1,74 @@
+/**
+ * #50: a rail failure carries the API's own code and message, verbatim, out
+ * of the engine — not only `rail_failed`. Both answers are real ones the
+ * deployed API gave the kits on production test mode: the 409
+ * `insufficient_funds` of an unfunded wallet (ent#1803) and the 5xx
+ * `provider_error` of a charge with no receiving identity (ent#1809). They go
+ * through the real SDK client against a local server, so the code and the
+ * message are the ones the SDK hands the rail, not ones a fake invents.
+ */
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { CodeSparRail } from "../src/api/rail.js";
+import { createCodeSparClient } from "../src/api/client.js";
+import { railErrorOf } from "../src/engine.js";
+import { harness } from "./helpers.js";
+
+const INSUFFICIENT = { status: 409, body: { error: { code: "insufficient_funds", message: "wallet cannot reserve the requested amount" }, request_id: null } };
+const PROVIDER = {
+  status: 502,
+  body: { error: { code: "provider_error", message: "charge_boleto_brl_celcoin_v1: no receiving identity at the provider for this consumer" }, request_id: null },
+};
+
+let server: Server;
+let baseUrl: string;
+let answer: { status: number; body: unknown } = INSUFFICIENT;
+
+beforeAll(async () => {
+  server = createServer((_req, res) => {
+    res.writeHead(answer.status, { "content-type": "application/json" });
+    res.end(JSON.stringify(answer.body));
+  });
+  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
+  baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+afterAll(async () => {
+  server.closeAllConnections();
+  await new Promise<void>((ok) => server.close(() => ok()));
+});
+
+async function spend() {
+  // Not the placeholder, which the guard refuses (#50); the underscore keeps it below the secret scan's key shape.
+  const h = harness({ mode: "human", wrapRail: () => new CodeSparRail(createCodeSparClient({ apiKey: "csk_test_unit_0000", baseUrl, timeoutMs: 5_000 })) });
+  const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+  if (!d.ok) throw new Error("refused");
+  return h.engine.execute(h.engine.approve(d.execution.id, { id: "usr_demo", channel: "terminal" }).id);
+}
+
+describe("the rail's answer, verbatim", () => {
+  it("a 409 insufficient_funds closes the execution failed, and says so in the API's words", async () => {
+    answer = INSUFFICIENT;
+    const out = await spend();
+    expect(out.state).toBe("failed");
+    expect(out.reason).toBe("rail_failed");
+    expect(railErrorOf(out)).toEqual({ outcome: "failed", attempt_id: out.outcomes[0]!.attempt_id, code: "insufficient_funds", message: "wallet cannot reserve the requested amount" });
+  });
+
+  it("a 5xx provider_error leaves the attempt unknown, and still carries what the API said", async () => {
+    answer = PROVIDER;
+    const out = await spend();
+    expect(out.state).toBe("executing");
+    expect(out.reason).toBe("rail_uncertain");
+    expect(out.outcomes).toHaveLength(0);
+    expect(railErrorOf(out)).toMatchObject({ outcome: "uncertain", code: "provider_error", message: PROVIDER.body.error.message });
+  });
+
+  it("an unknown answer is superseded once its attempt has an outcome", () => {
+    const answers = [{ attempt_id: "att_0", code: "provider_error", message: "x" }];
+    expect(railErrorOf({ outcomes: [], uncertain_answers: answers })).toMatchObject({ outcome: "uncertain" });
+    expect(railErrorOf({ outcomes: [{ index: 0, attempt_id: "att_0", status: "settled" }], uncertain_answers: answers })).toBeNull();
+    expect(railErrorOf({ outcomes: [] })).toBeNull();
+  });
+});

package/templates/hello-agent/packages/agent-core/test/receipt-read-verification.test.ts

@@ -124,6 +124,37 @@ describe("a v4 receipt: signature, body and approval", () => {
     expect(report.message).toContain(ITEMS_HASH);
   });
 
+  it("reports sandbox and money_moved off the bound body, and no other field of the read", () => {
+    for (const report of [verifyReceiptRead(sealed(4), keyDocument()), verifyReceiptRead(sealed(4), keyDocument(), { approval: artifact() })]) {
+      expect(report.sealed_payment).toEqual({ sandbox: true, money_moved: false });
+      expect(JSON.stringify(report)).not.toContain(MANDATE_SIG);
+    }
+  });
+
+  it("reports a field the recipe does not seal as null, not as the read's value", () => {
+    const base = PUBLISHED["chain_recipe"] as { links: Array<{ from: string; fields?: string[] }> };
+    const recipe = { ...base, links: base.links.map((l) => (l.from === "payment" ? { ...l, fields: l.fields!.filter((f) => f !== "sandbox?") } : l)) };
+    const b = body(4, { items_hash: ITEMS_HASH, batch_hash: null });
+    const m = b.mandate;
+    const q = b.quote;
+    const p = b.payment;
+    const chain = sha256(
+      canonicalize({
+        v: 4,
+        links: [
+          { id: m.id, nonce: m.nonce, scope: m.scope, currency: m.currency, sig_sha256: m.sig_sha256 },
+          { seller: q.seller, resource: q.resource, price_minor: q.price_minor, payee: q.payee, session_id: q.session_id, sig: q.sig, at: q.at },
+          b.approval,
+          { rail: p.rail, provider: p.provider, tx_id: p.tx_id, amount_minor: p.amount_minor, attempt_id: p.attempt_id, money_moved: p.money_moved, at: p.at },
+        ],
+      }),
+    );
+    const read = { ...sealed(4), chain, receipt_sig_ed25519: signDetached(null, Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${chain}`, "utf8"), privateKey).toString("base64url") };
+    const report = verifyReceiptRead(read, keyDocument({ chain_recipe: recipe }));
+    expect(report.verdict).toBe("verified");
+    expect(report.sealed_payment).toEqual({ sandbox: null, money_moved: false });
+  });
+
   it("is chain_mismatch when the body beside a genuine signature was changed: payee, amount, approval", () => {
     const read = sealed(4);
     const q = read["quote"] as Record<string, unknown>;
@@ -136,6 +167,7 @@ describe("a v4 receipt: signature, body and approval", () => {
       const report = verifyReceiptRead(altered, keyDocument(), { approval: artifact() });
       expect(report.verdict).toBe("chain_mismatch");
       expect(report.chain_check).toMatchObject({ status: "mismatch", version: 4 });
+      expect(report.sealed_payment).toBeUndefined();
       expect(VERDICT_EXIT_CODES[report.verdict]).toBe(8);
     }
   });

package/templates/hello-agent/packages/agent-core/test/receivables.test.ts

@@ -261,6 +261,12 @@ describe("outcomeOf: the API's charge view, mapped by fields and never by prose"
     expect(outcomeOf({ ...base, status: "CANCELLED" })).toMatchObject({ status: "failed", code: "charge_cancelled" });
     expect(outcomeOf({ ...base, id: null, issuance_unconfirmed: true })).toEqual({ status: "in_flight" });
   });
+  it("an issuer that ends the registration in ERROR fails the attempt with charge_issuer_error; a status nobody documented stays accepted and unpayable", () => {
+    const errored = { ...base, status: "ERROR", payable: false, pix_copy_paste: null, boleto_bank_line: null, boleto_bar_code: null };
+    expect(outcomeOf(errored)).toMatchObject({ status: "failed", code: "charge_issuer_error" });
+    expect((outcomeOf(errored) as { message: string }).message).toContain("ERROR");
+    expect(outcomeOf({ ...errored, status: "SOMETHING_NEW" })).toMatchObject({ status: "accepted", instrument: { payable: false, status: "SOMETHING_NEW" } });
+  });
   it("a payment notified and not yet credited is still accepted: nothing settles on a notification", () => {
     expect(outcomeOf({ ...base, payment_in_flight: true, settlement: "pending" })).toMatchObject({ status: "accepted" });
   });
@@ -317,6 +323,49 @@ describe("paySandboxCharge: the SDK's typed call to the payer route", () => {
   });
 });
 
+describe("payIfPayable: the sandbox payer pays only what a payer could have paid (OPEN_QUESTIONS §63, ent#1816)", () => {
+  const view = (over: Record<string, unknown>) => ({ id: "chg_1", status: "PENDING", local_status: "pending", status_conflict: false, method: "boleto", currency: "BRL", amount: 1080, amount_minor: 108000, due_date: "2026-09-30", payable: true, boleto_bar_code: "1".repeat(44), boleto_bank_line: "2".repeat(47), pix_copy_paste: "000201...", credit_correlation_armed: true, payment_in_flight: false, settlement: null, issuance_unconfirmed: false, ...over });
+  const paid = { charge_id: "chg_1", status: "paid", local_status: "settled", simulated: true, settled_against: "sandbox_fixture", money_moved: false, quoted_minor: 108000, paid_minor: 108000, payment: "full", idempotent_replay: false };
+
+  async function withCharge(read: Record<string, unknown>) {
+    const { payIfPayable } = await import("../src/api/sandbox-payer.js");
+    const { createCodeSparClient } = await import("../src/api/client.js");
+    const seen: Array<{ method: string; url: string }> = [];
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string | URL | Request, init?: RequestInit) => {
+      const method = init?.method ?? "GET";
+      seen.push({ method, url: String(url) });
+      return new Response(JSON.stringify(method === "GET" ? read : paid), { status: 200, headers: { "content-type": "application/json" } });
+    }) as typeof fetch;
+    try {
+      const out = await payIfPayable(createCodeSparClient({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/" }), "chg_1");
+      return { out, seen };
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  }
+  const posts = (seen: Array<{ method: string }>) => seen.filter((s) => s.method === "POST").length;
+
+  it("a charge the issuer ended in ERROR: refused as charge_issuer_error, and the pay route is never called", async () => {
+    const { out, seen } = await withCharge(view({ status: "ERROR", payable: false, pix_copy_paste: null, boleto_bank_line: null, boleto_bar_code: null }));
+    expect(out).toMatchObject({ ok: false, refused: { code: "charge_issuer_error" } });
+    expect(seen.map((s) => `${s.method} ${s.url}`)).toEqual(["GET https://api.example.test/v1/charges/chg_1"]);
+    expect(posts(seen)).toBe(0);
+  });
+
+  it("a charge still registering, with no QR and no line: refused as no_payable_instrument, and the pay route is never called", async () => {
+    const { out, seen } = await withCharge(view({ status: "PROCESSING", payable: false, pix_copy_paste: null, boleto_bank_line: null, boleto_bar_code: null }));
+    expect(out).toMatchObject({ ok: false, refused: { code: "no_payable_instrument" } });
+    expect(posts(seen)).toBe(0);
+  });
+
+  it("a payable charge is paid, once", async () => {
+    const { out, seen } = await withCharge(view({}));
+    expect(out).toMatchObject({ ok: true, state: { status: "paid", settled_against: "sandbox_fixture" } });
+    expect(seen.map((s) => `${s.method} ${s.url}`)).toEqual(["GET https://api.example.test/v1/charges/chg_1", "POST https://api.example.test/v1/test/charges/chg_1/pay"]);
+  });
+});
+
 describe("CodeSparChargeRail.read: a 409 is branched on its code, never on the status alone", () => {
   const VIEW = { id: "chg_409", status: "PROCESSING", local_status: "pending", status_conflict: false, method: "boleto", currency: "BRL", amount: 1080, amount_minor: 108000, due_date: "2026-09-30", payable: false, boleto_bar_code: null, boleto_bank_line: null, pix_copy_paste: null, credit_correlation_armed: false, payment_in_flight: false, settlement: null, issuance_unconfirmed: false };
 

package/templates/hello-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/hello-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/hello-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/hello-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/hello-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);
   }
 }