@codespar/cli 0.18.1 → 0.20.0

package/templates/bills-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -14,6 +14,7 @@
  */
 import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
 import type { ApiFailure } from "./client.js";
+import { ISSUER_ERROR_STATUSES, type ChargeView } from "./charge-rail.js";
 import { createCodeSparClient, describeApiError } from "./client.js";
 
 /** What the payer route answers, as the SDK's generated OpenAPI types it. */
@@ -41,3 +42,38 @@ export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, c
     return { ok: false, failure: describeApiError(err) };
   }
 }
+
+/** Why the payer did not call the pay route: there was nothing a payer could have paid. */
+export type PayerRefusal = { code: "no_payable_instrument" | "charge_issuer_error"; message: string };
+
+export type GuardedPayResult = SandboxPayResult | { ok: false; refused: PayerRefusal };
+
+/**
+ * The sandbox payer as a PAYER: it reads the charge first and pays only an
+ * instrument a person could have paid, a Pix or a boleto line the read calls
+ * `payable`. A charge the issuer ended in error (`ERROR`) is refused as
+ * `charge_issuer_error`, anything else unpayable as `no_payable_instrument`,
+ * and in both cases the pay route is never called.
+ *
+ * The route itself settles whatever it is handed: a charge still
+ * `PROCESSING`, and on staging on 2026-09-27 a charge the issuer ended in
+ * `ERROR`, after which the read answers `CONFIRMED` (ent#1816,
+ * OPEN_QUESTIONS §63). A payer that trusted it turned an issuance that failed
+ * into a "settled" order no customer could have paid. No live payer can pay a
+ * charge with no instrument, so neither does this one.
+ */
+export async function payIfPayable(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<GuardedPayResult> {
+  let view: ChargeView;
+  try {
+    view = await api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } });
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+  if (ISSUER_ERROR_STATUSES.includes(view.status)) {
+    return { ok: false, refused: { code: "charge_issuer_error", message: `the issuer ended charge ${chargeRef}'s registration in ${view.status}; there is no instrument to pay, so the pay route was not called` } };
+  }
+  if (!view.payable) {
+    return { ok: false, refused: { code: "no_payable_instrument", message: `charge ${chargeRef} has no payable instrument (status ${view.status}, local ${view.local_status}); the pay route was not called` } };
+  }
+  return paySandboxCharge(api, chargeRef, amountMinor);
+}

package/templates/bills-agent/packages/agent-core/src/bundle.ts

@@ -178,6 +178,8 @@ export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Recor
   // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
   if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
   if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  // Written onto the copy since every spend carries the actor (§2); the read calls it `actor`, the copy `sealed_actor` beside its own stamp.
+  if ("sealed_actor" in copy) expected.push(["sealed_actor", canonicalJson(copy["sealed_actor"] ?? null), canonicalJson(read["actor"] ?? null)]);
   return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
 }
 

package/templates/bills-agent/packages/agent-core/src/channels.ts

@@ -154,22 +154,32 @@ export const TemplateRegistrySchema = z
   })
   .strict()
   .superRefine((registry, ctx) => {
+    // Meta approves a template per (name, language): the same name in two languages is two templates, the same pair twice is one declared twice.
     const seen = new Set<string>();
     const replyIds = new Set<string>();
+    const replyOwner = new Map<string, string>();
     for (const [i, template] of registry.templates.entries()) {
-      if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
-      seen.add(template.name);
-      // A tap is resolved by its id alone, so one id means one intent across the whole registry.
+      const pair = `${template.name}/${template.language}`;
+      if (seen.has(pair)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice in ${template.language}` });
+      seen.add(pair);
+      // A tap is resolved by its id in the conversation's language, so one id means one intent per language, and one template across languages.
       for (const [j, button] of (template.buttons ?? []).entries()) {
-        if (replyIds.has(button.id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice` });
-        replyIds.add(button.id);
+        if (replyIds.has(`${button.id}/${template.language}`)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice in ${template.language}` });
+        replyIds.add(`${button.id}/${template.language}`);
+        const owner = replyOwner.get(button.id);
+        if (owner !== undefined && owner !== template.name) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is offered by ${owner} and by ${template.name}` });
+        replyOwner.set(button.id, template.name);
       }
     }
   });
 
