@codespar/cli 0.17.0 → 0.18.0

package/templates/checkout-agent/scripts/whatsapp-emulator.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Runs the WhatsApp Cloud API emulator the channel's `simulator` backend talks
+ * to: `dyvit-wa-sim`, published as `@dyvit/whatsapp-simulator-cli` (MIT) from
+ * https://github.com/fabianocruz/whatsapp-simulator. It is not ours and it is
+ * not a dependency of this workspace.
+ *
+ * WHY NOT A DEPENDENCY. It is a development tool. Nothing in `packages/` or
+ * `agents/` imports it, so `npm ci` has no reason to fetch it and a contributor
+ * who never runs the WhatsApp gate never downloads it. `npx` fetches the exact
+ * version into its own cache the first time it is needed; nothing is vendored,
+ * nothing is installed globally, and the repository's tree is untouched.
+ *
+ * WHY PINNED TO A VERSION. A moving `latest` would make our gate fail on
+ * somebody else's release. `--version` overrides, and there is no `latest`.
+ * The spec handed to `npx` is exact, so it cannot resolve anything else.
+ *
+ * Usage:
+ *   node scripts/whatsapp-emulator.mjs                   start it (foreground)
+ *   node scripts/whatsapp-emulator.mjs --prepare         fetch only
+ *   node scripts/whatsapp-emulator.mjs --version <v>     a different release
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const EMULATOR_PACKAGE = "@dyvit/whatsapp-simulator-cli";
+/** The release the gate is measured against. Bump deliberately, never automatically. */
+export const EMULATOR_VERSION = "0.3.0";
+export const EMULATOR_PORT = 4290;
+/** Must match `WHATSAPP_SIM_APP_SECRET`. A local development value, not a credential. */
+export const EMULATOR_APP_SECRET = "dev";
+/** Where the channel's own receiver listens; the emulator posts its webhooks there. */
+export const EMULATOR_WEBHOOK_PORT = 4399;
+
+function spec(version) {
+  return `${EMULATOR_PACKAGE}@${version}`;
+}
+
+/** Warms `npx`'s cache so the start below does not race a download. */
+export function prepare(version = EMULATOR_VERSION, say = (l) => process.stderr.write(l + "\n")) {
+  say(`whatsapp emulator: fetching ${spec(version)}`);
+  const result = spawnSync("npx", ["--yes", spec(version), "--help"], { stdio: ["ignore", "ignore", "inherit"] });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`could not fetch ${spec(version)} (npx exited ${result.status}). Is the version published, and is the network reachable?`);
+  }
+  return spec(version);
+}
+
+function serve(version, webhookUrl) {
+  const child = spawn(
+    "npx",
+    ["--yes", spec(version), "serve", "--port", String(EMULATOR_PORT), "--webhook", webhookUrl, "--app-secret", EMULATOR_APP_SECRET],
+    // Its own process group: `npx` is a wrapper around the real server, and a
+    // signal sent to the wrapper alone leaves the port held by an orphan.
+    { cwd: ROOT, stdio: "inherit", detached: true },
+  );
+  const stop = () => {
+    try {
+      process.kill(-child.pid, "SIGTERM");
+    } catch {
+      child.kill("SIGTERM");
+    }
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  const argv = process.argv.slice(2);
+  const version = argv.includes("--version") ? argv[argv.indexOf("--version") + 1] : EMULATOR_VERSION;
+  const webhookUrl = argv.includes("--webhook") ? argv[argv.indexOf("--webhook") + 1] : `http://127.0.0.1:${EMULATOR_WEBHOOK_PORT}/`;
+  if (argv.includes("--prepare")) {
+    prepare(version);
+    process.stderr.write(`whatsapp emulator ready: ${spec(version)}\n`);
+  } else {
+    process.stderr.write(`whatsapp emulator: ${spec(version)} on :${EMULATOR_PORT}, webhooks to ${webhookUrl}\n`);
+    serve(version, webhookUrl);
+  }
+}

package/templates/checkout-agent/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  }
+}

package/templates/checkout-agent/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["packages/*/test/**/*.test.ts", "agents/*/test/**/*.test.ts", "test/**/*.test.ts"],
+    pool: "forks",
+    maxWorkers: 1,
+    minWorkers: 1,
+    fileParallelism: false,
+    testTimeout: 30000,
+  },
+});

