@codespar/cli 0.18.1 → 0.20.0

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

@@ -0,0 +1,179 @@
+/**
+ * What this agent prints, per locale: the runner's words for it, the lines an
+ * order reads as, the one message per outcome the customer receives, and the
+ * words pricing and the order tools write (the cart's issues, the gate's
+ * refusal details, an order's status). Every key exists in both entries (`npm
+ * run check`).
+ *
+ * The issue CODES (`coupon_unknown`, `quantity_above_stock`) and the reason
+ * codes are machine words and are the same in every locale; a test reads the
+ * code, a person reads the message. The details never quote the envelope's
+ * numbers or a cost, in either language (checkout §5.6).
+ */
+import type { LocaleTable } from "@codespar/agent-core";
+import type { KitStrings } from "@codespar/agent-runtime";
+
+const pt = {
+  mandateWord: "política",
+  receiptWord: "pedido",
+  intro: 'Você é o cliente. Diga o que quer ("oi, sou a Marina, quero o pacote de dez aulas e uma avaliação 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 emissão)",
+  notAuthorized: "a política não autoriza",
+  waitingForPayer: (round: number) => `  aguardando o pagamento... (${round} consultas)`,
+
+  order: "pedido",
+  customerLine: (customer: string, cart: string | undefined) => `cliente ${customer}${cart ? `, carrinho ${cart}` : ""}`,
+  lineDiscount: (pct: number) => ` (desconto ${pct}%)`,
+  coupon: (code: string) => `cupom ${code}`,
+  orderDiscount: "desconto no pedido",
+  cartLines: (count: number) => `${count} linha(s)`,
+  charge: "cobrança",
+  paidOrder: "pedido pago",
+  invoiceDocument: (id: string) => ` — documento ${id}`,
+  orderOf: (total: string) => `Pedido de ${total}`,
+
+  toldSettled: (chargeIds: string) => `Recebemos, pedido confirmado! Obrigado. (${chargeIds})`,
+  toldExpired: "A cobrança venceu sem pagamento. Se quiser, emito uma nova para o mesmo pedido.",
+  toldCancelled: "A cobrança foi cancelada. Nada foi pago.",
+  toldAmbiguous: "A cobrança deste pedido já foi emitida e estamos conferindo a situação dela. Não pague de novo; te aviso assim que estiver conferida.",
+  toldFailed: (reason: string | undefined) => `Não consegui emitir a cobrança (${reason ?? "falha no trilho"}). Nada foi cobrado.`,
+  toldDenied: (reason: string | undefined) => `Não consigo fechar o pedido nesses termos (${reason ?? "recusado"}).`,
+  toldUndecided: (why: string) => `O pedido expirou sem confirmação (${why}).`,
+
+  orderApproved: "pedido confirmado; a cobrança sai quando o cliente pedir (action=issue)",
+  orderCartChanged: "o carrinho mudou depois da confirmação; o pedido voltou para o atendente",
+  orderAwaitingAttendant: "aguardando o atendente confirmar o pedido",
+  orderIssued: "cobrança emitida; aguardando o pagamento",
+  orderUncertain: "desfecho da emissão desconhecido; nada será reemitido",
+  orderPaid: "pago",
+  noOrderForCart: (cartId: string) => `o carrinho ${cartId} ainda não virou pedido`,
+  noOrder: "nenhum pedido nesta conversa",
+  alreadyOrdered: (executionId: string) => `este carrinho já é o pedido ${executionId}; nada novo foi criado`,
+  noCart: "nenhum carrinho aberto nesta conversa; cart_update abre um",
+
+  totalItems: "Itens",
+  totalItemsDiscount: "Descontos nos itens",
+  totalSubtotal: "Subtotal",
+  totalOrderDiscount: "Desconto do pedido",
+  totalTotal: "Total",
+  lineValue: "Valor",
+  lineDiscountTotal: "Desconto",
+  lineTotal: "Total da linha",
+
+  issuePriceNotInput: "o preço vem do catálogo da loja; a linha foi recusada inteira",
+  issueSkuUnknown: (sku: string) => `não temos ${sku || "esse item"} no catálogo`,
+  issueUnavailable: (title: string) => `${title} está indisponível`,
+  issueQuantityInvalid: (max: number) => `quantidade deve ser um inteiro de 1 a ${max}`,
+  issueDuplicateSku: (sku: string) => `${sku} aparece mais de uma vez; uma linha por item, com a quantidade total`,
+  issueAboveStock: (stock: number, title: string) => `só há ${stock} de ${title}`,
+  issueCouponUnknown: (code: string) => `o cupom ${code} não existe nesta loja`,
+  issueCouponExpired: (code: string) => `o cupom ${code} expirou`,
+  issueCouponMinimum: (code: string, minimum: string) => `o cupom ${code} vale para pedidos a partir de ${minimum}`,
+
+  outsideServiceHours: (window: string, timezone: string, clock: string) => `fora do horário de atendimento (${window} ${timezone}); agora são ${clock}`,
+  gateOneItem: "um pedido é uma cobrança: um item, cujo valor é o total do carrinho",
+  gateNoCart: "um pedido nasce de um carrinho; esta execução não nomeia nenhum",
+  gateCartMissing: (ref: string) => `o carrinho ${ref} não existe neste estado`,
+  gateCartChanged: "o pedido não corresponde ao carrinho atual; o carrinho mudou depois",
+  gateCartEmpty: "carrinho vazio",
+  gateCartIssues: (codes: string) => `o carrinho tem pendências (${codes})`,
+  gateTotalMismatch: (charged: number, cart: number) => `o pedido cobra ${charged} e o carrinho soma ${cart}`,
+  gateNotForSale: (sku: string) => `${sku} não está à venda`,
+  gateNotListPrice: (sku: string) => `${sku} não está pelo preço de tabela`,
+  gateQuantity: (sku: string) => `quantidade de ${sku} fora do permitido`,
+  gateLineDiscount: (sku: string) => `desconto em ${sku} acima do que a política da loja permite`,
+  gateLineMargin: (sku: string) => `${sku} ficaria abaixo do piso de margem da loja`,
+  gateOrderDiscount: "desconto no pedido acima do que a política da loja permite",
+  gateCouponAndDiscount: "cupom e desconto negociado não se somam",
+  gateCouponInvalid: (code: string) => `o cupom ${code} não vale para este pedido`,
+  gateOrderMargin: "o pedido ficaria abaixo do piso de margem da loja",
+  gateTicket: (total: string) => `pedido de ${total} acima do ticket máximo da loja`,
+  gateNoDueDate: "a cobrança do pedido não tem vencimento",
+  gateDueOutsideWindow: (due: string, today: string, last: string) => `vencimento ${due} fora da janela da loja (de ${today} até ${last})`,
+};
+
+export const STRINGS: LocaleTable<typeof pt & KitStrings> = {
+  "pt-BR": pt,
+  en: {
+    mandateWord: "policy",
+    receiptWord: "order",
+    intro: 'You are the customer. Say what you want ("hi, I am Marina, I want the ten-class pack and an initial assessment"). Ctrl+D or "exit" ends.',
+    prompt: "customer> ",
+    approveQuestion: "  [attendant] Confirm this order? [y/N] ",
+    uncertainDispatch: "  outcome unknown on the rail; run `npm run resume` to reconcile (never repeat the issuance)",
+    notAuthorized: "the policy does not authorize it",
+    waitingForPayer: (round) => `  waiting for the payment... (${round} looks)`,
+
+    order: "order",
+    customerLine: (customer, cart) => `customer ${customer}${cart ? `, cart ${cart}` : ""}`,
+    lineDiscount: (pct) => ` (discount ${pct}%)`,
+    coupon: (code) => `coupon ${code}`,
+    orderDiscount: "order discount",
+    cartLines: (count) => `${count} line(s)`,
+    charge: "charge",
+    paidOrder: "paid order",
+    invoiceDocument: (id) => ` — document ${id}`,
+    orderOf: (total) => `Order of ${total}`,
+
+    toldSettled: (chargeIds) => `Payment received, order confirmed! Thank you. (${chargeIds})`,
+    toldExpired: "The charge reached its due date unpaid. If you like, I can issue a new one for the same order.",
+    toldCancelled: "The charge was cancelled. Nothing was paid.",
+    toldAmbiguous: "The charge for this order was already issued and we are checking where it stands. Do not pay again; I will let you know as soon as it is checked.",
+    toldFailed: (reason) => `I could not issue the charge (${reason ?? "rail failure"}). Nothing was charged.`,
+    toldDenied: (reason) => `I cannot close the order on those terms (${reason ?? "refused"}).`,
+    toldUndecided: (why) => `The order expired without a confirmation (${why}).`,
+
+    orderApproved: "order confirmed; the charge goes out when the customer asks for it (action=issue)",
+    orderCartChanged: "the cart changed after the confirmation; the order went back to the attendant",
+    orderAwaitingAttendant: "waiting for the attendant to confirm the order",
+    orderIssued: "charge issued; waiting for the payment",
+    orderUncertain: "outcome of the issuance unknown; nothing will be re-issued",
+    orderPaid: "paid",
+    noOrderForCart: (cartId) => `cart ${cartId} has not become an order yet`,
+    noOrder: "no order in this conversation",
+    alreadyOrdered: (executionId) => `this cart is already order ${executionId}; nothing new was created`,
+    noCart: "no cart open in this conversation; cart_update opens one",
+
+    totalItems: "Items",
+    totalItemsDiscount: "Item discounts",
+    totalSubtotal: "Subtotal",
+    totalOrderDiscount: "Order discount",
+    totalTotal: "Total",
+    lineValue: "Amount",
+    lineDiscountTotal: "Discount",
+    lineTotal: "Line total",
+
+    issuePriceNotInput: "the price comes from the store's catalog; the whole line was refused",
+    issueSkuUnknown: (sku) => `we do not have ${sku || "that item"} in the catalog`,
+    issueUnavailable: (title) => `${title} is unavailable`,
+    issueQuantityInvalid: (max) => `the quantity must be a whole number from 1 to ${max}`,
+    issueDuplicateSku: (sku) => `${sku} appears more than once; one line per item, with the total quantity`,
+    issueAboveStock: (stock, title) => `there are only ${stock} of ${title}`,
+    issueCouponUnknown: (code) => `coupon ${code} does not exist in this store`,
+    issueCouponExpired: (code) => `coupon ${code} has expired`,
+    issueCouponMinimum: (code, minimum) => `coupon ${code} applies to orders from ${minimum}`,
+
+    outsideServiceHours: (window, timezone, clock) => `outside service hours (${window} ${timezone}); it is ${clock} now`,
+    gateOneItem: "an order is one charge: one item, whose amount is the cart's total",
+    gateNoCart: "an order is born from a cart; this execution names none",
+    gateCartMissing: (ref) => `cart ${ref} does not exist in this state`,
+    gateCartChanged: "the order does not match the current cart; the cart changed afterwards",
+    gateCartEmpty: "empty cart",
+    gateCartIssues: (codes) => `the cart has pending issues (${codes})`,
+    gateTotalMismatch: (charged, cart) => `the order charges ${charged} and the cart adds up to ${cart}`,
+    gateNotForSale: (sku) => `${sku} is not for sale`,
+    gateNotListPrice: (sku) => `${sku} is not at the list price`,
+    gateQuantity: (sku) => `the quantity of ${sku} is outside what is allowed`,
+    gateLineDiscount: (sku) => `the discount on ${sku} is above what the store's policy allows`,
+    gateLineMargin: (sku) => `${sku} would fall below the store's margin floor`,
+    gateOrderDiscount: "the order discount is above what the store's policy allows",
+    gateCouponAndDiscount: "a coupon and a negotiated discount do not add up",
+    gateCouponInvalid: (code) => `coupon ${code} does not apply to this order`,
+    gateOrderMargin: "the order would fall below the store's margin floor",
+    gateTicket: (total) => `an order of ${total} is above the store's maximum ticket`,
+    gateNoDueDate: "the order's charge has no due date",
+    gateDueOutsideWindow: (due, today, last) => `due date ${due} is outside the store's window (from ${today} to ${last})`,
+  },
+};

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

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

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/order-marina.transcript.jsonl

