@codespar/cli 0.18.0 → 0.20.0

package/templates/checkout-agent/agents/checkout-agent/src/catalog.ts

@@ -12,7 +12,7 @@
  * stock come from this file, not from any warehouse.
  *
  * The customers' documents are valid CPFs (check digits computed): the
- * clearing house validates the payer of a cobranca com vencimento. `alias`
+ * clearing house validates the payer of a cobrança com vencimento. `alias`
  * matches the named entries of the sales policy (`mandate.example.json`); the
  * core resolves it to the document, which the model never sees.
  */
@@ -28,15 +28,15 @@ export interface CatalogItem {
   service_code: string;
 }
 
-export const MERCHANT = { name: "Estudio Tom Maior", city: "Sao Paulo" } as const;
+export const MERCHANT = { name: "Estúdio Tom Maior", city: "São Paulo" } as const;
 
 export const CATALOG: CatalogItem[] = [
-  { sku: "aula-avulsa", title: "Aula avulsa de violao (60 min)", category: "aula", price_minor: 10000, cost_minor: 4500, available: true, service_code: "8.02" },
-  { sku: "pacote-10-aulas", title: "Pacote de 10 aulas de violao", category: "aula", price_minor: 39000, cost_minor: 30000, available: true, service_code: "8.02" },
-  { sku: "avaliacao-inicial", title: "Avaliacao inicial de nivel", category: "avaliacao", price_minor: 8990, cost_minor: 3000, available: true, service_code: "8.02" },
+  { sku: "aula-avulsa", title: "Aula avulsa de violão (60 min)", category: "aula", price_minor: 10000, cost_minor: 4500, available: true, service_code: "8.02" },
+  { sku: "pacote-10-aulas", title: "Pacote de 10 aulas de violão", category: "aula", price_minor: 39000, cost_minor: 30000, available: true, service_code: "8.02" },
+  { sku: "avaliacao-inicial", title: "Avaliação inicial de nível", category: "avaliacao", price_minor: 8990, cost_minor: 3000, available: true, service_code: "8.02" },
   { sku: "consultoria-1h", title: "Consultoria de carreira musical (1 h)", category: "consultoria", price_minor: 20000, cost_minor: 9000, available: true, service_code: "17.01" },
   { sku: "ingresso-recital", title: "Ingresso para o recital de dezembro", category: "ingresso", price_minor: 4500, cost_minor: 1500, available: true, stock: 4, service_code: "12.07" },
-  { sku: "masterclass-producao", title: "Masterclass de producao musical", category: "masterclass", price_minor: 25000, cost_minor: 10000, available: false, service_code: "8.02" },
+  { sku: "masterclass-producao", title: "Masterclass de produção musical", category: "masterclass", price_minor: 25000, cost_minor: 10000, available: false, service_code: "8.02" },
 ];
 
 /** Where the service invoice (NFS-e) is delivered: the borrower's registration at the store. */
@@ -60,7 +60,7 @@ export interface Customer {
   address?: FiscalAddress;
 }
 