package/templates/collections-agent/README.md

@@ -1,7 +1,7 @@
 # {{name}}
 
 Scaffolded by `codespar init --template collections-agent` from the `collections-agent` starter kit
-(https://github.com/codespar/agent-starter-kits at `8f130b7cdc30510c929e6f7ebb07184f763e6ce4`, agent 0.1.0).
+(https://github.com/codespar/agent-starter-kits at `b766575306a71c9135c0d70e23d591e6523dc2f8`, agent 0.1.0).
 
 The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.
 
@@ -18,6 +18,11 @@ against are vendored here and linked as npm workspaces; the agent's own
   npm start
 ```
 
+The kits root scripts this agent's channels use are carried too, verbatim, and
+run at this root as they do in the kits repo:
+
+  - `npm run whatsapp:emulator` — `scripts/whatsapp-emulator.mjs`
+
 The agent's guide is [`agents/collections-agent/README.md`](agents/collections-agent/README.md); its commands run at this root
 (`npm run check`, `npm run eval`, `npm test`) or inside `agents/collections-agent/`. The manifest pins
 `cli: "@codespar/cli@0.14.0"`, the CLI version whose `agent run`/`eval` this agent was written for.

package/templates/collections-agent/agents/collections-agent/README.md

@@ -71,9 +71,11 @@ Cloud API's own response shape and posts back the same signed
 `x-hub-signature-256` webhooks, so what runs against it is the adapter itself.
 It also has a clock we can move (`POST /_sim/clock`), which a replay finishing
 in seconds cannot otherwise have. No Meta account, no credential, and no
-traffic that leaves the machine. What it does NOT cover is measured, with the
-exact payloads, in `docs/OPEN_QUESTIONS.md` §46 — chief among them that it
-prices the 24-hour window but does not enforce it.
+traffic that leaves the machine. What it did not cover at 0.1.1 was measured, with
+the exact payloads, in `docs/OPEN_QUESTIONS.md` §46; 0.2.0 closed
+all five, chief among them that it ENFORCES the 24-hour window with Meta's
+own 400/131047 instead of only pricing it, and the pinned 0.3.0 corrects the
+four places 0.2.0 differed from its release note.
 
 `--scripted` replays the debtor's turns from `channels/whatsapp/<name>.json`,
 which is what an agent ships for this channel: the contact the conversation is
@@ -179,11 +181,13 @@ nothing. It runs in the CI, which starts the emulator in its own step.
 
 A fourth run covers the case the other three cannot reach: agree, move the
 conversation's clock 26 hours, let the sandbox payer pay, poll. It asserts the
-execution settled and the confirmation went out as a TEMPLATE. Read that
-precisely: the emulator PRICES the 24-hour window and does not ENFORCE it
-(`docs/OPEN_QUESTIONS.md` §46a), so what passes is OUR choice of carrier and
-not the provider refusing the alternative. The day the emulator enforces the
-window, that run gets stronger without changing.
+execution settled and the confirmation went out as a TEMPLATE, and it asks the
+emulator directly whether it would have carried the free-form alternative: it
+must answer 400/131047, as Meta does (`docs/OPEN_QUESTIONS.md` §46a). A fifth
+run moves the two clocks apart — the conversation's 26 hours, the agent's one —
+so our window reads open while the provider's is shut; the free-form
+confirmation is refused with 131047 and the poll tells the person by the
+template instead, once.
 
 ## The sandbox payer
 

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/README.md

@@ -109,3 +109,11 @@ credential, nothing leaving the machine. `npm run whatsapp:gate` at the
 repository root runs the whole cycle over it three times from a clean state
 and asserts the final state each time, plus a fourth run that agrees now, moves
 the conversation's clock past 24 hours, pays, and polls.
+
+## Taps, failed deliveries and the fallback (OPEN_QUESTIONS §46)
+
+A template may declare quick replies `{ id, title, intent }`. When the person taps one, the model is handed the `intent`, never the button's title, and a tap on an id no template declares is recorded and skipped. `acordo_cobranca_vencida` offers "Emitir nova" / "Agora nao", and `acordo-1042-retomada.json` is Joana tapping "Emitir nova" the day after.
+
+A delivery the provider reports `failed` (131026: not on WhatsApp, blocked) is recorded, becomes `message.debtor.failed` when it told an outcome, reaches the operator's console, and makes the poll answer `delivery_failed` instead of "told". A `read` is recorded and nothing more.
+
+`atendimento_atualizacao` is the registry's FALLBACK, the one template a poll sends for an outcome the agent has no copy for. It states nothing about the outcome and asks the person to answer. `npm run check` requires exactly one fallback, taking no variables.

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/acordo-1042-retomada.json

@@ -0,0 +1,10 @@
+{
+  "name": "acordo-1042-retomada",
+  "description": "The day after: the charge for order #1042 expired, the poll told Joana with the acordo_cobranca_vencida template, and she answers by TAPPING its 'Emitir nova' button instead of typing. The tap is a turn whose text is the intent the template declares for that button, never the button's title and never the model's reading of it; the agent issues again and the payer pays.",
+  "channel": "whatsapp",
+  "contact": "+5511987654321",
+  "subject": "acordo-1042",
+  "turns": [
+    { "reply": { "id": "emitir_nova", "title": "Emitir nova" } }
+  ]
+}

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/templates.json

@@ -11,13 +11,39 @@
       "name": "acordo_cobranca_vencida",
       "language": "pt_BR",
       "description": "The receivable reached its due date unpaid. The same message the terminal sends free-form, and it has to be its own template: a debtor whose charge expired must not be told the agreement is settled. {{1}} is the agreement alias.",
-      "body": "Oi! A cobranca do {{1}} venceu sem pagamento. Se quiser, emito uma nova dentro das mesmas condicoes."
+      "body": "Oi! A cobranca do {{1}} venceu sem pagamento. Se quiser, emito uma nova dentro das mesmas condicoes.",
+      "buttons": [
+        {
+          "id": "emitir_nova",
+          "title": "Emitir nova",
+          "intent": "quero que voce emita uma nova cobranca para o meu acordo"
+        },
+        {
+          "id": "agora_nao",
+          "title": "Agora nao",
+          "intent": "agora nao quero uma nova cobranca para o meu acordo"
+        }
+      ]
     },
     {
       "name": "acordo_cobranca_cancelada",
       "language": "pt_BR",
       "description": "The receivable was cancelled, so nothing was paid and nothing is owed on it. {{1}} is the agreement alias.",
       "body": "Oi! A cobranca do {{1}} foi cancelada e nada foi pago. Qualquer coisa, e so falar por aqui."
+    },
+    {
+      "name": "atendimento_atualizacao",
+      "language": "pt_BR",
+      "description": "The FALLBACK: sent by a poll, outside the 24-hour window, when an outcome closed that the agent has no template of its own for (a charge the rail failed to issue, a proposal denied or expired days later). It states NOTHING about the outcome, so it can never be the wrong news; it asks the person to answer, and an answer reopens the window, inside which the agent says what happened in free text. Takes no variables.",
+      "body": "Oi! Temos uma atualizacao sobre o seu atendimento. Responda esta mensagem para continuarmos por aqui.",
+      "fallback": true,
+      "buttons": [
+        {
+          "id": "falar_agora",
+          "title": "Falar agora",
+          "intent": "quero saber qual e a atualizacao do meu atendimento"
+        }
+      ]
     }
   ]
 }

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

@@ -184,6 +184,8 @@ whatsapp: --backend simulator|cloud-api  default simulator, which is the local e
     if (execution.state === "settled") text = `Recebemos, acordo quitado. 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 dentro das mesmas condicoes.";
     else if (execution.reason === "charge_cancelled") text = "A cobranca foi cancelada. Nada foi pago.";
+    // Failed or refused, the same fact: a charge was issued and nobody can yet say whether it was paid. Never "nada foi cobrado".
+    else if (execution.reason === "charge_reference_ambiguous") text = "A cobranca deste acordo 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 posso emitir nesses termos (${execution.reason ?? "recusado"}).`;
     else text = `A proposta expirou sem decisao (${execution.state}).`;

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

@@ -22,6 +22,9 @@ export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
   const listAgreements: ToolHandler = async (_input, ctx) => {
     const settled = ctx.engine.list({ state: "settled" });
     const open = ctx.engine.list({ state: "executing" });
+    // Issued, then its reference turned ambiguous: the charge exists and may be paid. Not open, and the core refuses another until it is reconciled.
+    const unreconciled = ctx.engine.list({ state: "failed" }).filter((e) => e.reason === "charge_reference_ambiguous");
+    const unreconciledAliases = new Set(unreconciled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
     const settledAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
     const issuedAliases = new Set(open.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
     return {
@@ -32,7 +35,13 @@ export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
         principal: formatBRL(a.principal_minor),
         origin: a.origin,
         opened_at: a.opened_at,
-        status: settledAliases.has(a.alias) ? "quitado" : issuedAliases.has(a.alias) ? "cobranca emitida, aguardando pagamento" : "em aberto",
+        status: settledAliases.has(a.alias)
+          ? "quitado"
+          : issuedAliases.has(a.alias)
+            ? "cobranca emitida, aguardando pagamento"
+            : unreconciledAliases.has(a.alias)
+              ? "cobranca emitida, em conferencia: nao emitir outra"
+              : "em aberto",
       })),
       envelope: {
         max_discount_pct: envelope.max_discount_pct,
@@ -98,7 +107,8 @@ function describe(execution: import("@codespar/agent-core").Execution) {
     ...(execution.reason ? { reason: execution.reason, detail: execution.detail } : {}),
     ...(execution.escalation ? { escalated_by: execution.escalation.trigger } : {}),
     charges,
-    issued: charges.length > 0 && charges.every((c) => c.status !== "failed"),
+    issued: execution.reason === "charge_reference_ambiguous" ? execution.state === "failed" : charges.length > 0 && charges.every((c) => c.status !== "failed"),
+    ...(execution.reason === "charge_reference_ambiguous" ? { reconcile_before_reissue: true } : {}),
     paid: execution.state === "settled",
     expired: execution.state === "failed" && execution.reason === "charge_expired",
   };

package/templates/collections-agent/agents/collections-agent/test/ambiguous-charge.test.ts

@@ -0,0 +1,55 @@
+/**
+ * An issued receivable whose reference turned ambiguous (`charge_reference_ambiguous`)
+ * may still be paid. The agent must not report the agreement as open, must not tell the
+ * debtor nothing was charged, and must not issue a second charge for the same debt.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { Execution } from "@codespar/agent-core";
+import { announceOutcome, setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+describe("a receivable closed charge_reference_ambiguous: reconcile, never reissue", () => {
+  it("list_agreements does not reopen it, a new charge for it is refused before the rail, and the debtor is not told nothing was charged", async () => {
+    let clock = new Date("2026-09-23T18:00:00Z");
+    const s = setup(agent, { mode: "mandate", rail: "stub", provider: "replay", transcript: "unused", stateDir: mkdtempSync(join(tmpdir(), "collections-ambiguous-")), runsDir: mkdtempSync(join(tmpdir(), "collections-ambiguous-runs-")), now: () => (clock = new Date(clock.getTime() + 1000)), say: () => undefined });
+    try {
+      s.payer!.behave("never");
+      const d = await s.engine.draft({ items: [{ payee: "acordo-1042", amount: 108000, due_date: "2026-09-30" }] });
+      if (!d.ok) throw new Error("refused");
+      const issued = await s.engine.execute(d.execution.id);
+      expect(issued.state).toBe("executing");
+      // The stub rail cannot answer 409; the core's own test drives that read. Here the closed execution is what the agent reads.
+      const chargeId = issued.outcomes[0]!.transaction_id!;
+      const closed: Execution = {
+        ...issued,
+        state: "failed",
+        reason: "charge_reference_ambiguous",
+        detail: "charge_reference_ambiguous: the reference matches more than one charge",
+        outcomes: [{ index: 0, attempt_id: issued.outcomes[0]!.attempt_id, status: "failed", code: "charge_reference_ambiguous", error: "charge_reference_ambiguous" }],
+        history: [...issued.history, { from: "executing", to: "failed", at: clock.toISOString(), actor: issued.actor, reason: "charge_reference_ambiguous" }],
+      };
+      s.store.saveExecution(closed);
+
+      const handlers = s.kit.handlers(s);
+      const ctx = { engine: s.engine, onExecution: async (e: Execution) => e };
+      const listed = (await handlers["list_agreements"]!({}, ctx)) as { agreements: Array<{ alias: string; status: string }> };
+      expect(listed.agreements.find((a) => a.alias === "acordo-1042")?.status).toBe("cobranca emitida, em conferencia: nao emitir outra");
+
+      const again = (await handlers["codespar_charge"]!({ action: "create", agreement: "acordo-1042", instalments: [{ amount_minor: 108000, due_date: "2026-10-15" }] }, ctx)) as Record<string, unknown>;
+      expect(again).toMatchObject({ status: "denied", reason: "charge_reference_ambiguous", issued: false, charges: [] });
+      expect(s.engine.list({ state: "executing" })).toHaveLength(0);
+      expect(s.engine.list().flatMap((e) => e.outcomes).filter((o) => o.transaction_id && o.transaction_id !== chargeId)).toEqual([]);
+
+      const told: string[] = [];
+      announceOutcome(closed, s, (l) => told.push(l));
+      expect(told).toHaveLength(1);
+      expect(told[0]).toContain("ja foi emitida");
+      expect(told[0]).not.toContain("Nada foi cobrado");
+    } finally {
+      s.close();
+    }
+  });
+});

package/templates/collections-agent/agents/collections-agent/test/fixtures/tap-emitir-nova-1042.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "create", "agreement": "acordo-1042", "instalments": [{"amount_minor": 108000, "due_date": "2026-09-30"}], "total_minor": 108000}}]}
+{"kind": "assistant_step", "reply": "Pronto, Joana: emiti uma nova cobranca de R$ 1.080,00, vencendo em 30/09. O codigo esta acima."}

package/templates/collections-agent/agents/collections-agent/test/whatsapp-poll.test.ts

@@ -11,11 +11,11 @@
  * what the guardrails and the window comparison read.
  *
  * What is asserted is which CARRIER the confirmation went out on and that the
- * cycle closed, never the wording. Read the template assertions precisely:
- * the emulator prices the 24-hour window and does not enforce it
- * (docs/OPEN_QUESTIONS.md §46a), so what passes here is OUR choice of
- * carrier, made by the session window, and not the provider refusing the
- * alternative.
+ * cycle closed, never the wording. Here the carrier is chosen by the session
+ * window with both clocks moved together; since 0.2.0 the emulator also
+ * refuses the free-form alternative with 131047 (docs/OPEN_QUESTIONS.md
+ * §46a), and `npm run whatsapp:gate` asks it to, and drives the case where
+ * the two clocks disagree.
  *
  * The conversing cases SKIP without the emulator, like the rest of the
  * channel suite; `npm run whatsapp:gate` fails rather than skipping, so the
@@ -72,9 +72,15 @@ interface PollPayload {
   channel: { backend: string; session_open: boolean; messages_out: number; refused: Array<{ rule: string }>; log: string } | null;
 }
 
+/**
+ * One scratch per case: its state, its runs, and its own conversation on the
+ * emulator (#42). The agree and the poll of a case share it, which is the
+ * point; two cases never do.
+ */
 function scratch(label: string) {
   const stateDir = mkdtempSync(join(tmpdir(), `collections-wa-poll-${label}-`));
-  return { COLLECTIONS_STATE_DIR: stateDir, COLLECTIONS_RUNS_DIR: join(stateDir, "runs") };
+  const phoneNumberId = `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`;
+  return { COLLECTIONS_STATE_DIR: stateDir, COLLECTIONS_RUNS_DIR: join(stateDir, "runs"), WHATSAPP_SIM_PHONE_NUMBER_ID: phoneNumberId };
 }
 
 function agent(args: string[], env: Record<string, string>) {

package/templates/collections-agent/agents/collections-agent/test/whatsapp-status-replies.test.ts

@@ -0,0 +1,148 @@
+/**
+ * §46's three product gaps on the collections-agent, in real processes
+ * against the emulator: the confirmation of a paid agreement that the provider
+ * reports FAILED is not an agreement the debtor was told about; an outcome the
+ * kit has no template for goes out as the registry's fallback; and a tapped
+ * "Emitir nova" is a turn, as the intent the template declared. Each case runs
+ * in a conversation of its own (#42). They SKIP without the emulator; the gate
+ * does not.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it } from "vitest";
+import { pollWhatsApp, setup } from "@codespar/agent-runtime";
+import { agent as collections } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+const TUESDAY = "2026-09-23T14:00:00-03:00";
+const AFTER_WINDOW = new Date(new Date(TUESDAY).getTime() + 26 * 3600_000).toISOString();
+const AGREED = "test/fixtures/agreed-1042-awaiting-payer.transcript.jsonl";
+const CONTACT = "5511987654321";
+
+const emulatorUp = await (async () => {
+  try {
+    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+  } catch {
+    return false;
+  }
+})();
+
+function scratch(label: string) {
+  const stateDir = mkdtempSync(join(tmpdir(), `collections-wa-sr-${label}-`));
+  return { COLLECTIONS_STATE_DIR: stateDir, COLLECTIONS_RUNS_DIR: join(stateDir, "runs"), WHATSAPP_SIM_PHONE_NUMBER_ID: `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}` };
+}
+
+const baseEnv = (env: Record<string, string>) => ({ ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", WHATSAPP_PHONE_NUMBER_ID: "", WHATSAPP_ACCESS_TOKEN: "", WHATSAPP_VERIFY_TOKEN: "", WHATSAPP_APP_SECRET: "", ...env });
+
+function run(args: string[], env: Record<string, string>) {
+  const r = spawnSync(NODE, [BIN, ...args], { cwd: AGENT_DIR, env: baseEnv(env), encoding: "utf8", timeout: 90_000 });
+  return { code: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+const lastJson = (stdout: string) => JSON.parse(stdout.split("\n").filter(Boolean).pop()!) as Record<string, unknown>;
+
+async function sim(path: string, body?: unknown) {
+  const r = await fetch(`${EMULATOR}${path}`, body === undefined ? {} : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  return (await r.json()) as Record<string, unknown>;
+}
+
+function events(env: Record<string, string>, type: string): Array<{ execution_id: string | null; payload: Record<string, unknown> }> {
+  const db = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+  try {
+    return (db.prepare("SELECT execution_id, payload FROM events WHERE type = ?").all(type) as Array<{ execution_id: string | null; payload: string }>).map((r) => ({ execution_id: r.execution_id, payload: JSON.parse(r.payload) as Record<string, unknown> }));
+  } finally {
+    db.close();
+  }
+}
+
+/** A log path is relative to the cwd of whoever wrote it: the agent's directory for a child process, this process's for an in-process poll. */
+function channelLog(logPath: string, base = AGENT_DIR): Array<Record<string, unknown>> {
+  const path = isAbsolute(logPath) ? logPath : resolve(base, logPath);
+  return readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+describe.skipIf(!emulatorUp)("§46 on the collections-agent, against the emulator", () => {
+  it("the paid-agreement template the provider reports FAILED (131026) is not an agreement the debtor was told about", { timeout: 60_000 }, async () => {
+    const env = scratch("failed");
+    expect(run(["start", "--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--mode", "mandate", "--transcript", AGREED, "--now", TUESDAY, "--json"], { ...env, COLLECTIONS_STUB_PAYER: "never" }).code).toBe(3);
+    await sim("/_sim/clock", { advance_hours: 26 });
+
+    // The poll, in its own process, with a long enough wait for the status the provider reports after the send.
+    const child = spawn(NODE, [BIN, "poll", "--channel", "whatsapp", "--conversation", "acordo-1042", "--simulate-payer", "--now", AFTER_WINDOW, "--json"], { cwd: AGENT_DIR, env: baseEnv({ ...env, WHATSAPP_STATUS_GRACE_MS: "6000" }) });
+    let stdout = "";
+    child.stdout.on("data", (c: Buffer) => (stdout += c.toString()));
+    const exit = new Promise<number | null>((done) => child.on("exit", (code) => done(code)));
+
+    // As soon as the confirmation template exists at the provider, the provider reports it failed.
+    const key = `${env["WHATSAPP_SIM_PHONE_NUMBER_ID"]}:${CONTACT}`;
+    let template: string | undefined;
+    for (let i = 0; i < 200 && !template; i += 1) {
+      const state = (await sim(`/_sim/state?key=${key}`)) as { messages?: Array<{ id: string; direction: string; kind: string }> };
+      template = state.messages?.find((m) => m.direction === "business_to_user" && m.kind === "template")?.id;
+      if (!template) await new Promise((r) => setTimeout(r, 50));
+    }
+    expect(template).toBeDefined();
+    await sim("/_sim/status", { status: "failed", message_id: template, reason: "not on whatsapp" });
+
+    expect(await exit).toBe(1);
+    const polled = (lastJson(stdout)["polled"] as Array<{ state: string; delivery: { told: boolean; reason?: string } }>)[0]!;
+    // The cycle closed: the money is where the rail says it is. The telling of it did not happen.
+    expect(polled.state).toBe("settled");
+    expect(polled.delivery).toMatchObject({ told: false, reason: "delivery_failed" });
+    const failed = events(env, "message.debtor.failed");
+    expect(failed).toHaveLength(1);
+    expect(failed[0]!.payload).toMatchObject({ message_id: template, state: "settled" });
+    expect((failed[0]!.payload["errors"] as Array<{ code: number }>)[0]!.code).toBe(131026);
+  });
+
+  it("an outcome the kit has no template for goes out as the registry's fallback, which states no outcome", { timeout: 60_000 }, async () => {
+    const env = scratch("fallback");
+    expect(run(["start", "--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--mode", "mandate", "--transcript", AGREED, "--now", TUESDAY, "--json"], { ...env, COLLECTIONS_STUB_PAYER: "never" }).code).toBe(3);
+    await sim("/_sim/clock", { advance_hours: 26 });
+
+    // The same agent with no copy for any outcome: what a kit that never wrote one looks like to the poll.
+    const bare = { ...collections, kit: { ...collections.kit, outcomeTemplate: () => undefined } };
+    const saved = { ...process.env };
+    Object.assign(process.env, { ...env, COLLECTIONS_STATE_DIR: env["COLLECTIONS_STATE_DIR"], ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "" });
+    const written: string[] = [];
+    const write = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string) => (written.push(String(chunk)), true)) as typeof process.stdout.write;
+    const s = setup(bare, { mode: "mandate", rail: "stub", stateDir: env["COLLECTIONS_STATE_DIR"]!, runsDir: env["COLLECTIONS_RUNS_DIR"]!, now: () => new Date(AFTER_WINDOW), say: () => undefined });
+    let code: number;
+    try {
+      code = await pollWhatsApp({ agent: bare, setup: s, conversation: "acordo-1042", backend: "simulator", json: true, simulatePayer: true, now: () => new Date(AFTER_WINDOW), say: () => undefined });
+    } finally {
+      process.stdout.write = write;
+      s.close();
+      for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+      Object.assign(process.env, saved);
+    }
+    expect(code).toBe(0);
+    const payload = JSON.parse(written.join("").trim().split("\n").pop()!) as { polled: Array<{ delivery: Record<string, unknown> }>; channel: { log: string } };
+    expect(payload.polled[0]!.delivery).toEqual({ told: true, carrier: "template", template: "atendimento_atualizacao", fallback: true });
+    const last = channelLog(payload.channel.log, process.cwd()).filter((l) => l["direction"] === "out").at(-1)!;
+    expect(String(last["text"])).toContain("atendimento_atualizacao");
+    expect(last["offered"]).toEqual(["falar_agora"]);
+    expect(events(env, "message.debtor").at(-1)!.payload).toMatchObject({ template: "atendimento_atualizacao", fallback: true });
+  });
+
+  it("a tapped 'Emitir nova' is a turn, and the model is handed the intent the template declared for it", { timeout: 60_000 }, () => {
+    const env = scratch("tap");
+    const out = run(["start", "--channel", "whatsapp", "--conversation", "acordo-1042-retomada", "--scripted", "--mode", "mandate", "--transcript", "test/fixtures/tap-emitir-nova-1042.transcript.jsonl", "--simulate-payer", "--now", TUESDAY, "--json"], env);
+    expect(out.code).toBe(0);
+    const payload = lastJson(out.stdout) as { run_id: string; executions: Array<{ state: string }>; channel: { taps: unknown[]; log: string } };
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(payload.channel.taps).toEqual([{ id: "emitir_nova", turn: true }]);
+    const tap = channelLog(payload.channel.log).find((l) => l["kind"] === "reply")!;
+    expect(tap).toMatchObject({ direction: "in", reply: { id: "emitir_nova", title: "Emitir nova" }, text: "quero que voce emita uma nova cobranca para o meu acordo" });
+    // What the MODEL was handed: the declared intent, verbatim, as the person's turn.
+    const transcript = readFileSync(join(env["COLLECTIONS_RUNS_DIR"]!, payload.run_id, "transcript.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { kind: string; text?: string });
+    expect(transcript.filter((t) => t.kind === "user").map((t) => t.text)).toEqual(["quero que voce emita uma nova cobranca para o meu acordo"]);
+  });
+});

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

@@ -43,6 +43,9 @@ interface Payload {
   channel: { backend: string; conversation: string; turns: number; messages_in: number; messages_out: number; refused: Array<{ rule: string }>; log: string };
 }
 
+/** The emulator keys a conversation on `phone_number_id:contact`; a fresh id is a fresh conversation for the same contact. */
+const freshPhoneNumberId = () => `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`;
+
 function run(args: string[], extra: Record<string, string> = {}) {
   const stateDir = mkdtempSync(join(tmpdir(), "collections-wa-"));
   const result = spawnSync(NODE, [BIN, "start", ...args], {
@@ -58,6 +61,8 @@ function run(args: string[], extra: Record<string, string> = {}) {
       WHATSAPP_APP_SECRET: "",
       COLLECTIONS_STATE_DIR: stateDir,
       COLLECTIONS_RUNS_DIR: join(stateDir, "runs"),
+      // A conversation of its own on the emulator (#42): no case inherits another's inbound messages, or the window they anchor.
+      WHATSAPP_SIM_PHONE_NUMBER_ID: freshPhoneNumberId(),
       ...extra,
     },
     encoding: "utf8",

package/templates/collections-agent/package.json

@@ -15,6 +15,7 @@
     "check": "npm run check --workspaces --if-present --",
     "test": "vitest run --pool=forks --maxWorkers=1",
     "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/tsconfig.json && tsc --noEmit -p agents/collections-agent/tsconfig.json",
+    "whatsapp:emulator": "node scripts/whatsapp-emulator.mjs",
     "approve": "npm run approve --workspace=agents/collections-agent --",
     "deny": "npm run deny --workspace=agents/collections-agent --",
     "eval": "npm run eval --workspace=agents/collections-agent --",

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

@@ -12,10 +12,23 @@ This package is the decisions. The RUNNER around them — the terminal channel,
 
 `ExecutionEngine.policy()` runs at draft, at a human's approval and again immediately before `executing`, inside the transaction that writes the outbox row. Mandate status, allowlist, per-transaction cap, the window cap (counting settled, in flight AND awaiting executions as reservations), `escalate_above` and the artifact's `items_hash` are all re-checked at the last gate. A person's approval satisfies `escalate_above` and nothing else.
 
+## What the artifact binds besides the items
+
+`items_hash` covers the execution's items: payee, amount, currency and a receivable's due date. Two optional bindings cover what those fields cannot see, and each is **omitted, never null**, when it does not apply, so an artifact without them signs the same bytes it signed before they existed (`test/composition.test.ts` pins that against an artifact hashed on `main` before `composition` was added):
+
+- `batch` — the set a line was approved inside (`batch_hash` over the ordered lines, the line's `index`, the `count`). One execution per line, N lines.
+- `composition` — what ONE amount is made of (`{ ref, composition_hash, line_count }`, with `compositionHash` over the resolved lines). One execution, N lines behind it: a sale is one charge, so a cart of three lines is one item whose amount is the order's total. Two units at 100 and one unit at 200 are the same item and the same `items_hash`; they are not the same `composition_hash`. `compositionHash` uses `itemsHash`'s canonicalisation over `ref`, `quantity`, `unit_amount`, `amount` and `currency`, not `itemsHash` itself, because ten units at a 10% discount and nine at list price have the same line amount.
+
+`checkApprovalArtifact` compares both, and the last gate sends a mismatch back to `awaiting_approval` with `items_hash_mismatch`, like a changed list. `ExecutionEngine.restate()` is how an OPEN execution (`awaiting_approval`, `approved`) follows the proposal behind it — a customer who changes the cart after the order was approved — without a transition: items, total, `items_hash` and composition are replaced, the state, the artifact and the idempotency key are kept, and the last gate does the refusing. The payees of a restatement cannot change.
+
+## What of the artifact reaches the receipt
+
+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.
+
 ## 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.
 
 ## 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`, and a read that does not answer 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.
+`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/collections-agent/packages/agent-core/package.json

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