@@ -2,4 +2,4 @@
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_2", "name": "cart_update", "input": {"lines": [{"sku": "aula-avulsa", "quantity": 2}]}}]}
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_3", "name": "codespar_charge", "input": {"action": "create", "customer": "marina", "total_minor": 20000}}]}
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_4", "name": "codespar_charge", "input": {"action": "issue"}}]}
-{"kind": "assistant_step", "reply": "Pedido de duas aulas avulsas, R$ 200,00: o QR e o copia e cola estao acima."}
+{"kind": "assistant_step", "reply": "Pedido de duas aulas avulsas, R$ 200,00: o QR e o copia e cola estão acima."}

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/ordered-marina-awaiting-payer.transcript.jsonl

@@ -1,6 +1,6 @@
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "list_catalog", "input": {}}]}
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_2", "name": "cart_update", "input": {"lines": [{"sku": "pacote-10-aulas", "quantity": 1}, {"sku": "avaliacao-inicial", "quantity": 1}]}}]}
-{"kind": "assistant_step", "reply": "Oi, Marina! Montei o carrinho: pacote de 10 aulas de violao (R$ 390,00) e avaliacao inicial de nivel (R$ 89,90). Total R$ 479,90, cobranca por Pix ou boleto com vencimento hoje. Posso fechar o pedido?"}
+{"kind": "assistant_step", "reply": "Oi, Marina! Montei o carrinho: pacote de 10 aulas de violão (R$ 390,00) e avaliação inicial de nível (R$ 89,90). Total R$ 479,90, cobrança por Pix ou boleto com vencimento hoje. Posso fechar o pedido?"}
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_3", "name": "codespar_charge", "input": {"action": "create", "customer": "marina", "total_minor": 47990}}]}
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_4", "name": "codespar_charge", "input": {"action": "issue"}}]}
-{"kind": "assistant_step", "reply": "Pronto, Marina: a cobranca de R$ 479,90 esta emitida, o codigo esta acima. Assim que o pagamento cair, eu te confirmo por aqui."}
+{"kind": "assistant_step", "reply": "Pronto, Marina: a cobrança de R$ 479,90 está emitida, o código está acima. Assim que o pagamento cair, eu te confirmo por aqui."}

