@codespar/cli 0.16.0 → 0.18.0

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-evidence.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Decision 19a: `attestation.evidence` on the consent submit, built from what
+ * a conversation channel can honestly say it observed (ent#1615).
+ *
+ * The first test is the important one and it asserts a REFUSAL. A simulated
+ * conversation was observed by nobody, and signing a counter as a provider
+ * message id would put a made-up fact inside a record whose whole value is
+ * that it is observed. The seam is wired; the simulator declines to use it.
+ *
+ * The rest hold the shape to the API's own rule, so a change here fails in
+ * the repo instead of failing as a 400 at the consent submit.
+ */
+import { describe, expect, it } from "vitest";
+import { evidenceFor, WHATSAPP_EVIDENCE_KEYS } from "../src/channels/whatsapp/evidence.js";
+import type { InboundMessage } from "../src/channels/types.js";
+
+const AT = (iso: string) => Math.floor(Date.parse(iso) / 1000);
+const NOW = () => new Date("2026-09-23T17:00:00Z");
+const REAL: InboundMessage = {
+  id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND",
+  from: "+5511987654321",
+  text: "sim, autorizo",
+  timestamp: AT("2026-09-23T17:00:00Z"),
+};
+
+describe("what an emulated conversation may attest", () => {
+  it("refuses, and says why in a sentence somebody can act on", () => {
+    const result = evidenceFor({ live: false, message: { ...REAL, id: "wamid.sim.9f1c" }, now: NOW });
+    expect(result.attestable).toBe(false);
+    if (result.attestable) return;
+    expect(result.reason).toContain("emulator");
+    expect(result.reason).toContain("no phone was involved");
+  });
+
+  it("refuses even when the emulated message wears a provider-shaped id, because the id is not what decides", () => {
+    expect(evidenceFor({ live: false, message: REAL, now: NOW }).attestable).toBe(false);
+  });
+});
+
+describe("what a live conversation attests", () => {
+  it("builds the submit's attestation with the four keys the whatsapp channel may carry", () => {
+    const result = evidenceFor({ live: true, message: REAL, sessionId: "conv_1042", reference: "acordo-1042", now: NOW });
+    expect(result.attestable).toBe(true);
+    if (!result.attestable) return;
+    expect(result.attestation).toEqual({
+      method: "partner_session",
+      asserted_at: AT("2026-09-23T17:00:00Z"),
+      reference: "acordo-1042",
+      evidence: {
+        channel: "whatsapp",
+        contact: "+5511987654321",
+        message_id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND",
+        session_id: "conv_1042",
+        provider_ts: AT("2026-09-23T17:00:00Z"),
+      },
+    });
+  });
+
+  it("carries the contact in the clear, because the API hashes it under a key a partner cannot compute", () => {
+    const result = evidenceFor({ live: true, message: REAL, now: NOW });
+    if (!result.attestable) throw new Error("expected evidence");
+    expect(result.attestation.evidence.contact).toBe("+5511987654321");
+    expect(result.attestation.evidence).not.toHaveProperty("contact_hash");
+  });
+
+  it("never carries an ip, a user agent, a device id or a geo: on this channel each of those was inferred", () => {
+    const result = evidenceFor({ live: true, message: REAL, now: NOW });
+    if (!result.attestable) throw new Error("expected evidence");
+    const keys = Object.keys(result.attestation.evidence).filter((k) => k !== "channel");
+    expect(keys.every((k) => (WHATSAPP_EVIDENCE_KEYS as readonly string[]).includes(k))).toBe(true);
+    for (const forbidden of ["ip", "user_agent", "device_id_hash", "geo"]) expect(result.attestation.evidence).not.toHaveProperty(forbidden);
+  });
+
+  it("separates the partner's clock from the provider's: asserted_at is ours, provider_ts is theirs", () => {
+    const result = evidenceFor({ live: true, message: { ...REAL, timestamp: AT("2026-09-23T15:00:00Z") }, now: () => new Date("2026-09-23T17:00:05Z") });
+    if (!result.attestable) throw new Error("expected evidence");
+    expect(result.attestation.asserted_at).toBe(AT("2026-09-23T17:00:05Z"));
+    expect(result.attestation.evidence.provider_ts).toBe(AT("2026-09-23T15:00:00Z"));
+  });
+
+  it("refuses a reference with a dot: the canonical signing string joins segments, and a wamid goes in message_id", () => {
+    const result = evidenceFor({ live: true, message: REAL, reference: "wamid.HBgN", now: NOW });
+    expect(result.attestable).toBe(false);
+  });
+
+  it("refuses a message id or a session id the API's opaque-id shape would reject", () => {
+    expect(evidenceFor({ live: true, message: { ...REAL, id: "wamid with spaces" }, now: NOW }).attestable).toBe(false);
+    expect(evidenceFor({ live: true, message: REAL, sessionId: "conv 1042", now: NOW }).attestable).toBe(false);
+  });
+
+  it("refuses a message the provider gave no timestamp for", () => {
+    expect(evidenceFor({ live: true, message: { ...REAL, timestamp: 0 }, now: NOW }).attestable).toBe(false);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-rules.test.ts

@@ -0,0 +1,174 @@
+/**
+ * The rules of collecting over a conversation, tried and refused.
+ *
+ * Every case here is an ATTEMPT: the message is handed to the channel the way
+ * the runner hands it one, and what is asserted is that nothing left the
+ * process. The backend under the channel is a recorder, so "refused" is not a
+ * claim about a return value — it is the recorder having seen nothing.
+ *
+ * The last case is the one that matters most: the same attempts through a
+ * DIFFERENT backend. The rules live above the backend, so choosing one cannot
+ * be a way around them.
+ */
+import { describe, expect, it } from "vitest";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { checkOutbound } from "../src/channels/rules.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+/** A backend that carries nothing and remembers everything it was asked to carry. */
+class Recorder implements ChannelBackend {
+  readonly delivered: Array<{ to: string; body: OutboundBody }> = [];
+  constructor(
+    readonly name = "recorder",
+    readonly live = false,
+    private readonly inbox: InboundMessage[] = [],
+  ) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push({ to, body });
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const INSIDE = new Date("2026-09-23T14:00:00-03:00");
+const OUTSIDE = new Date("2026-09-23T22:30:00-03:00");
+const HOURS = { window: "08:00-20:00", timezone: "America/Sao_Paulo" };
+
+function channelAt(now: Date, backend = new Recorder(), openSession = true) {
+  const channel = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    hours: HOURS,
+    knownSubjects: ["acordo-1042", "acordo-1077", "acordo-1103"],
+    templates: [{ name: "cobranca_lembrete", language: "pt_BR", description: "a reminder", body: "Oi {{1}}, sobre o acordo." }],
+  });
+  // A session is open because the person wrote; the window is WhatsApp's rule, not ours, and has its own test below.
+  if (openSession) {
+    (channel as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(now.getTime() / 1000));
+  }
+  return { channel, backend };
+}
+
+describe("the collection rules, tried through the channel", () => {
+  it("sends inside the collection hours", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses everything outside the collection hours, and the backend never sees it", async () => {
+    const { channel, backend } = channelAt(OUTSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(sent.state).toBe("failed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a message to any contact but the one the conversation is bound to", () => {
+    const refusal = checkOutbound("+5511900000000", { kind: "text", text: "sobre a sua divida" }, {
+      conversation: { contact: CONTACT, subject: "acordo-1042" },
+      hours: HOURS,
+      now: () => INSIDE,
+    });
+    expect(refusal?.rule).toBe("bound_contact");
+  });
+
+  it("refuses a message that names another debtor's agreement", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("O acordo-1077 do Carlos tambem esta em aberto, voces podem combinar.");
+    expect(sent.refused?.rule).toBe("subject_scope");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a CPF or a CNPJ in a message, formatted or bare", async () => {
+    for (const text of ["confirma o CPF 111.444.777-35?", "o CPF do titular e 11144477735", "CNPJ 12.345.678/0001-95", "CNPJ 12345678000195"]) {
+      const { channel, backend } = channelAt(INSIDE);
+      const sent = await channel.say(text);
+      expect(sent.refused?.rule, text).toBe("no_document");
+      expect(backend.delivered).toHaveLength(0);
+    }
+  });
+
+  it("does NOT read a Pix copy-and-paste or a boleto line as a document", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
+    const bankLine = "78517596684364082005302425802108566187285620000";
+    expect((await channel.send({ kind: "instrument", instrument: "pix_copy_paste", value: brcode })).refused).toBeUndefined();
+    expect((await channel.send({ kind: "instrument", instrument: "boleto_bank_line", value: bankLine })).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(2);
+  });
+
+  it("refuses an empty message", async () => {
+    const { channel } = channelAt(INSIDE);
+    expect((await channel.say("   ")).refused?.rule).toBe("empty_message");
+  });
+
+  it("masks the contact everywhere it is written down", async () => {
+    const { channel } = channelAt(INSIDE);
+    await channel.say("Oi!");
+    for (const line of channel.log()) {
+      expect(line.contact).not.toContain("987654321");
+      expect(line.contact).toContain("****");
+    }
+  });
+
+  it("applies the same rules through a different backend: a backend is not a way around one", async () => {
+    const other = new Recorder("another-backend", true);
+    const { channel, backend } = channelAt(OUTSIDE, other);
+    expect((await channel.say("boa noite, sobre a sua divida")).refused?.rule).toBe("collection_hours");
+    expect((await channelAt(INSIDE, new Recorder("another-backend", true)).channel.say("CPF 11144477735")).refused?.rule).toBe("no_document");
+    expect(backend.delivered).toHaveLength(0);
+  });
+});
+
+describe("WhatsApp's own rule: the 24-hour session window", () => {
+  it("carries a free-form message while the window is open", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    expect((await channel.say("Oi, Joana!")).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a free-form message once the window has shut, and says what would carry", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(sent.refused?.detail).toContain("template");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries a declared template with the window shut", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a template the agent never declared: Meta only delivers the ones it approved", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("holds a template to the house rules too: an approved template is not a way past the hours", async () => {
+    const { channel, backend } = channelAt(OUTSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("reopens the window when the person writes again", async () => {
+    const backend = new Recorder("recorder", false, [{ id: "in_1", from: CONTACT, text: "oi", timestamp: Math.floor(INSIDE.getTime() / 1000) }]);
+    const { channel } = channelAt(INSIDE, backend, false);
+    expect((await channel.say("antes")).refused?.rule).toBe("session_window_closed");
+    await channel.next();
+    expect((await channel.say("depois")).refused).toBeUndefined();
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-session.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The 24-hour window, read back and reasoned about.
+ *
+ * Two things are under test and they are the two halves of issue #25. A
+ * conversation that a later process comes back to has to know where its
+ * window stood, and the only honest source for that is the PROVIDER's
+ * timestamp in the record — not the run's own clock, which belongs to a
+ * machine WhatsApp never consulted. And a message that may only go as a
+ * template has to be held to what the agent actually declared, because a
+ * template Meta never approved is not a message, it is a 4xx.
+ *
+ * None of it needs the emulator: every refusal here happens above the
+ * backend, which is the whole claim `channels/` makes.
+ */
+import { describe, expect, it } from "vitest";
+import { templateArity, type WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { SessionWindow, sessionStateFromChannelLog, SESSION_WINDOW_SECONDS } from "../src/channels/whatsapp/session.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+class Recorder implements ChannelBackend {
+  readonly name = "recorder";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return undefined;
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const TUESDAY = new Date("2026-09-23T14:00:00-03:00");
+const FRIDAY = new Date("2026-09-25T14:00:00-03:00");
+const QUITADO: WhatsAppTemplate = { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Recebemos o pagamento do {{1}}." };
+
+function channel(now: Date, lastInboundAt?: number, backend = new Recorder()) {
+  const c = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    templates: [QUITADO],
+    ...(lastInboundAt !== undefined ? { session: { lastInboundAt } } : {}),
+  });
+  return { channel: c, backend };
+}
+
+describe("where the window stood, read back from the record", () => {
+  it("takes the provider's timestamp and never the line's own `at`", () => {
+    const state = sessionStateFromChannelLog([
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182801 },
+      { direction: "out", at: "2026-09-23T17:00:10.000Z" },
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182821 },
+    ]);
+    expect(state.lastInboundAt).toBe(1790182821);
+  });
+
+  it("yields nothing from a log whose inbound lines carry no provider timestamp, and the window then reads as shut", () => {
+    // A bundle written before the timestamp was recorded. Shut is the safe
+    // direction: a template is deliverable in both halves of the rule.
+    const state = sessionStateFromChannelLog([{ direction: "in", at: "2026-09-23T17:00:00.000Z", text: "oi" }]);
+    expect(state.lastInboundAt).toBeUndefined();
+    expect(new SessionWindow([], state).open(TUESDAY)).toBe(false);
+  });
+
+  it("ignores outbound lines: the window is opened by the PERSON writing, not by us", () => {
+    expect(sessionStateFromChannelLog([{ direction: "out", provider_timestamp: 1790182801 }]).lastInboundAt).toBeUndefined();
+  });
+});
+
+describe("a conversation a later process comes back to", () => {
+  it("writes freely when the restored window is still open", async () => {
+    const { channel: c, backend } = channel(TUESDAY, Math.floor(TUESDAY.getTime() / 1000) - 3600);
+    expect(c.sessionOpen).toBe(true);
+    expect(c.sessionRemainingSeconds).toBe(SESSION_WINDOW_SECONDS - 3600);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses free text once the restored window has shut, which is the case the poll exists for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    expect(c.sessionOpen).toBe(false);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries the declared template in the same breath, with the language the registry holds", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const declared = c.declaredTemplate("acordo_quitado");
+    expect(declared?.language).toBe("pt_BR");
+    const sent = await c.send({ kind: "template", template: declared!.name, language: declared!.language, variables: ["acordo-1042"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toEqual([{ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"] }]);
+  });
+
+  it("reads as shut when nothing restored it: a process with no record of the conversation assumes the worst", () => {
+    expect(channel(TUESDAY).channel.sessionOpen).toBe(false);
+  });
+});
+
+describe("when the provider's clock disagrees with ours", () => {
+  /** A provider whose window is shut whatever ours says: free text is refused the way Meta refuses it, templates go. */
+  class ShutProvider extends Recorder {
+    override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+      if (body.kind === "template") return super.deliver(to, body);
+      return { id: "", state: "failed", refused: { rule: "session_window_closed", detail: "the provider refused the free-form message (400/131047)" } };
+    }
+  }
+
+  it("believes the provider: after a 131047 the window reads shut, and a template still goes", async () => {
+    const { channel: c, backend } = channel(TUESDAY, Math.floor(TUESDAY.getTime() / 1000) - 3600, new ShutProvider());
+    expect(c.sessionOpen).toBe(true);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(c.sessionOpen).toBe(false);
+    expect(c.sessionRemainingSeconds).toBe(0);
+    // Refused by our own rule from here, so a second free-form message never reaches the provider.
+    expect((await c.say("de novo")).refused?.detail).toContain("more than 24h");
+    const template = await c.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"] });
+    expect(template.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("reopens when the person writes again, because that is what opens a window at Meta too", () => {
+    const window = new SessionWindow([], { lastInboundAt: Math.floor(TUESDAY.getTime() / 1000) - 3600 });
+    window.observeProviderShut();
+    expect(window.open(TUESDAY)).toBe(false);
+    window.observeInbound(Math.floor(TUESDAY.getTime() / 1000));
+    expect(window.open(TUESDAY)).toBe(true);
+  });
+});
+
+describe("the local registry refuses what Meta would refuse", () => {
+  it("a name the agent never declared", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a language the template was not registered in: an approved template does not exist in another", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "es_MX", variables: ["acordo-1042"] });
+    expect(sent.refused?.rule).toBe("template_language_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a variable count the body has no placeholders for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042", "a mais"] });
+    expect(sent.refused?.rule).toBe("template_variables_mismatch");
+    expect(sent.refused?.detail).toContain("takes 1 variable(s)");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("counts the placeholders the way Meta numbers them", () => {
+    expect(templateArity("nenhuma")).toBe(0);
+    expect(templateArity("Oi {{1}}, sobre o {{2}}.")).toBe(2);
+    expect(templateArity("Oi {{ 1 }}.")).toBe(1);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-status-replies.test.ts

@@ -0,0 +1,182 @@
+/**
+ * §46's three product gaps, as the channel now answers them, with no network:
+ * a status webhook is read (a `failed` of an outcome's message is that
+ * outcome NOT told), a tapped quick reply becomes a turn only as the intent a
+ * declared template gave it, and the registry carries a fallback for an
+ * outcome the kit has no copy for. The same behaviour against the emulator is
+ * in the repository's `test/whatsapp-emulator.integration.test.ts`, and the
+ * `check` rule that requires the fallback, asked of the shipped agents, in
+ * `test/whatsapp-fallback-check.test.ts`: both read this repository's other
+ * agents and scripts, which a template made from one agent does not carry.
+ */
+import { describe, expect, it } from "vitest";
+import type { WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { buildSendRequest, parseInbound, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
+import type { ChannelBackend, ChannelLogLine, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../src/channels/types.js";
+
+const CONTACT = "+5511987654321";
+const NOW = new Date("2026-09-23T17:00:00Z");
+
+/** A backend the test drives: it queues what the person does and hands the channel the statuses the test reports. */
+class Scripted implements ChannelBackend {
+  readonly name = "scripted";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  private listener: ((s: StatusUpdate) => void) | undefined;
+  constructor(private readonly inbox: InboundMessage[] = []) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `wamid.test.${this.delivered.length}`, state: "sent" };
+  }
+  onStatus(listener: (s: StatusUpdate) => void): void {
+    this.listener = listener;
+  }
+  report(status: StatusUpdate): void {
+    this.listener?.(status);
+  }
+  async close(): Promise<void> {}
+}
+
+const TEMPLATES: WhatsAppTemplate[] = [
+  { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Oi! {{1}} quitado." },
+  {
+    name: "acordo_cobranca_vencida",
+    language: "pt_BR",
+    description: "expired",
+    body: "Oi! A cobranca do {{1}} venceu.",
+    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" },
+    ],
+  },
+  { name: "atendimento_atualizacao", language: "pt_BR", description: "fallback", body: "Oi! Temos uma atualizacao.", fallback: true },
+];
+
+function channel(inbox: InboundMessage[] = []) {
+  const backend = new Scripted(inbox);
+  const said: string[] = [];
+  const failed: ChannelLogLine[] = [];
+  const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT, subject: "acordo-1042" }, now: () => NOW, templates: TEMPLATES, say: (l) => said.push(l), onDeliveryFailed: (l) => failed.push(l) });
+  return { ch, backend, said, failed };
+}
+
+const tap = (id: string, extra: Partial<InboundMessage["reply"]> = {}): InboundMessage => ({ id: `wamid.in.${id}`, from: CONTACT, text: "Emitir nova", timestamp: 1790190000, reply: { type: "button_reply", id, title: "Emitir nova", ...extra } });
+
+describe("1. a status webhook is read, and a failed outcome is an outcome not told", () => {
+  it("parses statuses, with Meta's errors, out of the same delivery that carries messages", () => {
+    const parsed = parseInbound({
+      entry: [{ changes: [{ value: { statuses: [{ id: "wamid.a", status: "failed", timestamp: "1790190000", errors: [{ code: 131026, title: "Message undeliverable", error_data: { details: "not on whatsapp" } }] }, { id: "wamid.b", status: "read", timestamp: "1790190001" }, { id: "wamid.c", status: "deleted" }] } }] }],
+    });
+    expect(parsed.statuses).toEqual([
+      { message_id: "wamid.a", status: "failed", timestamp: 1790190000, errors: [{ code: 131026, title: "Message undeliverable", details: "not on whatsapp" }] },
+      { message_id: "wamid.b", status: "read", timestamp: 1790190001, errors: [] },
+    ]);
+  });
+
+  it("a failed status of a message that told an outcome is recorded, reaches the operator and the outcome's owner, and names the outcome", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos, acordo quitado.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "failed", timestamp: 1790190100, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(ch.deliveryOf(sent.id)).toBe("failed");
+    const status = ch.log().find((l) => l.direction === "status")!;
+    expect(status).toMatchObject({ kind: "status", message_id: sent.id, state: "failed", about: { execution_id: "exe_1", state: "settled" }, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(failed).toEqual([status]);
+    expect(said.join("\n")).toContain("a pessoa NAO foi avisada");
+  });
+
+  it("a read is recorded and nothing more: not consent, not an acknowledgement, not a reply", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "read", timestamp: 1790190100, errors: [] });
+    expect(ch.log().filter((l) => l.direction === "status").map((l) => l.state)).toEqual(["read"]);
+    expect(failed).toEqual([]);
+    expect(said).toEqual([]);
+    // A read is not a turn either.
+    expect(await ch.next()).toBeUndefined();
+  });
+
+  it("a failure the provider reports BEFORE the send answered (the emulator posts statuses synchronously) is still tied to its outcome", async () => {
+    class Eager extends Scripted {
+      override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+        const sent = await super.deliver(to, body);
+        this.report({ message_id: sent.id, status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+        return sent;
+      }
+    }
+    const backend = new Eager();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    await ch.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"], about: { execution_id: "exe_2", state: "settled" } });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_2", state: "settled" }]);
+  });
+
+  it("a status about a message an EARLIER run sent is tied back to the outcome that run recorded", async () => {
+    const prior: ChannelLogLine = { at: NOW.toISOString(), direction: "out", contact: "+55*****4321", kind: "template", message_id: "wamid.old", state: "sent", about: { execution_id: "exe_old", state: "settled" } };
+    const backend = new Scripted();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, priorLines: [prior], onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    backend.report({ message_id: "wamid.old", status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+    expect(failed[0]?.about).toEqual({ execution_id: "exe_old", state: "settled" });
+  });
+});
+
+describe("2. a tapped quick reply is a turn, as the intent a declared template gave it", () => {
+  it("parses a button_reply, a list_reply and a template's quick-reply button, id and context kept", () => {
+    const msg = (m: Record<string, unknown>) => ({ entry: [{ changes: [{ value: { messages: [{ from: "5511987654321", timestamp: "1", ...m }] } }] }] });
+    expect(parseInbound(msg({ id: "a", type: "interactive", interactive: { type: "button_reply", button_reply: { id: "emitir_nova", title: "Emitir nova" } }, context: { id: "wamid.offer" } })).messages[0]?.reply).toEqual({ type: "button_reply", id: "emitir_nova", title: "Emitir nova", context_id: "wamid.offer" });
+    expect(parseInbound(msg({ id: "b", type: "interactive", interactive: { type: "list_reply", list_reply: { id: "3x", title: "3x", description: "tres" } } })).messages[0]?.reply).toEqual({ type: "list_reply", id: "3x", title: "3x" });
+    expect(parseInbound(msg({ id: "c", type: "button", button: { payload: "emitir_nova", text: "Emitir nova" } })).messages[0]?.reply).toEqual({ type: "button", id: "emitir_nova", title: "Emitir nova" });
+    // What this channel cannot read is still named, not turned into an empty message.
+    expect(parseInbound(msg({ id: "d", type: "image" })).ignored).toEqual([{ id: "d", type: "image" }]);
+    expect(parseInbound(msg({ id: "e", type: "interactive", interactive: { type: "nfm_reply" } })).ignored).toEqual([{ id: "e", type: "interactive:nfm_reply" }]);
+  });
+
+  it("a declared id is a turn whose text is the declared intent, never the title", async () => {
+    const { ch } = channel([tap("emitir_nova")]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("quero que voce emita uma nova cobranca para o meu acordo");
+    const line = ch.log().at(-1)!;
+    expect(line).toMatchObject({ direction: "in", kind: "reply", reply: { id: "emitir_nova", title: "Emitir nova" }, text: "quero que voce emita uma nova cobranca para o meu acordo" });
+  });
+
+  it("an id no template declares is not a turn: recorded, told to the operator, and the next real turn is what comes back", async () => {
+    const typed: InboundMessage = { id: "wamid.in.text", from: CONTACT, text: "oi", timestamp: 1790190001 };
+    const { ch, said } = channel([tap("pagar_tudo", { title: "Pagar tudo" }), typed]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("oi");
+    expect(ch.log()[0]).toMatchObject({ kind: "reply", refused: { rule: "reply_not_offered" }, reply: { id: "pagar_tudo" } });
+    expect(said.join("\n")).toContain("reply_not_offered");
+  });
+
+  it("a tap that names a message this conversation did not send with that reply is not a turn either", async () => {
+    const { ch } = channel([tap("emitir_nova", { context_id: "wamid.somebody_else" })]);
+    expect(await ch.next()).toBeUndefined();
+    expect(ch.log()[0]?.refused?.rule).toBe("reply_not_offered");
+  });
+
+  it("a template goes out with the quick replies its declaration offers, and the log says which", async () => {
+    const { ch, backend } = channel();
+    await ch.send({ kind: "template", template: "acordo_cobranca_vencida", language: "pt_BR", variables: ["acordo-1042"] });
+    expect((backend.delivered[0] as { buttons?: unknown }).buttons).toEqual([{ id: "emitir_nova", title: "Emitir nova" }, { id: "agora_nao", title: "Agora nao" }]);
+    expect(ch.log()[0]?.offered).toEqual(["emitir_nova", "agora_nao"]);
+    const config: CloudApiConfig = { baseUrl: "http://sim", phoneNumberId: "1", accessToken: "t", verifyToken: "v", appSecret: "s", apiVersion: "v22.0", webhookPort: 0 };
+    const request = buildSendRequest(config, CONTACT, backend.delivered[0]!) as { body: string };
+    expect(JSON.parse(request.body).template.components).toEqual([
+      { type: "body", parameters: [{ type: "text", text: "acordo-1042" }] },
+      { type: "button", sub_type: "quick_reply", index: "0", parameters: [{ type: "payload", payload: "emitir_nova" }] },
+      { type: "button", sub_type: "quick_reply", index: "1", parameters: [{ type: "payload", payload: "agora_nao" }] },
+    ]);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}