@codespar/cli 0.17.0 → 0.18.1

package/templates/checkout-agent/packages/agent-runtime/src/channels/whatsapp/emulator.ts

@@ -0,0 +1,216 @@
+/**
+ * The house simulator, which is not ours: `dyvit-wa-sim`, the local Cloud API
+ * emulator from https://github.com/fabianocruz/whatsapp-simulator (MIT).
+ *
+ * WHY A SEPARATE PROCESS INSTEAD OF A FAKE IN THIS REPO. A mock we wrote would
+ * agree with us by construction — it would accept the payloads we send because
+ * we wrote both sides, and the day Meta refused one we would find out in
+ * production. The emulator answers `POST /v{version}/{phone-number-id}/messages`
+ * with the Cloud API's own response shape and posts back the same signed
+ * `x-hub-signature-256` webhooks, so the `simulator` backend is THE SAME CODE
+ * as the official one with a different base URL. That is the thing being
+ * proved, and it is not something a mock can prove.
+ *
+ * It also has a clock we can move (`POST /_sim/clock`), which a replay
+ * finishing in seconds cannot otherwise have: a collection runs over days, and
+ * without moving the clock the 24-hour window never closes, so the one rule
+ * that decides whether a message may be sent at all is never exercised.
+ *
+ * WHAT THIS FILE IS: the `_sim/*` side only — the routes that belong to the
+ * emulator and have no counterpart at Meta. The sending and receiving are
+ * `WhatsAppCloudApi`, unchanged.
+ *
+ * The emulator is a separate process and is not a dependency of this workspace:
+ * it is a development tool nothing here imports. `scripts/whatsapp-emulator.mjs`
+ * fetches `@dyvit/whatsapp-simulator-cli` at a pinned version and runs it;
+ * `npm run whatsapp:emulator` is the command.
+ */
+import type { ConversationScript } from "@codespar/agent-core";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
+import { WhatsAppCloudApi, type CloudApiOptions } from "./cloud-api.js";
+
+export const EMULATOR_ENV = {
+  url: "WHATSAPP_SIM_URL",
+  appSecret: "WHATSAPP_SIM_APP_SECRET",
+  webhookPort: "WHATSAPP_SIM_WEBHOOK_PORT",
+  phoneNumberId: "WHATSAPP_SIM_PHONE_NUMBER_ID",
+} as const;
+
+export const EMULATOR_DEFAULTS = {
+  url: "http://127.0.0.1:4290",
+  /** Matches `--app-secret` in `npm run whatsapp:emulator`. A local development value, not a credential. */
+  appSecret: "dev",
+  webhookPort: 4399,
+  phoneNumberId: "900000000001",
+  apiVersion: "v22.0",
+} as const;
+
+export class EmulatorUnreachableError extends Error {
+  constructor(url: string, detail: string) {
+    super(
+      `the WhatsApp emulator is not answering at ${url} (${detail}).\n` +
+        `  Start it in another terminal:  npm run whatsapp:emulator\n` +
+        `  It is dyvit-wa-sim, from https://github.com/fabianocruz/whatsapp-simulator — MIT, run from npm at a pinned version, no Meta account and no credential.`,
+    );
+    this.name = "EmulatorUnreachableError";
+  }
+}
+
+/** The `_sim/*` routes: what the emulator has and Meta does not. */
+export class EmulatorDriver {
+  constructor(
+    private readonly url: string,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  private async call(path: string, init?: RequestInit): Promise<unknown> {
+    let response: Response;
+    try {
+      response = await this.fetchImpl(`${this.url}${path}`, { ...init, signal: AbortSignal.timeout(5000) });
+    } catch (err) {
+      throw new EmulatorUnreachableError(this.url, err instanceof Error ? err.message : String(err));
+    }
+    const text = await response.text();
+    if (!response.ok) throw new Error(`emulator answered ${response.status} to ${path}: ${text.slice(0, 200)}`);
+    return text ? JSON.parse(text) : {};
+  }
+
+  private post(path: string, body: unknown): Promise<unknown> {
+    return this.call(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  }
+
+  health(): Promise<unknown> {
+    return this.call("/health");
+  }
+
+  /** Pins the conversation clock, so a scripted run reads the same at 03:00 as at 15:00. */
+  pin(at: Date): Promise<unknown> {
+    return this.post("/_sim/clock", { now: at.toISOString() });
+  }
+
+  /** Moves the conversation clock forward. The only way to reach the far side of the 24-hour window. */
+  advanceHours(hours: number): Promise<unknown> {
+    return this.post("/_sim/clock", { advance_hours: hours });
+  }
+
+  /** The person writes, or taps a quick reply. The emulator answers with a signed inbound webhook to our receiver. */
+  inbound(options: { phoneNumberId: string; from: string; text: string; sentAt?: Date } | { phoneNumberId: string; from: string; reply: { id: string; title: string }; sentAt?: Date }): Promise<unknown> {
+    return this.post("/_sim/inbound", {
+      phone_number_id: options.phoneNumberId,
+      from: options.from,
+      ...("reply" in options
+        ? { type: "interactive", interactive: { type: "button_reply", button_reply: { id: options.reply.id, title: options.reply.title } } }
+        : { text: options.text }),
+      ...(options.sentAt ? { sent_at: options.sentAt.toISOString() } : {}),
+    });
+  }
+
+  /** Reports a delivery status for a message the business sent, as the provider would: `read`, or `failed` with a reason. */
+  status(options: { status: "read" | "failed"; messageId: string; reason?: string }): Promise<unknown> {
+    return this.post("/_sim/status", { status: options.status, message_id: options.messageId, ...(options.reason ? { reason: options.reason } : {}) });
+  }
+
+  /** The priced timeline, which is the emulator's own reason for existing. Read for the console, never asserted on. */
+  state(key: string): Promise<{ priced?: { total?: number; currency?: string } } | undefined> {
+    return this.call(`/_sim/state?key=${encodeURIComponent(key)}`).then(
+      (v) => v as { priced?: { total?: number; currency?: string } },
+      () => undefined,
+    );
+  }
+}
+
+export interface EmulatorBackendOptions extends CloudApiOptions {
+  driver: EmulatorDriver;
+  /** The person's turns. Absent means they are at the keyboard. */
+  script?: ConversationScript | undefined;
+  /** The instant the emulator's conversation clock is pinned to. */
+  pinAt?: Date | undefined;
+  /** Interactive only: reads the person's next line. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /** Where the console draws the conversation as it goes. */
+  render: (line: string) => void;
+}
+
+/**
+ * The `simulator` backend: `WhatsAppCloudApi` pointed at the emulator, plus the
+ * one thing the Cloud API has no equivalent for — making the person write.
+ *
+ * Every outbound message goes through the same `deliver` the Meta backend uses,
+ * and every inbound one arrives as a signed webhook at the same receiver, so
+ * nothing here is a shortcut around the adapter.
+ */
+export class WhatsAppEmulator implements ChannelBackend {
+  readonly name = "emulator";
+  readonly live = false;
+  private readonly api: WhatsAppCloudApi;
+  private turn = 0;
+  private closed = false;
+
+  constructor(private readonly options: EmulatorBackendOptions) {
+    const { driver: _driver, script: _script, pinAt: _pinAt, ask: _ask, render: _render, ...api } = options;
+    this.api = new WhatsAppCloudApi(api);
+  }
+
+  async open(): Promise<void> {
+    await this.api.open();
+    await this.options.driver.health();
+    if (this.options.pinAt) await this.options.driver.pin(this.options.pinAt);
+    this.options.render("");
+    this.options.render(`  ┌─ WhatsApp (dyvit-wa-sim, emulador local da Cloud API — sem rede externa, sem conta Meta)`);
+  }
+
+  async next(): Promise<InboundMessage | undefined> {
+    if (this.closed) return undefined;
+    const turn = await this.nextTurn();
+    if (turn === undefined) return undefined;
+    // The person writes (or taps) THROUGH the emulator: it mints the message id
+    // and posts the signed webhook our receiver verifies, so a scripted turn
+    // takes the same path a real one would.
+    const who = { phoneNumberId: this.options.config.phoneNumberId, from: this.options.conversation.contact };
+    await this.options.driver.inbound(typeof turn === "string" ? { ...who, text: turn } : { ...who, reply: turn });
+    return this.api.next();
+  }
+
+  onStatus(listener: (status: StatusUpdate) => void): void {
+    this.api.onStatus(listener);
+  }
+
+  private async nextTurn(): Promise<string | { id: string; title: string } | undefined> {
+    const script = this.options.script;
+    if (script) {
+      const turn = script.turns[this.turn];
+      if (!turn) return undefined;
+      this.turn += 1;
+      // The person's own pause, on the emulator's clock. A conversation that
+      // happens over days is what closes the 24-hour window.
+      if (turn.after_seconds > 0) await this.options.driver.advanceHours(turn.after_seconds / 3600);
+      return turn.reply ? { id: turn.reply.id, title: turn.reply.title ?? turn.reply.id } : turn.text;
+    }
+    return this.nextText();
+  }
+
+  private async nextText(): Promise<string | undefined> {
+    if (!this.options.ask) return undefined;
+    let answer: string;
+    try {
+      answer = await this.options.ask("  │ voce> ");
+    } catch {
+      return undefined;
+    }
+    const text = answer.trim();
+    if (!text) return this.nextText();
+    if (["sair", "exit", "quit"].includes(text.toLowerCase())) return undefined;
+    return text;
+  }
+
+  deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+    return this.api.deliver(to, body);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await this.api.close();
+    this.options.render("  └─ fim da conversa");
+  }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Decision 19a, the part a channel can carry: `attestation.evidence` on
+ * `POST /v1/consents/{token}/submit` (codespar-enterprise ent#1615).
+ *
+ * In the sandbox a mandate is born at the terminal with
+ * `attestation: { method: "in_person" }` — the titular is at the keyboard and
+ * the partner is the process. In production the act happens in a
+ * CONVERSATION, so the method is `partner_session` and the submit may carry
+ * what the partner OBSERVED of it. This builds that object.
+ *
+ * The API's rule, restated here because it is the whole point: a WhatsApp
+ * conversation hands the partner a message and a sender, not a socket. The
+ * channel's allowed keys are therefore `contact`, `message_id`, `session_id`
+ * and `provider_ts`, and an `ip`, a `user_agent`, a `device_id_hash` or a
+ * `geo` on this channel would have been inferred rather than observed. The
+ * API refuses them (400 `attestation_evidence_invalid`), and so does this,
+ * one layer earlier, because a value inferred inside a signed record reads as
+ * observed and is worse than an absent one.
+ *
+ * WHY THE EMULATOR CANNOT PRODUCE ONE. Everything here is a claim about what a
+ * provider observed. A conversation carried by an emulator on the developer's
+ * own machine was observed by nobody: its message id was minted locally, its
+ * timestamp came from a clock we move ourselves, and no phone was involved.
+ * Signing that as evidence would be a false declaration — the same one the
+ * API's own schema warns about for a partner that declares `other` for a
+ * WhatsApp act. So `evidenceFor` returns a REFUSAL for any backend that is not
+ * live, with the reason on it, and the caller either submits without evidence
+ * or does not submit at all. That is not a gap in the seam; it is the seam
+ * working.
+ *
+ * `live` is not a flag anyone sets: it is whether the base URL is Meta's host.
+ * A run cannot claim to be live by being configured to say so.
+ */
+import type { InboundMessage } from "../types.js";
+
+/** The keys the API's `whatsapp` channel accepts. Mirrored from `CONSENT_EVIDENCE_CHANNEL_KEYS`. */
+export const WHATSAPP_EVIDENCE_KEYS = ["contact", "message_id", "session_id", "provider_ts"] as const;
+
+/** Opaque provider ids: a `wamid.` carries `.`, `:`, `=` and `+`, and all four are allowed. */
+const OPAQUE_ID = /^[A-Za-z0-9_.:=+-]{1,120}$/;
+
+/**
+ * The evidence as the PARTNER sends it. The wire carries `contact` in the
+ * clear and the API hashes it into `contact_hash` under the org's own key —
+ * a partner cannot compute that hash, and a partner-computed one would match
+ * nothing.
+ */
+export interface WhatsAppConsentEvidence {
+  channel: "whatsapp";
+  contact?: string;
+  message_id?: string;
+  session_id?: string;
+  /** Unix seconds on the PROVIDER's clock, which is not the partner's. */
+  provider_ts?: number;
+}
+
+export interface ConsentAttestation {
+  method: "partner_session";
+  /** Unix seconds: when the PARTNER says the human authorized. */
+  asserted_at: number;
+  /** The partner's own record id. `^[A-Za-z0-9_-]{1,120}$` — no dots, so a `wamid` goes in `message_id`. */
+  reference?: string;
+  evidence: WhatsAppConsentEvidence;
+}
+
+export type EvidenceResult = { attestable: true; attestation: ConsentAttestation } | { attestable: false; reason: string };
+
+export interface EvidenceInput {
+  /** Whether the backend that carried the message talks to a real provider. */
+  live: boolean;
+  /** The message in which the person said yes. */
+  message: InboundMessage;
+  /** The partner's id for this conversation, when it has one. */
+  sessionId?: string | undefined;
+  /** The partner's clock, for `asserted_at`. */
+  now: () => Date;
+  reference?: string | undefined;
+}
+
+export function evidenceFor(input: EvidenceInput): EvidenceResult {
+  if (!input.live) {
+    return {
+      attestable: false,
+      reason:
+        "this act was observed by an emulator on this machine, and a simulated observation is not evidence: " +
+        "the message id was minted locally, the timestamp came from a clock we move ourselves, and no phone was involved",
+    };
+  }
+  if (!OPAQUE_ID.test(input.message.id)) return { attestable: false, reason: `the provider message id does not fit the API's opaque-id shape: ${input.message.id.slice(0, 24)}` };
+  if (!Number.isInteger(input.message.timestamp) || input.message.timestamp <= 0) return { attestable: false, reason: "the provider gave no usable timestamp for the message" };
+  if (input.sessionId !== undefined && !OPAQUE_ID.test(input.sessionId)) return { attestable: false, reason: "the session id does not fit the API's opaque-id shape" };
+  if (input.reference !== undefined && !/^[A-Za-z0-9_-]{1,120}$/.test(input.reference)) return { attestable: false, reason: "the attestation reference must be [A-Za-z0-9_-]{1,120}" };
+
+  return {
+    attestable: true,
+    attestation: {
+      method: "partner_session",
+      asserted_at: Math.floor(input.now().getTime() / 1000),
+      ...(input.reference !== undefined ? { reference: input.reference } : {}),
+      evidence: {
+        channel: "whatsapp",
+        contact: input.message.from,
+        message_id: input.message.id,
+        ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+        provider_ts: input.message.timestamp,
+      },
+    },
+  };
+}

package/templates/checkout-agent/packages/agent-runtime/src/channels/whatsapp/index.ts

@@ -0,0 +1,350 @@
+/**
+ * The WhatsApp channel: one adapter, two backends.
+ *
+ * Everything that decides what may be said lives HERE and not in a backend,
+ * which is what makes "the rules are code" true rather than aspirational.
+ * Picking the simulator or the official API changes who carries the bytes; it
+ * does not change the hours, the bound contact, the secrecy of the debt, the
+ * document rule or the session window. A test that tries to get around a rule
+ * by choosing a backend is in `test/whatsapp-rules.test.ts` and fails.
+ *
+ * It also keeps the two audiences apart. `send` reaches the person who owes.
+ * The operator's console and the approval question are wired to stderr by the
+ * caller and have no path to this object at all — not a check, a shape: there
+ * is no method here that an operator line could be handed to.
+ */
+import { declaredReplies, type ProofBundle, type QuickReply, type WhatsAppTemplate } from "@codespar/agent-core";
+import { checkOutbound, type HoursRule, type RuleContext } from "../rules.js";
+import type { Channel, ChannelBackend, ChannelLogLine, Conversation, DeliveryState, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
+import { maskContact } from "../contact.js";
+import { SessionWindow, type SessionState } from "./session.js";
+
+export interface WhatsAppChannelOptions {
+  backend: ChannelBackend;
+  conversation: Conversation;
+  now: () => Date;
+  hours?: HoursRule | undefined;
+  knownSubjects?: readonly string[] | undefined;
+  /** The run's bundle, so the conversation is part of the proof. */
+  bundle?: ProofBundle | undefined;
+  /** Templates the agent declares it uses, from `channels/whatsapp/templates.json`. Meta's approval of them is not knowable from here. */
+  templates?: readonly WhatsAppTemplate[] | undefined;
+  /**
+   * Where the window stood when an earlier run left this conversation. A run
+   * that JOINS a conversation — a poll looking at a charge agreed yesterday —
+   * has no inbound message of its own to open it from, and without this it
+   * would read every conversation as shut.
+   */
+  session?: SessionState | undefined;
+  /** The operator's console. Refusals are reported here, never to the conversation. */
+  say?: ((line: string) => void) | undefined;
+  /**
+   * Draws the conversation for whoever is watching the run. It is a VIEW of
+   * what went over the channel, written after the fact, and never a way to put
+   * something in front of the person — that is `send`, and it is the only one.
+   */
+  render?: ((line: string) => void) | undefined;
+  /**
+   * The provider reported that a message the agent sent was NOT delivered.
+   * Called with the status line, which names the outcome the message told
+   * when it told one — that outcome was not told, whatever the send answered.
+   */
+  onDeliveryFailed?: ((line: ChannelLogLine) => void) | undefined;
+  /** Lines an earlier run wrote for this conversation, so a status about a message it sent can be tied back to what that message was. */
+  priorLines?: ReadonlyArray<ChannelLogLine> | undefined;
+}
+
+export class WhatsAppChannel implements Channel {
+  readonly name = "whatsapp" as const;
+  readonly conversation: Conversation;
+  private readonly session: SessionWindow;
+  private readonly lines: ChannelLogLine[] = [];
+  private lastInbound: InboundMessage | undefined;
+  private readonly replies: Map<string, QuickReply>;
+  /** The latest state the provider reported per message id, this process. */
+  private readonly delivery = new Map<string, DeliveryState>();
+  /**
+   * Failures reported for a message not yet in the log. A provider can post
+   * the status before the send that minted the id has answered (the emulator
+   * does, synchronously); the failure is acted on once the message is logged
+   * and it is known what the message was.
+   */
+  private readonly earlyFailures = new Map<string, ChannelLogLine>();
+
+  constructor(private readonly options: WhatsAppChannelOptions) {
+    this.conversation = options.conversation;
+    this.session = new SessionWindow(options.templates ?? [], options.session);
+    this.replies = declaredReplies(options.templates ?? []);
+  }
+
+  get backend(): string {
+    return this.options.backend.name;
+  }
+
+  /** Whether the backend talks to a real provider. What the consent-evidence seam turns on. */
+  get live(): boolean {
+    return this.options.backend.live;
+  }
+
+  /** The message the person last sent, for the caller that needs to attest to an act. */
+  get lastInboundMessage(): InboundMessage | undefined {
+    return this.lastInbound;
+  }
+
+  /**
+   * Whether a free-form message may go out right now. A caller that has one
+   * thing to say and two ways to say it asks HERE which one the provider
+   * would carry — the alternative is composing a message, watching the
+   * channel refuse it, and calling that a decision.
+   */
+  get sessionOpen(): boolean {
+    return this.session.open(this.options.now());
+  }
+
+  /** Seconds of free-form left, for the console line that explains the choice. */
+  get sessionRemainingSeconds(): number {
+    return this.session.remainingSeconds(this.options.now());
+  }
+
+  /** The registry's fallback template, the one sent for an outcome the kit has no copy for. */
+  fallbackTemplate(): string | undefined {
+    return (this.options.templates ?? []).find((t) => t.fallback)?.name;
+  }
+
+  /** What the agent declared about a template it is about to send. The language is the registry's, never the sender's guess. */
+  declaredTemplate(name: string): WhatsAppTemplate | undefined {
+    return this.session.declared(name);
+  }
+
+  async open(): Promise<void> {
+    this.options.backend.onStatus?.((status) => this.observeStatus(status));
+    await this.options.backend.open();
+  }
+
+  /**
+   * The person's next turn. A typed message is the turn. A TAPPED quick reply
+   * is a turn only when its id is one a declared template offers, and then the
+   * turn is that reply's declared intent, never the button's title and never
+   * anything the model makes of it. A tap on an id nobody declared — or on a
+   * message this conversation did not send, when the provider names the
+   * message — is recorded, reported to the operator and skipped: a button the
+   * agent never offered has no meaning to hand on.
+   */
+  async next(): Promise<InboundMessage | undefined> {
+    for (;;) {
+      const message = await this.options.backend.next();
+      if (!message) return undefined;
+      // Any inbound, tap or text, reopens the 24-hour window: the person wrote.
+      this.lastInbound = message;
+      this.session.observeInbound(message.timestamp);
+      const base = {
+        at: this.options.now().toISOString(),
+        direction: "in" as const,
+        contact: maskContact(message.from),
+        message_id: message.id,
+        state: "delivered" as const,
+        // The provider's clock, which is the only one the 24-hour window is
+        // counted on. A later run reads the window back from here.
+        provider_timestamp: message.timestamp,
+      };
+      if (!message.reply) {
+        this.record({ ...base, kind: "text", text: message.text });
+        return message;
+      }
+      const tapped = { type: message.reply.type, id: message.reply.id, title: message.reply.title };
+      const declared = this.replies.get(message.reply.id);
+      const refusal = !declared
+        ? { rule: "reply_not_offered", detail: `the person tapped ${message.reply.id}, which no template this agent declares offers; it is not a turn` }
+        : message.reply.context_id && !this.offeredOn(message.reply.context_id, message.reply.id)
+          ? { rule: "reply_not_offered", detail: `the tap names message ${message.reply.context_id}, which this conversation did not send with ${message.reply.id}` }
+          : undefined;
+      if (refusal) {
+        this.record({ ...base, kind: "reply", reply: tapped, refused: refusal });
+        this.options.say?.(`  [whatsapp] toque ignorado (${refusal.rule}): ${refusal.detail}`);
+        continue;
+      }
+      this.record({ ...base, kind: "reply", reply: tapped, text: declared!.intent });
+      return { ...message, text: declared!.intent };
+    }
+  }
+
+  /** Whether the message the provider named is one this conversation sent carrying that reply. */
+  private offeredOn(messageId: string, replyId: string): boolean {
+    return [...(this.options.priorLines ?? []), ...this.lines].some((l) => l.direction === "out" && l.message_id === messageId && (l.offered ?? []).includes(replyId));
+  }
+
+  /**
+   * A status webhook. Recorded in the conversation; a `failed` is also the
+   * operator's business and, when the message told an outcome, the outcome's:
+   * the provider just said the person never got it. A `read` is recorded and
+   * nothing more — it says a device displayed the message, which is not
+   * consent, not acknowledgement of a debt or an order, and not a reply.
+   */
+  private observeStatus(status: StatusUpdate): void {
+    const sent = [...(this.options.priorLines ?? []), ...this.lines].find((l) => l.direction === "out" && l.message_id === status.message_id);
+    this.delivery.set(status.message_id, status.status);
+    const line: ChannelLogLine = {
+      at: this.options.now().toISOString(),
+      direction: "status",
+      contact: maskContact(this.conversation.contact),
+      kind: "status",
+      message_id: status.message_id,
+      state: status.status,
+      provider_timestamp: status.timestamp,
+      ...(sent?.about ? { about: sent.about } : {}),
+      ...(status.errors.length ? { errors: status.errors } : {}),
+    };
+    this.record(line);
+    if (status.status !== "failed") return;
+    if (!sent) {
+      this.earlyFailures.set(status.message_id, line);
+      return;
+    }
+    this.reportFailure(line);
+  }
+
+  private reportFailure(line: ChannelLogLine): void {
+    const status = { message_id: line.message_id, errors: line.errors ?? [] };
+    const codes = status.errors.map((e) => `${e.code ?? "?"}${e.details ? ` ${e.details}` : ""}`).join("; ") || "no error given";
+    this.options.say?.(
+      `  [operador] ENTREGA FALHOU da mensagem ${status.message_id} (${codes})${line.about ? ` — era o aviso de ${line.about.execution_id} (${line.about.state}): a pessoa NAO foi avisada` : ""}`,
+    );
+    this.options.onDeliveryFailed?.(line);
+  }
+
+  /** The latest status the provider reported for a message this process saw a status for. */
+  deliveryOf(messageId: string): DeliveryState | undefined {
+    return this.delivery.get(messageId);
+  }
+
+  /**
+   * Waits for status webhooks that may still be in flight. A provider reports
+   * a failure after the send answered, and a process that exits first never
+   * hears it; this is the short, bounded wait a caller that has just told an
+   * outcome gives the provider before it reports the outcome as told.
+   */
+  async settle(ms: number): Promise<void> {
+    if (ms > 0) await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async send(body: OutboundBody): Promise<SentMessage> {
+    const to = this.conversation.contact;
+    const ctx: RuleContext = {
+      conversation: this.conversation,
+      hours: this.options.hours,
+      now: this.options.now,
+      knownSubjects: this.options.knownSubjects,
+    };
+
+    // The house rules first: a message the law refuses is not a message the provider should ever see.
+    const refusal = checkOutbound(to, body, ctx) ?? this.providerRefusal(body);
+    if (refusal) {
+      const sent: SentMessage = { id: "", state: "failed", refused: refusal };
+      this.logOutbound(body, sent);
+      this.options.say?.(`  [whatsapp] recusado (${refusal.rule}): ${refusal.detail}`);
+      return sent;
+    }
+
+    // A template carries the quick replies its declaration offers, and only those.
+    const buttons = body.kind === "template" ? this.session.declared(body.template)?.buttons : undefined;
+    const outgoing: OutboundBody = body.kind === "template" && buttons?.length ? { ...body, buttons: buttons.map((b) => ({ id: b.id, title: b.title })) } : body;
+    const sent = await this.options.backend.deliver(to, outgoing);
+    if (sent.refused) this.options.say?.(`  [whatsapp] recusado pelo backend (${sent.refused.rule}): ${sent.refused.detail}`);
+    if (sent.refused?.rule === "session_window_closed") this.session.observeProviderShut();
+    this.logOutbound(outgoing, sent);
+    return sent;
+  }
+
+  say(text: string): Promise<SentMessage> {
+    return this.send({ kind: "text", text });
+  }
+
+  async close(): Promise<void> {
+    await this.options.backend.close();
+  }
+
+  /** Every message of this conversation, in order. */
+  log(): ReadonlyArray<ChannelLogLine> {
+    return this.lines;
+  }
+
+  private logOutbound(body: OutboundBody, sent: SentMessage): void {
+    const early = sent.id ? this.earlyFailures.get(sent.id) : undefined;
+    if (early) {
+      this.earlyFailures.delete(sent.id);
+      const about = (body.kind === "text" || body.kind === "template") && body.about ? body.about : undefined;
+      queueMicrotask(() => this.reportFailure({ ...early, ...(about ? { about } : {}) }));
+    }
+    this.record({
+      at: this.options.now().toISOString(),
+      direction: "out",
+      contact: maskContact(this.conversation.contact),
+      kind: body.kind,
+      message_id: sent.id,
+      state: sent.state,
+      ...(textOf(body) !== undefined ? { text: textOf(body)! } : {}),
+      ...(sent.refused ? { refused: sent.refused } : {}),
+      ...((body.kind === "text" || body.kind === "template") && body.about ? { about: body.about } : {}),
+      ...(body.kind === "template" && body.buttons?.length ? { offered: body.buttons.map((b) => b.id) } : {}),
+    });
+  }
+
+  /**
+   * WhatsApp's own rule, enforced on both backends: outside the 24 hours
+   * after the person's last message only an approved template may go out.
+   * The simulator obeys it because a rule that only bites in production is a
+   * rule you meet in production.
+   */
+  private providerRefusal(body: OutboundBody): { rule: string; detail: string } | undefined {
+    const open = this.session.open(this.options.now());
+    if (body.kind === "template") return this.session.refuse(body);
+    if (!open) {
+      return {
+        rule: "session_window_closed",
+        detail: "more than 24h since the person's last message: WhatsApp only carries an approved template now, not a free-form message",
+      };
+    }
+    return undefined;
+  }
+
+  private record(line: ChannelLogLine): void {
+    this.lines.push(line);
+    this.options.bundle?.channel({ ...line, channel: "whatsapp", backend: this.backend });
+    this.options.render?.(`  │ ${draw(line)}`);
+  }
+}
+
+/** One console line for one message. The refusals are visible: a message nobody got is part of the conversation's story. */
+function draw(line: ChannelLogLine): string {
+  if (line.direction === "status") return `(status ${line.message_id}: ${line.state}${line.errors?.length ? ` ${line.errors.map((e) => e.code).join(",")}` : ""})`;
+  if (line.kind === "reply") return `${line.contact}: [toque: ${line.reply?.title ?? "?"}]${line.refused ? ` (ignorado: ${line.refused.rule})` : ` -> ${line.text ?? ""}`}`;
+  const who = line.direction === "in" ? `${line.contact}:` : "loja:";
+  const what =
+    line.kind === "instrument"
+      ? `[copia e cola] ${line.text ?? ""}`
+      : line.kind === "media"
+        ? "[imagem: QR Pix]"
+        : line.kind === "template"
+          ? line.text ?? "[template]"
+          : line.text ?? "";
+  return line.refused ? `${who} (nao enviada: ${line.refused.rule}) ${what}` : `${who} ${what}`;
+}
+
+function textOf(body: OutboundBody): string | undefined {
+  switch (body.kind) {
+    case "text":
+      return body.text;
+    case "instrument":
+      return body.value;
+    case "media":
+      return body.caption;
+    case "template":
+      return `[template ${body.template}] ${body.variables.join(" | ")}${body.buttons?.length ? ` [${body.buttons.map((b) => b.title).join("] [")}]` : ""}`;
+  }
+}
+
+export * from "../contact.js";
+export * from "./cloud-api.js";
+export * from "./emulator.js";
+export * from "./evidence.js";
+export * from "./session.js";