package/templates/checkout-agent/agents/checkout-agent/test/fixtures/tap-falar-agora-marina.transcript.jsonl

@@ -1,2 +1,2 @@
 {"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "status"}}]}
-{"kind": "assistant_step", "reply": "Oi, Marina! Nao ha pedido em aberto nesta conversa. Quer montar um novo?"}
+{"kind": "assistant_step", "reply": "Oi, Marina! Não há pedido em aberto nesta conversa. Quer montar um novo?"}

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

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

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

@@ -110,7 +110,7 @@ describe("checkout §3.3, §5: the gate the core runs at every gate", () => {
     const over = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], order_discount_pct: 9 }, envelope, TODAY);
     expect(checkOrder(order(over), over, envelope, AFTERNOON, TZ)?.reason).toBe("outside_envelope");
     const stacked = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "BEMVINDO10", order_discount_pct: 2 }, envelope, TODAY);
-    expect(checkOrder(order(stacked), stacked, envelope, AFTERNOON, TZ)?.detail).toContain("nao se somam");
+    expect(checkOrder(order(stacked), stacked, envelope, AFTERNOON, TZ)?.detail).toContain("não se somam");
     const coupon = priceCart({ lines: [{ sku: "aula-avulsa", quantity: 2 }], coupon: "BEMVINDO10" }, envelope, TODAY);
     expect(checkOrder(order(coupon), coupon, envelope, AFTERNOON, TZ)).toBeUndefined();
   });