-/** Every quick reply the registry declares, by id: the only taps that can become a turn. */
-export function declaredReplies(templates: readonly WhatsAppTemplate[]): Map<string, QuickReply> {
-  return new Map(templates.flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
+/**
+ * Every quick reply the registry declares, by id: the only taps that can
+ * become a turn. With a `language`, only the copies declared in it: an English
+ * conversation hands the model the English intent of the button it tapped.
+ */
+export function declaredReplies(templates: readonly WhatsAppTemplate[], language?: string): Map<string, QuickReply> {
+  return new Map(templates.filter((t) => language === undefined || t.language === language).flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
 }
 
 export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;

package/templates/bills-agent/packages/agent-core/src/check.ts

@@ -14,6 +14,7 @@ import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js
 import { MandateSchema } from "./mandate.js";
 import { ToolsFileSchema } from "./tools.js";
 import { canonicalJson } from "./hash.js";
+import { LOCALES, WHATSAPP_LANGUAGE } from "./locale.js";
 import { PUBLISHED_EVENTS, isPublishedEvent } from "./events.js";
 
 export interface CheckFinding {
@@ -145,9 +146,30 @@ export function checkAgent(agentDir: string): CheckReport {
   if (manifest.channels.includes("whatsapp")) {
     if (!existsSync(registryPath)) error("channels_templates_missing", `agent.yaml declares the whatsapp channel and channels/whatsapp/${TEMPLATE_REGISTRY_FILE} does not exist`);
     else if (registry) {
-      const fallbacks = registry.templates.filter((t) => t.fallback);
-      if (fallbacks.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${fallbacks.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
-      else if (templateArity(fallbacks[0]!.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallbacks[0]!.name} takes variables; it is sent when nothing specific can be said, so it takes none`);
+      const names = [...new Set(registry.templates.filter((t) => t.fallback).map((t) => t.name))];
+      if (names.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${names.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
+      for (const fallback of registry.templates.filter((t) => t.fallback)) {
+        if (templateArity(fallback.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallback.name} (${fallback.language}) takes variables; it is sent when nothing specific can be said, so it takes none`);
+      }
+    }
+  }
+  // A conversation speaks the language of its locale, and either locale can be
+  // chosen per run (`--locale`), so every template exists in the language of
+  // every locale, with the same buttons and the same variables. A template
+  // missing in one language is an outcome that locale cannot tell once the
+  // 24-hour window shuts.
+  if (registry) {
+    const languages = LOCALES.map((l) => WHATSAPP_LANGUAGE[l]);
+    for (const template of registry.templates) {
+      if (!languages.includes(template.language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${template.name} is declared in ${template.language}, which no locale sends; the locales send ${languages.join(", ")}`);
+    }
+    for (const name of [...new Set(registry.templates.map((t) => t.name))]) {
+      const copies = registry.templates.filter((t) => t.name === name);
+      for (const language of languages) {
+        if (!copies.some((t) => t.language === language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${name} has no ${language} copy; a conversation in that locale could not send it`);
+      }
+      const shape = (t: (typeof copies)[number]) => JSON.stringify({ arity: templateArity(t.body), buttons: (t.buttons ?? []).map((b) => b.id), fallback: t.fallback ?? false });
+      if (new Set(copies.map(shape)).size > 1) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: the copies of ${name} differ in variables, buttons or fallback across languages; a translation says the same thing`);
     }
   }
   if (existsSync(registryPath)) {

package/templates/bills-agent/packages/agent-core/src/engine.ts

@@ -13,7 +13,7 @@
  */
 import { checkApprovalArtifact, createApprovalArtifact, type ApprovalSigner } from "./approval.js";
 import { maskPayee, type ProofBundle } from "./bundle.js";
-import { evaluateEscalation, type Escalation } from "./escalate.js";
+import { evaluateEscalation, localDate, type Escalation } from "./escalate.js";
 import { CHARGE_CANCELLED, CHARGE_EXPIRED, CHARGE_PAID, PAYMENT_FAILED, PAYMENT_SUCCEEDED, type PublishedEvent } from "./events.js";
 import type { Guardrails } from "./guardrails.js";
 import { batchAttemptId, itemsHash, sha256Hex } from "./hash.js";
@@ -21,10 +21,10 @@ import { newId } from "./ids.js";
 import { mandateExpired, payeeAllowed, resolveBeneficiary, windowCap, windowStart, type Mandate } from "./mandate.js";
 import type { Manifest } from "./manifest.js";
 import { checkQuote, quoteFromApproval } from "./quote.js";
-import { spendApprovalOf, type PaymentRail, type RailOutcome, type RailPayment, type SealedSpendApproval, type SpendApproval } from "./rail.js";
+import { sameWireActor, spendApprovalOf, wireActorOf, type PaymentRail, type RailOutcome, type RailPayment, type SealedSpendApproval, type SpendApproval } from "./rail.js";
 import { sameApprovalHash } from "./receipt-chain.js";
 import type { MandateStatusReport, MandateStatusSource } from "./revocation.js";
-import { isTerminal, transition, type Execution, type ExecutionState } from "./state-machine.js";
+import { isTerminal, transition, type Execution, type ExecutionState, type RailAnswer } from "./state-machine.js";
 import type { StateStore } from "./state/store.js";
 import type { Actor, ApprovalArtifact, ApprovalMode, ExecutionBatch, ExecutionComposition, ExecutionItem, ExecutionReason, ItemOutcome } from "./types.js";
 
@@ -131,6 +131,16 @@ export class ExecutionEngine {
     return this.deps.mandate;
   }
 
+  /**
+   * The day it is for the person, in the guardrails' timezone, at this
+   * engine's clock (so `--now` pins it too). A tool that shows a due date
+   * shows this next to it: the model has no calendar of its own, and without
+   * it a bill due next week reads as one that already fell due.
+   */
+  today(): string {
+    return localDate(this.clock(), this.deps.guardrails.timezone);
+  }
+
   // ---- the model's only entry point -------------------------------------
 
   async draft(proposal: Proposal): Promise<DraftResult> {
@@ -420,6 +430,7 @@ export class ExecutionEngine {
   private async dispatch(execution: Execution<"executing">, payments: RailPayment[]): Promise<Execution> {
     const outcomes: ItemOutcome[] = [...execution.outcomes];
     const unknown: string[] = [];
+    const unknownAnswers: RailAnswer[] = [];
     const sealMismatches: string[] = [];
     this.deps.store.updateOutbox(execution.idempotency_key, "sent", undefined, this.clock().toISOString());
 
@@ -453,10 +464,11 @@ export class ExecutionEngine {
         // sent: an unknown answer about THIS payee says nothing about the next
         // one, and the execution stays open until reconciliation settles it.
         unknown.push(`attempt ${payment.attempt_id}: ${outcome.code} — outcome unknown, kept for reconciliation`);
+        unknownAnswers.push({ attempt_id: payment.attempt_id, code: outcome.code, message: outcome.message });
         continue;
       }
       if (outcome.status === "failed") {
-        outcomes.push({ index, attempt_id: payment.attempt_id, status: "failed", code: outcome.code, error: `${outcome.code}: ${outcome.message}`, ...(outcome.held ? { held: outcome.held } : {}) });
+        outcomes.push({ index, attempt_id: payment.attempt_id, status: "failed", code: outcome.code, message: outcome.message, error: `${outcome.code}: ${outcome.message}`, ...(outcome.held ? { held: outcome.held } : {}) });
         continue;
       }
       if (outcome.status === "accepted") {
@@ -469,7 +481,12 @@ export class ExecutionEngine {
       const mismatch = await this.ingestSettlement(execution, index, payment, outcome.receipt_id, PAYMENT_SUCCEEDED);
       if (mismatch) sealMismatches.push(mismatch);
     }
-    const closed = this.close({ ...execution, outcomes, ...(Object.keys(generations).length > 0 ? { attempt_generations: generations } : {}) }, payments.length, unknown.join("; ") || undefined);
+    const answers = [...(execution.uncertain_answers ?? []).filter((a) => !unknownAnswers.some((u) => u.attempt_id === a.attempt_id)), ...unknownAnswers];
+    const closed = this.close(
+      { ...execution, outcomes, ...(Object.keys(generations).length > 0 ? { attempt_generations: generations } : {}), ...(answers.length > 0 ? { uncertain_answers: answers } : {}) },
+      payments.length,
+      unknown.join("; ") || undefined,
+    );
     if (sealMismatches.length > 0) throw new ReceiptSealMismatchError(execution.id, sealMismatches);
     return closed;
   }
@@ -494,13 +511,12 @@ export class ExecutionEngine {
     if (execution.outcomes.length < attempts) {
       return this.leaveUnresolved(updated, unknownDetail ?? `${execution.outcomes.length} of ${attempts} attempt(s) have an outcome`);
     }
-    // An ambiguous receivable outranks any other failure: it is the one outcome that must be reconciled rather than issued again.
-    const failed = execution.outcomes.find((o) => o.status === "failed" && o.code === "charge_reference_ambiguous") ?? execution.outcomes.find((o) => o.status === "failed");
+    const failed = decisiveFailure(execution.outcomes);
     if (failed) {
       this.deps.store.updateOutbox(execution.idempotency_key, "failed", execution.outcomes, at);
       // `org_paused` is the API refusing the spend itself: the kill switch was pressed after the gate read the status. Nothing moved.
       const reason: ExecutionReason =
-        failed.code === "charge_expired" || failed.code === "charge_cancelled" || failed.code === "org_paused" || failed.code === "charge_reference_ambiguous" ? failed.code : "rail_failed";
+        failed.code === "charge_expired" || failed.code === "charge_cancelled" || failed.code === "charge_issuer_error" || failed.code === "org_paused" || failed.code === "charge_reference_ambiguous" ? failed.code : "rail_failed";
       return this.persist(transition(updated, "failed", { at, actor: this.agentActor, reason, detail: failed.error ?? "rail refused" }));
     }
     if (execution.outcomes.filter((o) => o.status === "settled").length === attempts) {
@@ -584,6 +600,11 @@ export class ExecutionEngine {
       this.record("receipt.seal_mismatch", executionId, { receipt_id: receiptId, attempt_id: payment.attempt_id, sealed_approval: receipt.approval, sent_approval: payment.approval });
       mismatches.push(`receipt ${receiptId} seals approval ${receipt.approval ? receipt.approval.items_hash : "none"}; attempt ${payment.attempt_id} sent ${payment.approval.items_hash}`);
     }
+    // §2: the actor the spend declared, as the API recorded it. A different one, or none, is an event and not a seal mismatch:
+    // the money and its link to the approval are what the receipt proves, and who triggered it is what it RECORDS.
+    if (receipt.sealed_actor !== undefined && !sameWireActor(receipt.sealed_actor, wireActorOf(payment.actor))) {
+      this.record("receipt.actor_mismatch", executionId, { receipt_id: receiptId, attempt_id: payment.attempt_id, sealed_actor: receipt.sealed_actor, sent_actor: wireActorOf(payment.actor) });
+    }
     return mismatches.length > 0 ? mismatches.join("; ") : undefined;
   }
 
@@ -671,7 +692,12 @@ export class ExecutionEngine {
         replace({ index, attempt_id: payment.attempt_id, status: "failed", code: seen.code, error: `${seen.code}: ${seen.message}`, ...(seen.held ? { held: seen.held } : {}) });
         continue;
       }
-      replace({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: seen.transaction_id, ...(seen.receipt_id ? { receipt_id: seen.receipt_id } : {}), ...(seen.replayed ? { replayed: true as const } : {}) });
+      // No `replayed` here, whatever the rail said. A lookup IS a second
+      // presentation of an attempt this execution already sent, so on the API
+      // every settled lookup answers `idempotent_replay`, including the one
+      // whose payment was this execution's own. The mark would say "someone
+      // else paid" about a payment nobody can attribute from here.
+      replace({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: seen.transaction_id, ...(seen.receipt_id ? { receipt_id: seen.receipt_id } : {}) });
       const mismatch = await this.ingestSettlement(execution, index, payment, seen.receipt_id, prior ? CHARGE_PAID : PAYMENT_SUCCEEDED);
       if (mismatch) sealMismatches.push(mismatch);
     }
@@ -1050,6 +1076,61 @@ function railAnswer(outcome: RailOutcome): Record<string, unknown> {
   }
 }
 
+/** The failed outcome an execution closes on. An ambiguous receivable outranks any other failure: it is the one outcome that must be reconciled rather than issued again. */
+function decisiveFailure(outcomes: readonly ItemOutcome[]): ItemOutcome | undefined {
+  return outcomes.find((o) => o.status === "failed" && o.code === "charge_reference_ambiguous") ?? outcomes.find((o) => o.status === "failed");
+}
+
+/** What the rail answered, verbatim: the code and message the API sent, not only `rail_failed` or `rail_uncertain` (#50). */
+export interface RailError {
+  /** `failed`: the answer the execution closed on. `uncertain`: an answer that left an attempt's outcome unknown. */
+  outcome: "failed" | "uncertain";
+  attempt_id: string;
+  code: string;
+  message: string | null;
+}
+
+/**
+ * The rail's own answer behind a failure, for `--json` and the terminal. The
+ * reason (`rail_failed`) says WHICH gate closed the execution; this says what
+ * the API said, so a first failure explains itself — `insufficient_funds` on
+ * an unfunded test wallet reads as that, not as a generic refusal. `null` when
+ * nothing failed and nothing was left unknown. A 5xx is not a failure — the
+ * money may have moved — so `provider_error` comes back as `uncertain`, with
+ * the API's words, while the execution stays open for reconciliation. An
+ * outcome stored before the message was kept carries only `code: message` in
+ * `error`, and that is what is returned.
+ */
+export function railErrorOf(execution: Pick<Execution, "outcomes" | "uncertain_answers">): RailError | null {
+  const failed = decisiveFailure(execution.outcomes);
+  if (failed?.code !== undefined) return { outcome: "failed", attempt_id: failed.attempt_id, code: failed.code, message: failed.message ?? failed.error ?? null };
+  const pending = (execution.uncertain_answers ?? []).find((a) => !execution.outcomes.some((o) => o.attempt_id === a.attempt_id));
+  return pending ? { outcome: "uncertain", attempt_id: pending.attempt_id, code: pending.code, message: pending.message } : null;
+}
+
+/**
+ * Settled, and every settled attempt was answered from the rail's record of
+ * an earlier presentation this execution never made: the money moved, and
+ * this execution did not move it. `dispatch` is the only writer of the mark,
+ * so a report can say "paid by this run" of everything else it calls settled.
+ */
+export function isReplayedSettlement(execution: Pick<Execution, "state" | "outcomes">): boolean {
+  const settled = execution.outcomes.filter((o) => o.status === "settled");
+  return execution.state === "settled" && settled.length > 0 && settled.every((o) => o.replayed === true);
+}
+
+/**
+ * A reason, or a rail code, that closes a payment without anything having
+ * failed: nobody paid the charge in time, the charge was withdrawn, or the
+ * organization pressed the kill switch. It reads with `denied` and `expired`,
+ * not with a rail failure, in every count and report.
+ */
+const DECLINED_REASONS: readonly string[] = ["charge_expired", "charge_cancelled", "org_paused"];
+
+export function isDeclinedReason(reason: string | null | undefined): boolean {
+  return typeof reason === "string" && DECLINED_REASONS.includes(reason);
+}
+
 /** The approval link a receipt sealed is the one a spend sent: the same hashes, in either spelling of the `sha256:` prefix. */
 function sealsApproval(sealed: SealedSpendApproval | null, sent: SpendApproval): boolean {
   return sealed !== null && sameApprovalHash(sealed.items_hash, sent.items_hash) && sameApprovalHash(sealed.batch_hash, sent.batch_hash ?? null);

package/templates/bills-agent/packages/agent-core/src/escalate.ts

@@ -71,6 +71,16 @@ export function localClock(now: Date, timezone: string): string {
   return `${hour}:${minute}`;
 }
 
+/** The calendar day `now` falls on in `timezone`, as `YYYY-MM-DD`. */
+export function localDate(now: Date, timezone: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" }).format(now);
+}
+
+/** Whole days from `today` to `date` (both `YYYY-MM-DD`): 0 is today, negative is already past. */
+export function daysUntil(today: string, date: string): number {
+  return Math.round((Date.parse(`${date}T00:00:00Z`) - Date.parse(`${today}T00:00:00Z`)) / 86_400_000);
+}
+
 /** `"22:00-07:00"` is the CLOSED window: inside it, the trigger fires. Crosses midnight when start > end. */
 export function isOutsideHours(window: string, now: Date, timezone: string): boolean {
   const [start, end] = window.split("-") as [string, string];

package/templates/bills-agent/packages/agent-core/src/index.ts

@@ -19,6 +19,9 @@ export * from "./tools.js";
 export * from "./bundle.js";
 export * from "./engine.js";
 export * from "./agent.js";
+export * from "./language.js";
+export * from "./locale.js";
+export * from "./strings.js";
 export * from "./check.js";
 export * from "./events.js";
 export * from "./state/store.js";

package/templates/bills-agent/packages/agent-core/src/language.ts

@@ -0,0 +1,52 @@
+/**
+ * The language a person wrote in, of the two the kits speak, and the sentence
+ * that tells the model to answer in it.
+ *
+ * A rule in the system prompt ("answer in the language of the person's latest
+ * message") was not enough (docs/OPEN_QUESTIONS.md §64): on the Messages API a
+ * tool result is a user-role message, so on any turn that used a tool the
+ * latest message the model read was Portuguese data, and five English requests
+ * out of five were answered in Portuguese. The loop therefore reads the
+ * language from what the person TYPED, deterministically, and states it for
+ * the whole turn.
+ *
+ * Function words, not a classifier: payee names, bill descriptions and
+ * amounts are the same in both languages and count for neither.
+ */
+
+export type ReplyLanguage = "pt-BR" | "en";
+
+const PT = new Set(
+  "de da das do dos para pra pro que com um uma os é está esta estou já foi o e em na nas nos no ao aos meu minha minhas meus você voce vocês não nao sim oi olá ola quanto quanta quais qual quero queria pague paga pagar pagamento pagamentos manda mande mandar roda rode rodar gastei gastou mês mes conta contas folha essa esse isso esta este semana tudo vence venceu obrigado obrigada por favor hoje agora fechado até como onde quando quem aqui sou eu pode posso preciso".split(" "),
+);
+const EN = new Set(
+  "the to and of for pay paid please my i i'm i'd i'll you your how much many what which when who is are was were have has had spent this that month week bill bills run payroll school cleaner electricity it it's next year's hi hello thanks thank can could would will with yes send show list due all everything from on in at by fee enrollment rules ignore".split(" "),
+);
+
+/** `undefined` when the text gives no lead either way ("ok", a number, a key). */
+export function detectLanguage(text: string): ReplyLanguage | undefined {
+  // A Pix key or an address is not language: "chave@x.com" would count "com" as Portuguese.
+  const words = text.replace(/\S+@\S+|\S+:\/\/\S+/g, " ").toLowerCase().normalize("NFC").match(/[\p{L}']+/gu) ?? [];
+  let pt = 0;
+  let en = 0;
+  for (const word of words) {
+    if (PT.has(word)) pt += 1;
+    if (EN.has(word)) en += 1;
+  }
+  // Diacritics are Portuguese's and never English's.
+  if (/[ãõçâêôáéíóúà]/i.test(text)) pt += 2;
+  if (pt > en) return "pt-BR";
+  if (en > pt) return "en";
+  return undefined;
+}
+
+/** Appended to the system prompt for every step of a turn whose language is known. */
+export function replyLanguageDirective(language: ReplyLanguage): string {
+  const name = language === "en" ? "English" : "Brazilian Portuguese";
+  return [
+    "## Reply language for this turn",
+    "",
+    `The person wrote their last message in ${name}. Write your reply in ${name}.`,
+    "Tool results are data, not the person: their payee names, descriptions and statuses are in Portuguese and do not change the language of your reply.",
+  ].join("\n");
+}

package/templates/bills-agent/packages/agent-core/src/locale.ts

@@ -0,0 +1,88 @@
+/**
+ * The language of the strings the CODE prints: the approval question, the
+ * batch gesture, the execution lines, the consent summary, the WhatsApp
+ * templates and the refusal details a kit writes. No model writes these.
+ *
+ * It is not the reply language (`language.ts`). That one is read from each
+ * turn the person types and only tells the model how to answer. The locale is
+ * fixed for a run and for a conversation, because the question that proposes
+ * a payment and the question that approves it must not change language
+ * between the two.
+ *
+ * Resolution: `--locale` on the command, else `locale:` in `agent.yaml`, else
+ * `pt-BR`. A conversation a later command comes back to keeps the locale its
+ * bundle recorded.
+ */
+import { z } from "zod";
+
+export const LOCALES = ["pt-BR", "en"] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = "pt-BR";
+export const LocaleSchema = z.enum(LOCALES);
+
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === "string" && (LOCALES as readonly string[]).includes(value);
+}
+
+/** A `--locale` value, or the error the command prints next to its usage. */
+export function parseLocale(value: string): Locale {
+  if (!isLocale(value)) throw new Error(`--locale must be ${LOCALES.join(" or ")}`);
+  return value;
+}
+
+export function resolveLocale(flag: Locale | undefined, manifest: { locale?: Locale | undefined }): Locale {
+  return flag ?? manifest.locale ?? DEFAULT_LOCALE;
+}
+
+/**
+ * The language code Meta approves a template in. Meta approves a template per
+ * (name, language) pair, so an English conversation sends the `en_US` copy of
+ * a template and never the `pt_BR` one.
+ */
+export const WHATSAPP_LANGUAGE: { readonly [L in Locale]: string } = { "pt-BR": "pt_BR", en: "en_US" };
+
+/** One entry per locale. A table missing a locale does not type-check; a key missing from one entry fails `npm run check`. */
+export type LocaleTable<T> = { readonly [L in Locale]: T };
+
+/**
+ * What differs between the entries of a string table: a key one locale has and
+ * another lacks, a string where the other has a function, or a function that
+ * takes a different number of arguments. Empty means every key exists in every
+ * locale with the same shape. The check reads this at runtime because a kit is
+ * TypeScript that `npm run check` does not compile.
+ */
+export function tableGaps(name: string, table: Partial<Record<Locale, object>>): string[] {
+  const gaps: string[] = [];
+  const entry = (l: Locale) => table[l] as Record<string, unknown> | undefined;
+  for (const locale of LOCALES) if (!entry(locale)) gaps.push(`${name} has no ${locale} entry`);
+  const keys = new Set(LOCALES.flatMap((l) => Object.keys(entry(l) ?? {})));
+  for (const key of [...keys].sort()) {
+    const shapes = LOCALES.map((l) => {
+      const value = entry(l)?.[key];
+      if (value === undefined) return "missing";
+      if (typeof value === "function") return `function/${value.length}`;
+      return typeof value === "string" && value.length > 0 ? "string" : `empty ${typeof value}`;
+    });
+    for (const [i, shape] of shapes.entries()) {
+      if (shape === "missing" || shape.startsWith("empty")) gaps.push(`${name}.${key} is ${shape} in ${LOCALES[i]}`);
+    }
+    if (new Set(shapes.filter((s) => s !== "missing")).size > 1) gaps.push(`${name}.${key} differs in shape across locales: ${LOCALES.map((l, i) => `${l} ${shapes[i]}`).join(", ")}`);
+  }
+  return gaps;
+}
+
+/** `185000` -> `R$ 1.850,00` in pt-BR, `R$1,850.00` in English: the two forms the prompts give the model since #62. */
+export function formatBRL(minor: number, locale: Locale): string {
+  const sign = minor < 0 ? "-" : "";
+  const abs = Math.abs(minor);
+  const cents = String(abs % 100).padStart(2, "0");
+  if (locale === "en") return `${sign}R$${Math.floor(abs / 100).toLocaleString("en-US")}.${cents}`;
+  return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${cents}`;
+}
+
+/** `2026-09-30` -> `30/09/2026` in pt-BR; English keeps the ISO date, which reads the same on either side of the Atlantic. */
+export function formatDay(iso: string, locale: Locale): string {
+  if (locale === "en") return iso;
+  const [y, m, d] = iso.split("-");
+  return `${d}/${m}/${y}`;
+}

package/templates/bills-agent/packages/agent-core/src/manifest.ts

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
+import { LocaleSchema } from "./locale.js";
 
 const PINNED_PACKAGE = /^@codespar\/(mcp|cli)@\d+\.\d+\.\d+$/;
 const HOURS_WINDOW = /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/;
@@ -34,12 +35,14 @@ export const ManifestSchema = z
     default_approval: z.enum(["human", "mandate"]),
     escalate_above: EscalateAboveSchema.optional(),
     mcp: z.string().regex(PINNED_PACKAGE, "mcp must pin an exact version, e.g. @codespar/mcp@0.5.8"),
-    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.14.0"),
+    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.18.1"),
     tools: z.string(),
     guardrails: z.string(),
     mandate_schema: z.string(),
     events: z.array(z.string().regex(/^commerce\.[a-z_.]+$/)),
     channels: z.array(z.enum(["terminal", "whatsapp"])).nonempty(),
+    /** The language of the strings the code prints (not of the model's replies). Optional: absent is `pt-BR`, which is what every agent printed before the field existed. */
+    locale: LocaleSchema.optional(),
     maturity: z.record(z.string(), MaturitySchema),
     scenarios: z.string(),
     evals: z.string(),

package/templates/bills-agent/packages/agent-core/src/rail.ts

@@ -75,7 +75,7 @@ export interface RailPayment {
    * its shape and never its content. A charge rail ignores it.
    */
   approval?: SpendApproval;
-  /** Section 4.5: carried on every call. The API has no wire field for it yet; see OPEN_QUESTIONS. */
+  /** Section 4.5: carried on every call, on the wire as `PaymentActor` (`wireActorOf`) since @codespar/sdk 0.16.10; see OPEN_QUESTIONS §2. */
   actor: Actor;
 }
 
@@ -167,9 +167,37 @@ export interface RailReceipt {
   receipt_sig_kid: string | null;
   /** Section 4.5: the kit stamps the actor onto the local copy of every receipt. */
   actor: Actor;
+  /**
+   * The actor the API RECORDED for the spend and read back (`PaymentActor`,
+   * @codespar/sdk 0.16.10): `null` when it recorded none — an API that did not
+   * take the field, or a spend that sent none. Absent when the rail cannot
+   * say: a charge, which records no actor.
+   */
+  sealed_actor?: WireActor | null;
   raw: unknown;
 }
 
+/**
+ * Who triggered a spend, in the API's own shape (`PaymentActor`,
+ * @codespar/sdk 0.16.10): the agent by its identifier and the consumer it acts
+ * for, or the person by id and the channel they acted from. The kit's `Actor`
+ * names the agent under `agent`; the wire names it under `id`, and that is the
+ * only difference.
+ */
+export type WireActor = { type: "agent"; id: string; on_behalf_of: string } | { type: "human"; id: string; channel?: string };
+
+export function wireActorOf(actor: Actor): WireActor {
+  return actor.type === "agent" ? { type: "agent", id: actor.agent, on_behalf_of: actor.on_behalf_of } : { type: "human", id: actor.id, channel: actor.channel };
+}
+
+/** The same actor, field for field. A human's channel counts: the same person on WhatsApp and on a dashboard are two events. */
+export function sameWireActor(a: WireActor | null, b: WireActor | null): boolean {
+  if (a === null || b === null) return a === b;
+  if (a.type === "agent" && b.type === "agent") return a.id === b.id && a.on_behalf_of === b.on_behalf_of;
+  if (a.type === "human" && b.type === "human") return a.id === b.id && (a.channel ?? null) === (b.channel ?? null);
+  return false;
+}
+
 /** What a reconcile learns: a recorded outcome, "still running", or nothing. Never a new payment. */
 export type RailLookup = RailOutcome | { status: "in_flight" } | undefined;