-const SAO_PAULO = { city: "Sao Paulo", city_code: "3550308", state: "SP" } as const;
+const SAO_PAULO = { city: "São Paulo", city_code: "3550308", state: "SP" } as const;
 
 export const CUSTOMERS: Customer[] = [
   { alias: "marina", name: "Marina Costa", document: "27548613008", email: "marina.costa@example.com", address: { street: "Rua Harmonia", number: "120", district: "Vila Madalena", postal_code: "05435000", ...SAO_PAULO } },

package/templates/checkout-agent/agents/checkout-agent/src/kit.ts

@@ -18,18 +18,21 @@ import { relative } from "node:path";
 import qrcode from "qrcode-terminal";
 import {
   CodeSparChargeRail,
-  NotATestKeyError,
   StubChargeRail,
   createCodeSparClient,
-  isTestKey,
+  assertTestKey,
   loadMandate,
-  paySandboxCharge,
+  payIfPayable,
+  formatBRL,
+  formatDay,
+  CORE_STRINGS,
   type Execution,
   type StubChargeRailOptions,
+  railErrorOf,
 } from "@codespar/agent-core";
 import { defineAgent, envName, type AgentKit, type Setup } from "@codespar/agent-runtime";
-import { formatBRL, formatDate } from "./catalog.js";
 import { checkOrder, loadEnvelope, priceCart, localDate } from "./pricing.js";
+import { STRINGS } from "./strings.js";
 import { claimOrder, CartBook, makeCartHandlers, type Cart } from "./modules/storefront-cart.js";
 import { followCart, makeChargeHandlers, orderProposal } from "./modules/bolepix-receivables.js";
 import { CodeSparInvoiceRail, followSale, InvoiceBook, resumeInvoices, StubInvoiceRail, type InvoiceDeps, type InvoiceRail, type StubIssuerBehaviour } from "./modules/nfse-invoice.js";
@@ -68,7 +71,7 @@ function invoiceDeps(s: Setup, say: (line: string) => void): InvoiceDeps {
 async function placeOrder(s: Setup, customer: string, lines: Array<{ sku: string; quantity: number }>): Promise<Execution> {
   const book = new CartBook(s.store);
   const now = s.engine.clock();
-  const priced = priceCart({ lines }, loadEnvelope(s.guardrails), localDate(now, s.guardrails.timezone));
+  const priced = priceCart({ lines }, loadEnvelope(s.guardrails), localDate(now, s.guardrails.timezone), s.locale);
   const runId = s.runId;
   const cartId = book.nextId(runId);
   const cart: Cart = { ...priced, cart_id: cartId, ref: `${runId}/${cartId}`, run_id: runId, version: 1, currency: "BRL", order_discount_pct: 0, updated_at: now.toISOString() };
@@ -87,17 +90,11 @@ const kit: AgentKit = {
   labels: {
     defaultUser: "usr_atendente",
     evalUser: "usr_atendente",
-    mandateWord: "politica",
-    receiptWord: "pedido",
-    intro: 'Voce e o cliente. Diga o que quer ("oi, sou a Marina, quero o pacote de dez aulas e uma avaliacao inicial"). Ctrl+D ou "sair" encerra.',
-    prompt: "cliente> ",
-    approveQuestion: "  [atendente] Confirmar este pedido? [s/N] ",
-    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a emissao)",
     missingReceiptKind: "record_missing_locally",
     missingReceiptDetail: (receiptId, runId) => `paid charge ${receiptId} is not in runs/${runId}/receipts`,
     stillExecuting: (e) => `${e.id}: still executing (${e.reason}) — ${e.detail}; nothing was re-issued; \`npm run poll\` keeps looking`,
-    waitingForPayer: (round) => `  aguardando o pagamento... (${round} consultas)`,
   },
+  strings: STRINGS,
 
   usage: () => `checkout-agent
   npm start                                                        interactive terminal (you are the customer; the attendant answers the approval question)
@@ -109,12 +106,13 @@ const kit: AgentKit = {
   npm run poll -- --channel whatsapp --conversation <name>         back to a conversation whose payment landed after the run ended
 options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>
          --wait <seconds>  --simulate-payer  --payer pays|expires|never (stub only)  --json
-         --now <ISO 8601>  pin the run to that instant (service hours, the due date, timestamps); env CODESPAR_AGENT_NOW is the same thing`,
+         --now <ISO 8601>  pin the run to that instant (service hours, the due date, timestamps); env CODESPAR_AGENT_NOW is the same thing
+         --locale pt-BR|en  the language of what the code prints, WhatsApp templates included (the model answers in the language the customer types either way)`,
 
   buildRail: (ctx) => {
     const mandate = ctx.mandate ?? loadMandate(ctx.manifest.resolvePath(ctx.manifest.manifest.mandate_schema));
     if (ctx.kind === "api") {
-      if (!isTestKey(ctx.env["CODESPAR_API_KEY"])) throw new NotATestKeyError();
+      assertTestKey(ctx.env["CODESPAR_API_KEY"]);
       const client = createCodeSparClient({ apiKey: ctx.env["CODESPAR_API_KEY"], baseUrl: ctx.env["CODESPAR_API_URL"], projectId: ctx.env["CODESPAR_PROJECT_ID"] });
       return {
         rail: new CodeSparChargeRail(client),
@@ -124,8 +122,8 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
         payer: {
           kind: "api" as const,
           async pay(chargeId: string) {
-            const result = await paySandboxCharge(client, chargeId);
-            if (!result.ok) return { ok: false as const, detail: `${result.failure.code}: ${result.failure.message}` };
+            const result = await payIfPayable(client, chargeId);
+            if (!result.ok) return { ok: false as const, detail: "refused" in result ? `${result.refused.code}: ${result.refused.message}` : `${result.failure.code}: ${result.failure.message}` };
             const s = result.state;
             return { ok: true as const, detail: `sandbox payer: ${s.charge_id} ${s.status} (${s.payment}, ${s.paid_minor} of ${s.quoted_minor}), simulated=${s.simulated}, settled_against=${s.settled_against}, money_moved=${s.money_moved}${s.idempotent_replay ? ", replay" : ""}` };
           },
@@ -161,37 +159,40 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
     const envelope = loadEnvelope(setup.guardrails);
     const book = new CartBook(setup.store);
     // On a channel that binds a conversation, the customer is the one it is bound to: read at call time, because the channel binds after setup.
-    const orderDeps = { book, runId: setup.runId, timezone: setup.guardrails.timezone, clock: setup.engine.clock, boundCustomer: () => setup.conversation?.subject };
+    const orderDeps = { book, runId: setup.runId, timezone: setup.guardrails.timezone, clock: setup.engine.clock, boundCustomer: () => setup.conversation?.subject, locale: () => setup.locale };
     return {
       ...makeCartHandlers({ ...orderDeps, envelope, onReplaced: (cart, engine) => void followCart(cart, engine, orderDeps) }),
       ...makeChargeHandlers(orderDeps),
     };
   },
 
-  policyExtension: ({ guardrails, store }) => {
+  policyExtension: ({ guardrails, store, locale }) => {
     const envelope = loadEnvelope(guardrails);
     const book = new CartBook(store);
-    return (execution, ctx) => checkOrder(execution, execution.composition ? book.get(execution.composition.ref) : undefined, envelope, ctx.now, ctx.guardrails.timezone);
+    return (execution, ctx) => checkOrder(execution, execution.composition ? book.get(execution.composition.ref) : undefined, envelope, ctx.now, ctx.guardrails.timezone, locale());
   },
 
   describeExecution: (execution, setup) => {
+    const text = setup.coreStrings;
+    const words = STRINGS[setup.locale];
+    const money = (minor: number) => formatBRL(minor, setup.locale);
     const lines: string[] = [];
     const cart = cartOf(setup, execution);
-    lines.push(`  pedido ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
-    lines.push(`    cliente ${execution.items[0]?.beneficiary ?? "?"}${cart ? `, carrinho ${cart.cart_id} v${cart.version}` : ""}`);
-    for (const l of cart?.line_items ?? []) lines.push(`    - ${l.quantity}x ${l.name}: ${formatBRL(l.totals.find((t) => t.type === "total")!.amount)}${l.discount_pct ? ` (desconto ${l.discount_pct}%)` : ""}`);
-    for (const d of cart?.order_discounts ?? []) lines.push(`    - ${d.kind === "coupon" ? `cupom ${d.ref.replace("coupon:", "")}` : "desconto no pedido"}: ${formatBRL(-d.amount)}`);
-    lines.push(`    total (calculado pelo core): ${formatBRL(execution.total)}${execution.items[0]?.due_date ? `, vence ${formatDate(execution.items[0].due_date)}` : ""}`);
-    if (execution.composition) lines.push(`    cart_hash ${execution.composition.composition_hash.slice(0, 19)}… (${execution.composition.line_count} linha(s))`);
-    if (execution.escalation) lines.push(`    escalado por: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
-    if (execution.blocking_reasons.length) lines.push(`    bloqueado: ${execution.blocking_reasons.join(", ")} — a politica nao autoriza; nao ha o que aprovar`);
+    lines.push(`  ${words.order} ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
+    lines.push(`    ${words.customerLine(execution.items[0]?.beneficiary ?? "?", cart ? `${cart.cart_id} v${cart.version}` : undefined)}`);
+    for (const l of cart?.line_items ?? []) lines.push(`    - ${l.quantity}x ${l.name}: ${money(l.totals.find((t) => t.type === "total")!.amount)}${l.discount_pct ? words.lineDiscount(l.discount_pct) : ""}`);
+    for (const d of cart?.order_discounts ?? []) lines.push(`    - ${d.kind === "coupon" ? words.coupon(d.ref.replace("coupon:", "")) : words.orderDiscount}: ${money(-d.amount)}`);
+    lines.push(`    ${text.totalByCore}: ${money(execution.total)}${execution.items[0]?.due_date ? text.dueOn(formatDay(execution.items[0].due_date, setup.locale)) : ""}`);
+    if (execution.composition) lines.push(`    cart_hash ${execution.composition.composition_hash.slice(0, 19)}… (${words.cartLines(execution.composition.line_count)})`);
+    if (execution.escalation) lines.push(`    ${text.escalatedBy}: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
+    if (execution.blocking_reasons.length) lines.push(`    ${text.blocked(execution.blocking_reasons.join(", "), words.notAuthorized)}`);
     if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
     for (const outcome of execution.outcomes) {
-      if (outcome.transaction_id) lines.push(`    cobranca: ${outcome.transaction_id} — ${outcome.status}${outcome.code ? ` (${outcome.code})` : ""}`);
-      if (outcome.receipt_id) lines.push(`    pedido pago: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+      if (outcome.transaction_id) lines.push(`    ${words.charge}: ${outcome.transaction_id} — ${outcome.status}${outcome.code ? ` (${outcome.code})` : ""}`);
+      if (outcome.receipt_id) lines.push(`    ${words.paidOrder}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
     }
     const invoice = new InvoiceBook(setup.store).of(execution.id);
-    if (invoice) lines.push(`    NFS-e ${invoice.id}: ${invoice.state}${invoice.reason ? ` (${invoice.reason}, ${invoice.code})` : ""}${invoice.document ? ` — documento ${invoice.document.id}` : ""}`);
+    if (invoice) lines.push(`    NFS-e ${invoice.id}: ${invoice.state}${invoice.reason ? ` (${invoice.reason}, ${invoice.code})` : ""}${invoice.document ? words.invoiceDocument(invoice.document.id) : ""}`);
     return lines;
   },
 
@@ -214,6 +215,7 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
           id: e.id,
           state: e.state,
           reason: e.reason ?? null,
+          rail_error: railErrorOf(e),
           escalation: e.escalation ?? null,
           cart_id: cart?.cart_id ?? null,
           cart_hash: e.composition?.composition_hash ?? null,
@@ -234,18 +236,19 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
   },
 
   /** What the customer reads when the charge is payable: the QR as an image, the copy-and-paste under it, the bank line if any. */
-  presentInstrument: (execution, _instalment, chargeId, instrument, tell) => {
+  presentInstrument: (execution, _instalment, chargeId, instrument, tell, locale) => {
+    const text = CORE_STRINGS[locale];
     tell("");
-    tell(`Pedido de ${formatBRL(execution.total)}${instrument.due_date ? `, vence ${formatDate(instrument.due_date)}` : ""} — cobranca ${chargeId}`);
+    tell(`${STRINGS[locale].orderOf(formatBRL(execution.total, locale))}${instrument.due_date ? text.dueOn(formatDay(instrument.due_date, locale)) : ""}${text.chargeRef(chargeId)}`);
     if (instrument.pix_copy_paste) {
       qrcode.generate(instrument.pix_copy_paste, { small: true }, (qr: string) => {
         for (const line of qr.split("\n")) tell(line);
       });
-      tell("Pix copia e cola:");
+      tell(text.pixCopyPaste);
       tell(instrument.pix_copy_paste);
     }
     if (instrument.boleto_bank_line) {
-      tell("Ou pelo boleto, linha digitavel:");
+      tell(text.boletoLine);
       tell(instrument.boleto_bank_line);
     }
     tell("");
@@ -255,14 +258,15 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
   announceOutcome: (execution, setup, tell) => {
     if (!["settled", "failed", "denied", "expired"].includes(execution.state)) return false;
     if (!setup.engine.markTold(execution.id, execution.state)) return false;
+    const words = STRINGS[setup.locale];
     let text: string;
-    if (execution.state === "settled") text = `Recebemos, pedido confirmado! Obrigado. (${execution.outcomes.map((o) => o.transaction_id).filter(Boolean).join(", ")})`;
-    else if (execution.reason === "charge_expired") text = "A cobranca venceu sem pagamento. Se quiser, emito uma nova para o mesmo pedido.";
-    else if (execution.reason === "charge_cancelled") text = "A cobranca foi cancelada. Nada foi pago.";
-    else if (execution.reason === "charge_reference_ambiguous") text = "A cobranca deste pedido ja foi emitida e estamos conferindo a situacao dela. Nao pague de novo; te aviso assim que estiver conferida.";
-    else if (execution.state === "failed") text = `Nao consegui emitir a cobranca (${execution.reason ?? "falha no trilho"}). Nada foi cobrado.`;
-    else if (execution.state === "denied") text = `Nao consigo fechar o pedido nesses termos (${execution.reason ?? "recusado"}).`;
-    else text = `O pedido expirou sem confirmacao (${execution.reason ?? execution.state}).`;
+    if (execution.state === "settled") text = words.toldSettled(execution.outcomes.map((o) => o.transaction_id).filter(Boolean).join(", "));
+    else if (execution.reason === "charge_expired") text = words.toldExpired;
+    else if (execution.reason === "charge_cancelled") text = words.toldCancelled;
+    else if (execution.reason === "charge_reference_ambiguous") text = words.toldAmbiguous;
+    else if (execution.state === "failed") text = words.toldFailed(execution.reason);
+    else if (execution.state === "denied") text = words.toldDenied(execution.reason);
+    else text = words.toldUndecided(execution.reason ?? execution.state);
     tell(text);
     setup.engine.note("message.debtor", execution.id, { state: execution.state, reason: execution.reason ?? null, text });
     return true;
@@ -284,8 +288,8 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
    * is answered inside the turn that produced it, so it has no template, and
    * the poll reports it rather than sending approximate copy.
    */
-  outcomeTemplate: (execution) => {
-    const total = formatBRL(execution.total);
+  outcomeTemplate: (execution, locale) => {
+    const total = formatBRL(execution.total, locale);
     if (execution.state === "settled") return { template: "pedido_confirmado", variables: [total] };
     if (execution.reason === "charge_expired") return { template: "pedido_cobranca_vencida", variables: [total] };
     if (execution.reason === "charge_cancelled") return { template: "pedido_cobranca_cancelada", variables: [total] };

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

@@ -2,7 +2,7 @@
  * Module `bolepix-receivables`, the sales version: the `codespar_charge`
  * handler. A copy of the collections-agent's module in its bones (agents do
  * not import each other's modules, OPEN_QUESTIONS §39f) and different in what
- * it charges: an ORDER, one cobranca com vencimento whose amount is the
+ * it charges: an ORDER, one cobrança com vencimento whose amount is the
  * cart's total as the code priced it, due today (checkout decision 1).
  *
  * Three actions, because ordering and issuing are two moments of a sale:
@@ -22,10 +22,11 @@
  * No input carries an amount. `total_minor` is recorded and, with
  * `model_total_mismatch: refuse`, refuses a total the model got wrong.
  */
-import type { Execution, ExecutionEngine, Proposal, ToolHandler } from "@codespar/agent-core";
+import type { Execution, ExecutionEngine, Locale, Proposal, ToolHandler } from "@codespar/agent-core";
 import { MERCHANT, formatBRL, formatDate } from "../catalog.js";
 import { localDate } from "../pricing.js";
 import { claimOrder, currentCart, orderOf, resolveCart, type Cart, type CartBook } from "./storefront-cart.js";
+import { STRINGS } from "../strings.js";
 
 interface ChargeInput {
   action?: unknown;
@@ -43,6 +44,8 @@ export interface OrderDeps {
   clock: () => Date;
   /** The customer a channel's conversation is bound to, when one is: an order in this conversation is theirs. */
   boundCustomer?: () => string | undefined;
+  /** The run's locale, read at call time: an order's status message is worded in it. Default pt-BR. */
+  locale?: () => Locale;
 }
 
 const OPEN = new Set(["awaiting_approval", "approved"]);
@@ -74,6 +77,7 @@ export function followCart(cart: Cart, engine: ExecutionEngine, deps: Pick<Order
 }
 
 export function makeChargeHandlers(deps: OrderDeps): Record<string, ToolHandler> {
+  const text = () => STRINGS[deps.locale?.() ?? "pt-BR"];
   const findOrder = (engine: ExecutionEngine, input: ChargeInput): { order: Execution | undefined; cart: Cart | undefined } => {
     if (typeof input.execution_id === "string" && input.execution_id) {
       const order = engine.get(input.execution_id);
@@ -91,14 +95,14 @@ export function makeChargeHandlers(deps: OrderDeps): Record<string, ToolHandler>
 
     if (action === "status") {
       const { order, cart } = findOrder(ctx.engine, input);
-      if (!order) return { found: false, message: cart ? `o carrinho ${cart.cart_id} ainda nao virou pedido` : "nenhum pedido nesta conversa" };
+      if (!order) return { found: false, message: cart ? text().noOrderForCart(cart.cart_id) : text().noOrder };
       return { found: true, ...describe(order, cart) };
     }
 
     if (action === "issue") {
       const { order, cart } = findOrder(ctx.engine, input);
       if (!order) throw new Error("codespar_charge: no order to issue; create the order from the cart first (action=create)");
-      if (order.state !== "approved") return { ...describe(order, cart), message: messageFor(order) };
+      if (order.state !== "approved") return { ...describe(order, cart), message: messageFor(order, text()) };
       // The cart may have moved since the order was approved; the order follows it, and the last gate compares.
       if (cart) followCart(cart, ctx.engine, deps);
       const executed = await ctx.engine.execute(order.id);
@@ -123,30 +127,34 @@ export function makeChargeHandlers(deps: OrderDeps): Record<string, ToolHandler>
     if (existing && (OPEN.has(existing.state) || existing.state === "executing" || existing.state === "settled")) {
       if (OPEN.has(existing.state)) followCart(cart, ctx.engine, deps);
       const current = ctx.engine.get(existing.id)!;
-      return { ...describe(current, cart), message: `este carrinho ja e o pedido ${current.id}; nada novo foi criado` };
+      return { ...describe(current, cart), message: text().alreadyOrdered(current.id) };
     }
 
     const claimed = typeof input.total_minor === "number" ? input.total_minor : undefined;
     const draft = await ctx.engine.draft(orderProposal(cart, customer, deps, claimed));
-    if (!draft.ok) return { status: "refused", reason: draft.reason, message: draft.message, issued: false, paid: false };
+    if (!draft.ok) {
+      // Refused before a draft: no execution will ever say so, and the run's count is taken from this.
+      ctx.onNotRun?.({ ref: cart.cart_id, why: "refused", detail: draft.reason });
+      return { status: "refused", reason: draft.reason, message: draft.message, issued: false, paid: false };
+    }
     claimOrder(ctx.engine, cart, draft.execution.id);
     const decided = await ctx.onExecution(draft.execution);
-    return { ...describe(decided, cart), message: messageFor(decided) };
+    return { ...describe(decided, cart), message: messageFor(decided, text()) };
   };
 
   return { codespar_charge: codesparCharge };
 }
 
-function messageFor(order: Execution): string {
+function messageFor(order: Execution, text: (typeof STRINGS)[Locale]): string {
   switch (order.state) {
     case "approved":
-      return "pedido confirmado; a cobranca sai quando o cliente pedir (action=issue)";
+      return text.orderApproved;
     case "awaiting_approval":
-      return order.reason === "items_hash_mismatch" ? "o carrinho mudou depois da confirmacao; o pedido voltou para o atendente" : "aguardando o atendente confirmar o pedido";
+      return order.reason === "items_hash_mismatch" ? text.orderCartChanged : text.orderAwaitingAttendant;
     case "executing":
-      return order.reason === "awaiting_settlement" ? "cobranca emitida; aguardando o pagamento" : "desfecho da emissao desconhecido; nada sera reemitido";
+      return order.reason === "awaiting_settlement" ? text.orderIssued : text.orderUncertain;
     case "settled":
-      return "pago";
+      return text.orderPaid;
     default:
       return `${order.state}${order.reason ? ` (${order.reason})` : ""}`;
   }

package/templates/checkout-agent/agents/checkout-agent/src/modules/nfse-invoice.ts

@@ -178,7 +178,7 @@ export class StubInvoiceRail implements InvoiceRail {
       return { status: "unsent", code: "no_eligible_providers", message: "stub: routing found no issuer this time; nothing was sent" };
     }
     if (behaviour === "refuses" || (behaviour === undefined && !request.recipient.address)) {
-      return { status: "refused", code: "E0101", message: "stub issuer: tomador sem endereco; a NFS-e exige o endereco do tomador" };
+      return { status: "refused", code: "E0101", message: "stub issuer: tomador sem endereço; a NFS-e exige o endereço do tomador" };
     }
     // What the issuer did is recorded before the answer is lost, as a real one would have.
     const documentId = `nfse_stub_${key.slice(-16)}`;
@@ -248,7 +248,7 @@ export function nfseRequest(sale: Execution, cart: Cart, customer: Customer): Nf
       description: `${MERCHANT.name} - pedido ${cart.cart_id}: ${cart.line_items.map((l) => `${l.quantity}x ${l.name}`).join("; ")}`,
       // What was PAID, discounts included; the transform would otherwise sum list prices.
       servicesAmount: sale.total / 100,
-      additionalInformation: `cobranca ${chargeId}, ${formatBRL(sale.total)}`,
+      additionalInformation: `cobrança ${chargeId}, ${formatBRL(sale.total)}`,
     },
   };
 }
@@ -342,8 +342,8 @@ export async function dispatchInvoice(record: InvoiceRecord, deps: InvoiceDeps):
 function notify(record: InvoiceRecord, deps: InvoiceDeps): InvoiceRecord {
   const text =
     record.reason === "invoice_uncertain"
-      ? `NFS-e do pedido ${record.sale_execution_id} (cobranca ${record.charge_id}) com resultado INCERTO (${record.code}): pode ter sido emitida. Nao reemita; confira no emissor. A venda continua paga.`
-      : `NFS-e do pedido ${record.sale_execution_id} (cobranca ${record.charge_id}) falhou (${record.reason}, ${record.code}): ${record.detail}. A venda continua paga.`;
+      ? `NFS-e do pedido ${record.sale_execution_id} (cobrança ${record.charge_id}) com resultado INCERTO (${record.code}): pode ter sido emitida. Não reemita; confira no emissor. A venda continua paga.`
+      : `NFS-e do pedido ${record.sale_execution_id} (cobrança ${record.charge_id}) falhou (${record.reason}, ${record.code}): ${record.detail}. A venda continua paga.`;
   deps.say(`  [atendente] ${text}`);
   deps.engine.note("message.attendant", record.sale_execution_id, { invoice_id: record.id, state: record.state, reason: record.reason ?? null, code: record.code ?? null, text });
   return record;

package/templates/checkout-agent/agents/checkout-agent/src/modules/storefront-cart.ts

@@ -18,9 +18,10 @@
  * execution carries (`<run_id>/cart-1`) is unique across runs, so an order
  * approved from another process (`npm run approve`) finds its cart.
  */
-import type { ExecutionEngine, StateStore, ToolHandler } from "@codespar/agent-core";
+import type { ExecutionEngine, Locale, StateStore, ToolHandler } from "@codespar/agent-core";
 import { CATALOG, MERCHANT, formatBRL } from "../catalog.js";
 import { localDate, priceCart, type Envelope, type PricedCart, type ValidationIssue } from "../pricing.js";
+import { STRINGS } from "../strings.js";
 
 export interface Cart extends PricedCart {
   cart_id: string;
@@ -137,6 +138,8 @@ export interface CartDeps {
   runId: string;
   timezone: string;
   clock: () => Date;
+  /** The run's locale, read at call time: the cart's issues and totals are worded in it. Default pt-BR. */
+  locale?: () => Locale;
   /** Called after a replacement, with the cart as it is now: an open order follows it (`bolepix-receivables`). */
   onReplaced(cart: Cart, engine: ExecutionEngine): void;
 }
@@ -169,16 +172,16 @@ export function makeCartHandlers(deps: CartDeps): Record<string, ToolHandler> {
     })),
     policy: {
       service_hours: deps.envelope.service_hours,
-      payment: "bolepix (cobranca com vencimento): paga por Pix ou por boleto, vence hoje",
-      discounts: "so dentro da politica da loja, aplicada pelo codigo; o que estiver fora e recusado. Cupom: so os da tabela da loja, informados pelo cliente.",
-      prices: "sempre os do catalogo; nenhuma ferramenta aceita preco",
+      payment: "bolepix (cobrança com vencimento): paga por Pix ou por boleto, vence hoje",
+      discounts: "só dentro da política da loja, aplicada pelo código; o que estiver fora é recusado. Cupom: só os da tabela da loja, informados pelo cliente.",
+      prices: "sempre os do catálogo; nenhuma ferramenta aceita preço",
     },
   });
 
   const cartView: ToolHandler = async (raw, ctx) => {
     const input = raw as { cart_id?: unknown };
     const cart = resolveCart(ctx.engine, deps, input.cart_id);
-    if (!cart) return { cart: null, message: "nenhum carrinho aberto nesta conversa; cart_update abre um" };
+    if (!cart) return { cart: null, message: STRINGS[deps.locale?.() ?? "pt-BR"].noCart };
     return viewOf(ctx.engine, cart);
   };
 
@@ -191,7 +194,7 @@ export function makeCartHandlers(deps: CartDeps): Record<string, ToolHandler> {
     } else target = currentCart(ctx.engine, deps);
 
     const now = deps.clock();
-    const priced = priceCart({ lines: input.lines, coupon: input.coupon, order_discount_pct: input.order_discount_pct }, deps.envelope, localDate(now, deps.timezone));
+    const priced = priceCart({ lines: input.lines, coupon: input.coupon, order_discount_pct: input.order_discount_pct }, deps.envelope, localDate(now, deps.timezone), deps.locale?.());
     const cartId = target?.cart_id ?? deps.book.nextId(deps.runId);
     const cart: Cart = {
       ...priced,

package/templates/checkout-agent/agents/checkout-agent/src/pricing.ts

@@ -13,8 +13,9 @@
  * `guardrails.json` under `envelope`, and every rule of it can only refuse.
  */
 import { z } from "zod";
-import { compositionHash, isOutsideHours, localClock, type CompositionLine, type Execution, type ExecutionReason, type Guardrails } from "@codespar/agent-core";
-import { catalogItem, formatBRL } from "./catalog.js";
+import { compositionHash, formatBRL, isOutsideHours, localClock, type CompositionLine, type Execution, type ExecutionReason, type Guardrails, type Locale } from "@codespar/agent-core";
+import { catalogItem } from "./catalog.js";
+import { STRINGS } from "./strings.js";
 
 const HOURS = /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/;
 
@@ -131,7 +132,8 @@ export interface CartInput {
  * priced from the catalog. A coupon that does not exist, or does not apply,
  * is named and not applied, and nothing "equivalent" is applied in its place.
  */
-export function priceCart(input: CartInput, envelope: Envelope, today: string): PricedCart {
+export function priceCart(input: CartInput, envelope: Envelope, today: string, locale: Locale = "pt-BR"): PricedCart {
+  const text = STRINGS[locale];
   const issues: ValidationIssue[] = [];
   const lines: PricedLine[] = [];
   const raw = Array.isArray(input.lines) ? input.lines : [];
@@ -143,30 +145,30 @@ export function priceCart(input: CartInput, envelope: Envelope, today: string):
     const line = (entry ?? {}) as Record<string, unknown>;
     const priced = PRICE_FIELDS.find((f) => f in line);
     if (priced) {
-      issues.push({ code: "price_not_caller_input", field: `${field}.${priced}`, message: "o preco vem do catalogo da loja; a linha foi recusada inteira" });
+      issues.push({ code: "price_not_caller_input", field: `${field}.${priced}`, message: text.issuePriceNotInput });
       continue;
     }
     const sku = typeof line["sku"] === "string" ? line["sku"].trim().toLowerCase() : "";
     const item = sku ? catalogItem(sku) : undefined;
     if (!item) {
-      issues.push({ code: "sku_unknown", field: `${field}.sku`, message: `nao temos ${sku || "esse item"} no catalogo` });
+      issues.push({ code: "sku_unknown", field: `${field}.sku`, message: text.issueSkuUnknown(sku) });
       continue;
     }
     if (!item.available) {
-      issues.push({ code: "item_unavailable", field: `${field}.sku`, message: `${item.title} esta indisponivel` });
+      issues.push({ code: "item_unavailable", field: `${field}.sku`, message: text.issueUnavailable(item.title) });
       continue;
     }
     const quantity = line["quantity"];
     if (typeof quantity !== "number" || !Number.isInteger(quantity) || quantity <= 0 || quantity > envelope.max_units_per_line) {
-      issues.push({ code: "quantity_invalid", field: `${field}.quantity`, message: `quantidade deve ser um inteiro de 1 a ${envelope.max_units_per_line}` });
+      issues.push({ code: "quantity_invalid", field: `${field}.quantity`, message: text.issueQuantityInvalid(envelope.max_units_per_line) });
       continue;
     }
     if (seen.has(item.sku)) {
-      issues.push({ code: "quantity_invalid", field: `${field}.sku`, message: `${item.sku} aparece mais de uma vez; uma linha por item, com a quantidade total` });
+      issues.push({ code: "quantity_invalid", field: `${field}.sku`, message: text.issueDuplicateSku(item.sku) });
       continue;
     }
     if (item.stock !== undefined && quantity > item.stock) {
-      issues.push({ code: "quantity_above_stock", field: `${field}.quantity`, message: `so ha ${item.stock} de ${item.title}` });
+      issues.push({ code: "quantity_above_stock", field: `${field}.quantity`, message: text.issueAboveStock(item.stock, item.title) });
       continue;
     }
     const discount = line["discount_pct"] ?? 0;
@@ -184,9 +186,9 @@ export function priceCart(input: CartInput, envelope: Envelope, today: string):
       discount_pct: discount,
       availability_status: item.stock !== undefined && item.stock - quantity <= 1 ? "low_stock" : "in_stock",
       totals: [
-        { type: "items_base_amount", display_text: "Valor", amount: base },
-        { type: "items_discount", display_text: "Desconto", amount: -off },
-        { type: "total", display_text: "Total da linha", amount: base - off },
+        { type: "items_base_amount", display_text: text.lineValue, amount: base },
+        { type: "items_discount", display_text: text.lineDiscountTotal, amount: -off },
+        { type: "total", display_text: text.lineTotal, amount: base - off },
       ],
     });
   }
@@ -198,9 +200,9 @@ export function priceCart(input: CartInput, envelope: Envelope, today: string):
     if (typeof input.coupon !== "string") throw new Error("coupon must be a string");
     const code = input.coupon.trim().toUpperCase();
     const found = envelope.coupons.find((c) => c.code === code);
-    if (!found) issues.push({ code: "coupon_unknown", field: "coupon", message: `o cupom ${code} nao existe nesta loja` });
-    else if (found.expires_at < today) issues.push({ code: "coupon_not_applicable", field: "coupon", message: `o cupom ${code} expirou` });
-    else if (subtotal < found.min_order_minor) issues.push({ code: "coupon_not_applicable", field: "coupon", message: `o cupom ${code} vale para pedidos a partir de ${formatBRL(found.min_order_minor)}` });
+    if (!found) issues.push({ code: "coupon_unknown", field: "coupon", message: text.issueCouponUnknown(code) });
+    else if (found.expires_at < today) issues.push({ code: "coupon_not_applicable", field: "coupon", message: text.issueCouponExpired(code) });
+    else if (subtotal < found.min_order_minor) issues.push({ code: "coupon_not_applicable", field: "coupon", message: text.issueCouponMinimum(code, formatBRL(found.min_order_minor, locale)) });
     else {
       coupon = code;
       orderDiscounts.push({ kind: "coupon", ref: `coupon:${code}`, pct: found.discount_pct, amount: Math.round((subtotal * found.discount_pct) / 100) });
@@ -224,11 +226,11 @@ export function priceCart(input: CartInput, envelope: Envelope, today: string):
     coupon,
     order_discounts: orderDiscounts,
     totals: [
-      { type: "items_base_amount", display_text: "Itens", amount: itemsBase },
-      { type: "items_discount", display_text: "Descontos nos itens", amount: subtotal - itemsBase },
-      { type: "subtotal", display_text: "Subtotal", amount: subtotal },
-      { type: "discount", display_text: "Desconto do pedido", amount: -orderOff },
-      { type: "total", display_text: "Total", amount: total },
+      { type: "items_base_amount", display_text: text.totalItems, amount: itemsBase },
+      { type: "items_discount", display_text: text.totalItemsDiscount, amount: subtotal - itemsBase },
+      { type: "subtotal", display_text: text.totalSubtotal, amount: subtotal },
+      { type: "discount", display_text: text.totalOrderDiscount, amount: -orderOff },
+      { type: "total", display_text: text.totalTotal, amount: total },
     ],
     total,
     validation_issues: issues,
@@ -248,46 +250,47 @@ export interface OrderVerdict {
  * envelope's numbers or a cost: the maximum discount and the margin floor are
  * negotiation information (checkout §5.6, exfiltration).
  */
-export function checkOrder(execution: Pick<Execution, "items" | "total" | "composition">, cart: PricedCart | undefined, envelope: Envelope, now: Date, timezone: string): OrderVerdict | undefined {
+export function checkOrder(execution: Pick<Execution, "items" | "total" | "composition">, cart: PricedCart | undefined, envelope: Envelope, now: Date, timezone: string, locale: Locale = "pt-BR"): OrderVerdict | undefined {
+  const text = STRINGS[locale];
   const [open, close] = envelope.service_hours.split("-") as [string, string];
   if (isOutsideHours(`${close}-${open}`, now, timezone)) {
-    return { reason: "outside_hours", detail: `fora do horario de atendimento (${envelope.service_hours} ${timezone}); agora sao ${localClock(now, timezone)}` };
+    return { reason: "outside_hours", detail: text.outsideServiceHours(envelope.service_hours, timezone, localClock(now, timezone)) };
   }
-  if (execution.items.length !== 1) return { reason: "outside_envelope", detail: "um pedido e uma cobranca: um item, cujo valor e o total do carrinho" };
-  if (!execution.composition) return { reason: "outside_envelope", detail: "um pedido nasce de um carrinho; esta execucao nao nomeia nenhum" };
-  if (!cart) return { reason: "outside_envelope", detail: `o carrinho ${execution.composition.ref} nao existe neste estado` };
-  if (cart.cart_hash !== execution.composition.composition_hash) return { reason: "outside_envelope", detail: "o pedido nao corresponde ao carrinho atual; o carrinho mudou depois" };
-  if (cart.line_items.length === 0) return { reason: "outside_envelope", detail: "carrinho vazio" };
-  if (cart.validation_issues.length > 0) return { reason: "outside_envelope", detail: `o carrinho tem pendencias (${cart.validation_issues.map((i) => i.code).join(", ")})` };
-  if (execution.total !== cart.total || execution.items[0]!.amount !== cart.total) return { reason: "outside_envelope", detail: `o pedido cobra ${execution.total} e o carrinho soma ${cart.total}` };
+  if (execution.items.length !== 1) return { reason: "outside_envelope", detail: text.gateOneItem };
+  if (!execution.composition) return { reason: "outside_envelope", detail: text.gateNoCart };
+  if (!cart) return { reason: "outside_envelope", detail: text.gateCartMissing(execution.composition.ref) };
+  if (cart.cart_hash !== execution.composition.composition_hash) return { reason: "outside_envelope", detail: text.gateCartChanged };
+  if (cart.line_items.length === 0) return { reason: "outside_envelope", detail: text.gateCartEmpty };
+  if (cart.validation_issues.length > 0) return { reason: "outside_envelope", detail: text.gateCartIssues(cart.validation_issues.map((i) => i.code).join(", ")) };
+  if (execution.total !== cart.total || execution.items[0]!.amount !== cart.total) return { reason: "outside_envelope", detail: text.gateTotalMismatch(execution.total, cart.total) };
 
   for (const line of cart.line_items) {
     const item = catalogItem(line.sku);
-    if (!item || !item.available) return { reason: "outside_envelope", detail: `${line.sku} nao esta a venda` };
-    if (line.unit_amount !== item.price_minor) return { reason: "outside_envelope", detail: `${line.sku} nao esta pelo preco de tabela` };
-    if (line.quantity > envelope.max_units_per_line || (item.stock !== undefined && line.quantity > item.stock)) return { reason: "outside_envelope", detail: `quantidade de ${line.sku} fora do permitido` };
-    if (line.discount_pct > envelope.max_discount_pct) return { reason: "outside_envelope", detail: `desconto em ${line.sku} acima do que a politica da loja permite` };
+    if (!item || !item.available) return { reason: "outside_envelope", detail: text.gateNotForSale(line.sku) };
+    if (line.unit_amount !== item.price_minor) return { reason: "outside_envelope", detail: text.gateNotListPrice(line.sku) };
+    if (line.quantity > envelope.max_units_per_line || (item.stock !== undefined && line.quantity > item.stock)) return { reason: "outside_envelope", detail: text.gateQuantity(line.sku) };
+    if (line.discount_pct > envelope.max_discount_pct) return { reason: "outside_envelope", detail: text.gateLineDiscount(line.sku) };
     const total = lineTotal(line);
-    if (marginBelow(total, item.cost_minor * line.quantity, envelope.min_margin_pct)) return { reason: "outside_envelope", detail: `${line.sku} ficaria abaixo do piso de margem da loja` };
+    if (marginBelow(total, item.cost_minor * line.quantity, envelope.min_margin_pct)) return { reason: "outside_envelope", detail: text.gateLineMargin(line.sku) };
   }
   const negotiated = cart.order_discounts.filter((d) => d.kind === "negotiated");
   const coupons = cart.order_discounts.filter((d) => d.kind === "coupon");
-  if (negotiated.some((d) => d.pct > envelope.max_order_discount_pct)) return { reason: "outside_envelope", detail: "desconto no pedido acima do que a politica da loja permite" };
-  if (negotiated.length > 0 && coupons.length > 0) return { reason: "outside_envelope", detail: "cupom e desconto negociado nao se somam" };
+  if (negotiated.some((d) => d.pct > envelope.max_order_discount_pct)) return { reason: "outside_envelope", detail: text.gateOrderDiscount };
+  if (negotiated.length > 0 && coupons.length > 0) return { reason: "outside_envelope", detail: text.gateCouponAndDiscount };
   const today = localDate(now, timezone);
   for (const c of coupons) {
     const code = c.ref.replace(/^coupon:/, "");
     const found = envelope.coupons.find((x) => x.code === code);
-    if (!found || found.expires_at < today || c.pct !== found.discount_pct) return { reason: "outside_envelope", detail: `o cupom ${code} nao vale para este pedido` };
+    if (!found || found.expires_at < today || c.pct !== found.discount_pct) return { reason: "outside_envelope", detail: text.gateCouponInvalid(code) };
   }
   const cost = cart.line_items.reduce((sum, l) => sum + (catalogItem(l.sku)?.cost_minor ?? 0) * l.quantity, 0);
-  if (marginBelow(cart.total, cost, envelope.min_margin_pct)) return { reason: "outside_envelope", detail: "o pedido ficaria abaixo do piso de margem da loja" };
-  if (cart.total > envelope.max_order_minor) return { reason: "outside_envelope", detail: `pedido de ${formatBRL(cart.total)} acima do ticket maximo da loja` };
+  if (marginBelow(cart.total, cost, envelope.min_margin_pct)) return { reason: "outside_envelope", detail: text.gateOrderMargin };
+  if (cart.total > envelope.max_order_minor) return { reason: "outside_envelope", detail: text.gateTicket(formatBRL(cart.total, locale)) };
 
   const due = execution.items[0]!.due_date;
-  if (!due) return { reason: "outside_envelope", detail: "a cobranca do pedido nao tem vencimento" };
+  if (!due) return { reason: "outside_envelope", detail: text.gateNoDueDate };
   const last = addDays(today, envelope.due_date_window_days);
-  if (due < today || due > last) return { reason: "outside_envelope", detail: `vencimento ${due} fora da janela da loja (de ${today} ate ${last})` };
+  if (due < today || due > last) return { reason: "outside_envelope", detail: text.gateDueOutsideWindow(due, today, last) };
   return undefined;
 }