@@ -133,6 +133,6 @@ describe("checkout §3.3, §5: the gate the core runs at every gate", () => {
 
   it("refuses an order above the ticket ceiling", () => {
     const big = priceCart({ lines: [{ sku: "pacote-10-aulas", quantity: 6 }] }, envelope, TODAY);
-    expect(checkOrder(order(big), big, envelope, AFTERNOON, TZ)?.detail).toContain("ticket maximo");
+    expect(checkOrder(order(big), big, envelope, AFTERNOON, TZ)?.detail).toContain("ticket máximo");
   });
 });

package/templates/checkout-agent/agents/checkout-agent/test/rerun-unpaid.test.ts

@@ -0,0 +1,47 @@
+/**
+ * A charge that was out and unpaid when the run ended is the payer's doing,
+ * not the model's: the rerun's payer pays, so it would settle an order the
+ * original left open. The rerun says so instead of reporting that it DIFFERS.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { loadScenario, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+function rerun(runsDir: string, runId: string) {
+  const result = spawnSync(process.execPath, [BIN, "rerun", runId, "--json"], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CHECKOUT_RUNS_DIR: runsDir, CHECKOUT_STATE_DIR: join(runsDir, "state") },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stderr: result.stderr, report: JSON.parse(result.stdout.trim()) as { same_states?: boolean; error?: string; not_replayed?: string[] } };
+}
+
+describe("npm run rerun <run-id> on a checkout run", () => {
+  it("payment-claimed: the charge nobody paid is named, and nothing is replayed", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "checkout-rerun-unpaid-"));
+    const original = await runScenario(agent, loadScenario(agent, "payment-claimed"), { mode: "human", rail: "stub", runsDir });
+    expect(original.executions.map((e) => e.state)).toEqual(["executing"]);
+
+    const out = rerun(runsDir, original.run_id);
+    expect(out.code).toBe(1);
+    expect(out.report.not_replayed).toEqual(["a payer who had not paid when it ended"]);
+    expect(out.report.error).toBe(`runs/${original.run_id} cannot be compared with a rerun: it met a payer who had not paid when it ended, which a rerun does not replay`);
+    expect(out.stderr).not.toContain("DIFFERS");
+  });
+
+  it("happy-path, where the payer paid, is replayed to the same states on the run's clock", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "checkout-rerun-paid-"));
+    const original = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "human", rail: "stub", runsDir });
+    const out = rerun(runsDir, original.run_id);
+    expect(out.code).toBe(0);
+    expect(out.report.same_states).toBe(true);
+  });
+});

package/templates/checkout-agent/agents/checkout-agent/test/scenario-reach-and-seconds.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Two things `npm start` says with no model key: which recording an `--input`
+ * replays, and how long a scenario pack took.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { loadScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+function start(args: string[]) {
+  const stateDir = mkdtempSync(join(tmpdir(), "checkout-reach-"));
+  const result = spawnSync(process.execPath, [BIN, "start", ...args], {
+    cwd: AGENT_DIR,
+    // Pinned inside the service hours, as the other process tests of this agent are.
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "2026-09-23T14:00:00-03:00", CHECKOUT_STATE_DIR: stateDir, CHECKOUT_RUNS_DIR: join(stateDir, "runs") },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+describe("npm start -- --input <the first turn of a scenario>", () => {
+  // The three that opened with one sentence, of which --input could only ever replay the first.
+  it.each(["cart-recomposed", "cart-replaced", "charge-expired"])("%s: replays its own recording", (name) => {
+    const out = start(["--input", loadScenario(agent, name).turns[0]!.input, "--json"]);
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain(`replaying ${join(AGENT_DIR, "scenarios", `${name}.transcript.jsonl`)}`);
+  });
+});
+
+describe("npm start -- --scenario <name> on the stub rail", () => {
+  it("says ok and where the bundle is, and no seconds: the stub's clock is the scenario's, not a watch", () => {
+    const began = Date.now();
+    const out = start(["--scenario", "happy-path", "--mode", "human"]);
+    const wall = (Date.now() - began) / 1000;
+    expect(out.code).toBe(0);
+    const ok = out.stderr.split("\n").find((line) => line.startsWith("== ok"))!;
+    expect(ok).toMatch(/^== ok — bundle em /);
+    expect(ok).not.toMatch(/\d+(\.\d+)?s — /);
+    // What the line used to claim: the scenario's clock counts 16 seconds here, and the process takes a fraction of that.
+    expect(wall).toBeLessThan(16);
+  });
+
+  it("--json still carries the cycle the scenario's clock counted, for the checks that read it", () => {
+    const out = start(["--scenario", "happy-path", "--mode", "human", "--json"]);
+    const report = JSON.parse(out.stdout.trim()) as { results: Array<{ ok: boolean; run: { rail: string; cycle_seconds: number | null } }> };
+    expect(report.results[0]).toMatchObject({ ok: true, run: { rail: "stub", cycle_seconds: expect.any(Number) } });
+  });
+});

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

@@ -11,7 +11,7 @@ import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { describe, expect, it } from "vitest";
-import { parseConversationScript, parseTemplateRegistry, templateArity, type Execution } from "@codespar/agent-core";
+import { WHATSAPP_LANGUAGE, parseConversationScript, parseTemplateRegistry, templateArity, type Execution } from "@codespar/agent-core";
 import { handleExecution, setup } from "@codespar/agent-runtime";
 import { agent } from "../src/kit.js";
 
@@ -65,9 +65,18 @@ const conversationOf = (p: Payload) => {
 };
 
 const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+/**
+ * The probe closes its connection, as every emulator call in these tests does.
+ * An agent run here is a `spawnSync`, which blocks this process's event loop
+ * for longer than the emulator's keep-alive (`Keep-Alive: timeout=5`), so a
+ * pooled socket is never expired by fetch and the next call on it dies
+ * `fetch failed … ECONNRESET`. This file makes one call today; the header is
+ * here so the next one does not inherit a pooled socket.
+ */
+const FRESH_CONNECTION = { connection: "close" } as const;
 const emulatorUp = await (async () => {
   try {
-    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+    return (await fetch(`${EMULATOR}/health`, { headers: FRESH_CONNECTION, signal: AbortSignal.timeout(2000) })).ok;
   } catch {
     return false;
   }
@@ -82,6 +91,10 @@ describe.skipIf(!emulatorUp)("the sale closes over the WhatsApp channel", () =>
     expect(out.code).toBe(0);
     const p = payloadOf(out.stdout);
     expect(p.executions.map((e) => e.state)).toEqual(["settled"]);
+    // The channel's one-shot carries the same count and refusal list as the terminal's.
+    const counted = p as unknown as { run_outcome: Record<string, number>; refused_before_draft: unknown[] };
+    expect(counted.run_outcome).toMatchObject({ settled: 1, failed: 0 });
+    expect(counted.refused_before_draft).toEqual([]);
     expect(p.invoices.map((i) => i.state)).toEqual(["accepted"]);
     expect(p.channel.backend).toBe("emulator");
     const outbound = conversationOf(p).filter((l) => l.direction === "out");
@@ -158,14 +171,17 @@ describe("the conversation decides who is charged, with no emulator in sight", (
   it("every template the kit can send is declared, with the arity it is sent with", () => {
     const registry = parseTemplateRegistry(readFileSync(join(AGENT_DIR, "channels/whatsapp/templates.json"), "utf8"));
     const order = { total: 47990 } as Execution;
-    for (const e of [{ ...order, state: "settled" }, { ...order, state: "failed", reason: "charge_expired" }, { ...order, state: "failed", reason: "charge_cancelled" }] as Execution[]) {
-      const t = agent.kit.outcomeTemplate!(e)!;
-      const declared = registry.templates.find((x) => x.name === t.template);
-      expect(declared).toBeDefined();
-      expect(templateArity(declared!.body)).toBe(t.variables.length);
-      expect(t.variables).toEqual(["R$ 479,90"]);
+    // In each locale: the same template names, declared in that locale's language, the total formatted for its reader.
+    for (const [locale, total] of [["pt-BR", "R$ 479,90"], ["en", "R$479.90"]] as const) {
+      for (const e of [{ ...order, state: "settled" }, { ...order, state: "failed", reason: "charge_expired" }, { ...order, state: "failed", reason: "charge_cancelled" }] as Execution[]) {
+        const t = agent.kit.outcomeTemplate!(e, locale)!;
+        const declared = registry.templates.find((x) => x.name === t.template && x.language === WHATSAPP_LANGUAGE[locale]);
+        expect(declared).toBeDefined();
+        expect(templateArity(declared!.body)).toBe(t.variables.length);
+        expect(t.variables).toEqual([total]);
+      }
+      // An order refused or never approved is answered in the turn; no template pretends otherwise.
+      expect(agent.kit.outcomeTemplate!({ ...order, state: "denied", reason: "outside_envelope" } as Execution, locale)).toBeUndefined();
     }
-    // An order refused or never approved is answered in the turn; no template pretends otherwise.
-    expect(agent.kit.outcomeTemplate!({ ...order, state: "denied", reason: "outside_envelope" } as Execution)).toBeUndefined();
   });
 });

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

@@ -3,7 +3,7 @@
     {
       "name": "codespar_charge",
       "effect": "charge",
-      "description": "The order and its charge. action=create turns the cart into an ORDER for the customer you are talking to: the code prices it from the catalog, checks it against the sales policy (price, discount, margin floor, ticket, service hours) and, depending on the approval mode, asks the attendant or confirms it alone. Nothing is issued by create. action=issue sends the confirmed order's charge: ONE bolepix (cobranca com vencimento, due today: the customer pays by Pix or by boleto) for the cart's total, with an idempotency key, so asking twice returns the same charge; the code presents the QR and the copy-and-paste. If the cart changed after the order was confirmed, issue sends it back to the attendant instead. action=status reads the order. You never pass an amount or a document: the code takes the total from the cart and the customer's name and document from the store's customer book.",
+      "description": "The order and its charge. action=create turns the cart into an ORDER for the customer you are talking to: the code prices it from the catalog, checks it against the sales policy (price, discount, margin floor, ticket, service hours) and, depending on the approval mode, asks the attendant or confirms it alone. Nothing is issued by create. action=issue sends the confirmed order's charge: ONE bolepix (cobrança com vencimento, due today: the customer pays by Pix or by boleto) for the cart's total, with an idempotency key, so asking twice returns the same charge; the code presents the QR and the copy-and-paste. If the cart changed after the order was confirmed, issue sends it back to the attendant instead. action=status reads the order. You never pass an amount or a document: the code takes the total from the cart and the customer's name and document from the store's customer book.",
       "input_schema": {
         "type": "object",
         "properties": {

package/templates/checkout-agent/packages/agent-core/README.md

@@ -1,8 +1,8 @@
 # @codespar/agent-core
 
-The primitives every CodeSpar starter-kit agent inherits (spec v5.1.1, section 4): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract and the two providers.
+The primitives every CodeSpar starter-kit agent inherits (section 4 of spec v5.1.1, [`docs/spec-v5.1.1.md`](../../docs/spec-v5.1.1.md), the only spec version in this repository; [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) says where later parts were built against v5.2 and the checkout spec v0.2): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract, the conversation loop and the two providers.
 
-This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|check|eval`, the setup that wires this package to an agent directory, and the scenario and adversarial runners — is [`@codespar/agent-runtime`](../agent-runtime), which depends on this one and is what an agent's `package.json` scripts call (#13). Nothing here knows an agent's name.
+This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|inspect|check|eval|verify`, the setup that wires this package to an agent directory, and the scenario and adversarial runners — is [`@codespar/agent-runtime`](../agent-runtime), which depends on this one and is what an agent's `package.json` scripts call (#13). Nothing here knows an agent's name.
 
 ## The state machine, and what the types do and do not prove
 
@@ -25,10 +25,29 @@ This package is the decisions. The RUNNER around them — the terminal channel,
 
 Every spend carries `approval: { items_hash, batch_hash? }`, the artifact's own hashes (`spendApprovalOf`), and the API seals them into the receipt's chain as a link of their own (chain v4, ent#1670). Both rails refuse a spend without them before any call. `composition` is not sent: the API takes the two hashes and nothing else, and only charges carry a composition today. `receipt-chain.ts` recomputes a chain from the receipt read under the `chain_recipe` the key document publishes (RFC 8785 implemented locally, `node:crypto` only), and `verifyReceiptRead` holds the signature, the body and the sealed approval link against the artifact, in that order. It proves WHAT was approved to anybody holding the read; WHO approved stays in the artifact, under the local key. `docs/OPEN_QUESTIONS.md` §3 and §47.
 
+## Who acted, on the wire
+
+Every spend sends the kit's actor as the SDK's `PaymentActor` (`wireActorOf` in `rail.ts`): an agent is `{ type: "agent", id: "<name>@<version>", on_behalf_of: <the mandate's consumer> }`, a person `{ type: "human", id, channel }`. `agent_id` still goes too; it names the agent the mandate was signed for. The rail reads the actor the API recorded back as `sealed_actor`, the bundle's receipt copy keeps it beside the kit's own `actor`, and one that differs from what was sent, or is missing, is a `receipt.actor_mismatch` event. It does not stop the run: the actor is what the receipt records, not what it proves. It is not in the chain, so a third party checking the Ed25519 signature learns nothing about who triggered the spend, and a charge carries no actor at all. §2.
+
+## A settlement this run did not make
+
+A spend presented again under the same attempt id is answered with the earlier payment (`idempotent_replay`). Dispatch marks that outcome `replayed: true`, and `isReplayedSettlement(execution)` is true when every settled attempt carries the mark. The money moved, and this execution did not move it. The execution is still `settled`. Only dispatch writes the mark, because dispatch is always this execution's first presentation of an id. Reconcile does not copy it: a lookup presents the attempt again, and the API answers every look at a settled attempt as a replay, this execution's own payment included. The tool results and a one-shot's `--json` read this predicate (`replayed`); `inspect` reads the same mark from the bundle's rail answers. An attempt closed by reconcile is still counted as paid by the execution that looked it up. §39c.
+
 ## Reconcile never re-dispatches
 
 An execution left in `executing` is looked up on the rail, attempt by attempt. A recorded settled or failed outcome closes it; `in_flight`, `uncertain` or unknown leaves it in `executing` with `reason: rail_uncertain` for a human. The single exception is an outbox row still `pending` (the state changed, no call was ever made): those attempts go out once, under the same ids.
 
+## The conversation loop
+
+`AgentLoop.turn` (`agent.ts`) sends the model the system prompt, the conversation and the tool specs, and hands each tool call to the kit's handler for it; a tool outside `tools.json` is refused `tool_not_allowed`. Only the engine behind the handlers moves money. Two things it adds that no prompt can:
+
+- **The reply language.** `detectLanguage` (`language.ts`) reads the language of what the person typed, Brazilian Portuguese or English, from function words; payee names, amounts and Pix keys count for neither. The loop appends a "Reply language for this turn" section naming it to the system prompt of every step of the turn. Tool results do not count: on the Messages API they are user-role messages, and a prompt rule alone lost to their Portuguese data. A turn with no lead either way keeps the previous turn's language, and before any lead the prompt's own default stands. The transcript's user line records `reply_language` (`null` before any lead). §64.
+- **The date.** `ExecutionEngine.today()` is the date in the guardrails' timezone at the engine's clock, so `--now` pins it. `list_bills`, `list_payables` and `list_agreements` return it as `today`, and bills and payables also carry `days_until_due` (`daysUntil`), because the model has no calendar of its own.
+
+## What the code prints, per locale
+
+`locale.ts` and `strings.ts` (#64). A run has one locale, `pt-BR` or `en`: `--locale`, else the optional `locale:` of `agent.yaml`, else `pt-BR` (`resolveLocale`). `CORE_STRINGS` holds the lines every agent shares (the batch gesture, the waits, how an execution and a payable instrument read, the WhatsApp operator lines) in both locales, and `tableGaps` is what `npm run check` runs over it and over each kit's table: a key one locale lacks, an empty string, or a function whose arity differs is an error. `formatBRL` and `formatDay` format for the locale's reader ("R$ 1.850,00" / "R$1,850.00"; "30/09/2026" / "2026-09-30"). `WHATSAPP_LANGUAGE` maps a locale to the language Meta approves a template in (`pt_BR`, `en_US`); the template registry holds one copy per (name, language), and the check requires every template in the language of every locale. None of it touches what an answer decides, and it is independent of the reply language above.
+
 ## Stubs
 
 `stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, `org_paused: true` (the organization kill switch, ent#1648) refuses it whatever `status` says, and a read that does not answer, or answers without `org_paused`, is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.

package/templates/checkout-agent/packages/agent-core/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.128.0",
-    "@codespar/sdk": "0.16.10",
+    "@codespar/sdk": "0.16.16",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   }