@codespar/cli 0.14.1 → 0.17.0

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

@@ -0,0 +1,206 @@
+/**
+ * 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 } from "../types.js";
+import { toGraphNumber, 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. The emulator answers with a signed inbound webhook to our receiver. */
+  inbound(options: { phoneNumberId: string; from: string; text: string; sentAt?: Date }): Promise<unknown> {
+    return this.post("/_sim/inbound", {
+      phone_number_id: options.phoneNumberId,
+      // Without the `+`, matching what `deliver` sends as `to`: the emulator keys
+      // its conversation on the literal string, so the two forms are two people.
+      from: toGraphNumber(options.from),
+      text: options.text,
+      ...(options.sentAt ? { sent_at: options.sentAt.toISOString() } : {}),
+    });
+  }
+
+  /** 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 text = await this.nextText();
+    if (text === undefined) return undefined;
+    // The person writes 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.
+    await this.options.driver.inbound({
+      phoneNumberId: this.options.config.phoneNumberId,
+      from: this.options.conversation.contact,
+      text,
+    });
+    return this.api.next();
+  }
+
+  private async nextText(): Promise<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.text;
+    }
+    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/supplier-payments-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/supplier-payments-agent/packages/agent-runtime/src/channels/whatsapp/index.ts

@@ -0,0 +1,225 @@
+/**
+ * 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 type { ProofBundle, WhatsAppTemplate } from "@codespar/agent-core";
+import { checkOutbound, type HoursRule, type RuleContext } from "../rules.js";
+import type { Channel, ChannelBackend, ChannelLogLine, Conversation, InboundMessage, OutboundBody, SentMessage } 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;
+}
+
+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;
+
+  constructor(private readonly options: WhatsAppChannelOptions) {
+    this.conversation = options.conversation;
+    this.session = new SessionWindow(options.templates ?? [], options.session);
+  }
+
+  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());
+  }
+
+  /** 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> {
+    await this.options.backend.open();
+  }
+
+  async next(): Promise<InboundMessage | undefined> {
+    const message = await this.options.backend.next();
+    if (!message) return undefined;
+    this.lastInbound = message;
+    this.session.observeInbound(message.timestamp);
+    this.record({
+      at: this.options.now().toISOString(),
+      direction: "in",
+      contact: maskContact(message.from),
+      kind: "text",
+      message_id: message.id,
+      state: "delivered",
+      text: message.text,
+      // 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,
+    });
+    return message;
+  }
+
+  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;
+    }
+
+    const sent = await this.options.backend.deliver(to, body);
+    if (sent.refused) this.options.say?.(`  [whatsapp] recusado pelo backend (${sent.refused.rule}): ${sent.refused.detail}`);
+    this.logOutbound(body, 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 {
+    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 } : {}),
+    });
+  }
+
+  /**
+   * 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 {
+  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(" | ")}`;
+  }
+}
+
+export * from "../contact.js";
+export * from "./cloud-api.js";
+export * from "./emulator.js";
+export * from "./evidence.js";
+export * from "./session.js";

package/templates/supplier-payments-agent/packages/agent-runtime/src/channels/whatsapp/open.ts

@@ -0,0 +1,143 @@
+/**
+ * Opening the WhatsApp channel: wiring, and only wiring.
+ *
+ * It lives apart from the command that starts a conversation because a second
+ * command now JOINS one — `codespar-agent poll --channel whatsapp`, which
+ * comes back to a conversation the run that opened it has long since ended.
+ * Two commands wiring the same channel by hand is how a rule ends up enforced
+ * on one path and not the other, and the whole claim of `channels/` is that
+ * the rules are above the backend. So both go through here.
+ *
+ * The decisions are all elsewhere: the rules in `channels/rules.ts`, the
+ * session window in `session.ts`, the gates in `terminal.ts`.
+ */
+import type { ConversationScript, ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "../../agent.js";
+import type { Setup } from "../../setup.js";
+import { knownSubjects, loadTemplates } from "../index.js";
+import type { ChannelBackend, Conversation } from "../types.js";
+import { WhatsAppChannel } from "./index.js";
+import { toGraphNumber, WhatsAppCloudApi, loadCloudApiConfig, type CloudApiConfig } from "./cloud-api.js";
+import { EmulatorDriver, EMULATOR_DEFAULTS, EMULATOR_ENV, WhatsAppEmulator } from "./emulator.js";
+import type { SessionState } from "./session.js";
+
+export type WhatsAppBackendName = "simulator" | "cloud-api";
+
+export interface OpenWhatsAppOptions {
+  agent: Agent;
+  setup: Setup;
+  conversation: Conversation;
+  backend: WhatsAppBackendName;
+  now: () => Date;
+  say: (line: string) => void;
+  /**
+   * Where the conversation is recorded. Normally the run's own bundle; a poll
+   * hands the bundle of the run it is continuing, because a conversation is
+   * one record and the message that closes it belongs with the ones that
+   * opened it.
+   */
+  bundle: ProofBundle;
+  /** The person's turns, when a script drives them. Absent and with no `ask`, nobody writes. */
+  script?: ConversationScript | undefined;
+  /** Interactive only: reads the person's next line. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /**
+   * Pins the emulator's CONVERSATION clock. A run that starts a conversation
+   * pins it; a run that joins one must not, because rewinding the provider's
+   * clock would reopen a window that really is shut. The agent's own notion of
+   * now is `now` above and is a different thing (#16).
+   */
+  pinAt?: Date | undefined;
+  /** Where the session window stood when an earlier run left this conversation. */
+  session?: SessionState | undefined;
+  /** Draws the conversation on the operator's console. */
+  render?: ((line: string) => void) | undefined;
+}
+
+export interface OpenedWhatsApp {
+  channel: WhatsAppChannel;
+  /** The `_sim/*` side, when the backend is the emulator. Absent against Meta. */
+  driver?: EmulatorDriver;
+  /** How the emulator keys this conversation, for the priced timeline. */
+  sessionKey?: string;
+}
+
+/**
+ * Builds the channel, or explains what is missing. Nothing is opened here:
+ * the caller opens it, because an emulator that is not running has to be
+ * reported differently depending on how far the command already got.
+ */
+export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | { refusal: string[] } {
+  const { agent, setup: s, say } = options;
+  let backend: ChannelBackend;
+  let driver: EmulatorDriver | undefined;
+  let sessionKey: string | undefined;
+
+  if (options.backend === "cloud-api") {
+    const { config, missing } = loadCloudApiConfig(process.env);
+    if (!config) {
+      return {
+        refusal: [
+          `the cloud-api backend needs credentials this repo ships none of: ${missing.join(", ")}.`,
+          `They live in the agent's .env (commented out in .env.example) and belong to a Meta Business account. The emulator needs none: drop --backend cloud-api.`,
+        ],
+      };
+    }
+    say("[whatsapp] cloud-api backend: this repo has never run one against Meta. The shapes are written from the published documentation; the first live run is yours.");
+    backend = new WhatsAppCloudApi({ config, conversation: { contact: options.conversation.contact }, say });
+  } else {
+    // The SAME backend, pointed somewhere else. What the emulator adds is the
+    // `_sim/*` side: making the person write, and moving the conversation clock.
+    const env = process.env;
+    const url = env[EMULATOR_ENV.url]?.trim() || EMULATOR_DEFAULTS.url;
+    const config: CloudApiConfig = {
+      baseUrl: url,
+      phoneNumberId: env[EMULATOR_ENV.phoneNumberId]?.trim() || EMULATOR_DEFAULTS.phoneNumberId,
+      // Not credentials: the emulator has no auth, and these are the values
+      // `npm run whatsapp:emulator` starts it with.
+      accessToken: "emulator",
+      verifyToken: "emulator",
+      appSecret: env[EMULATOR_ENV.appSecret]?.trim() || EMULATOR_DEFAULTS.appSecret,
+      apiVersion: EMULATOR_DEFAULTS.apiVersion,
+      webhookPort: Number(env[EMULATOR_ENV.webhookPort]?.trim() || EMULATOR_DEFAULTS.webhookPort),
+    };
+    driver = new EmulatorDriver(url);
+    sessionKey = `${config.phoneNumberId}:${toGraphNumber(options.conversation.contact)}`;
+    backend = new WhatsAppEmulator({
+      config,
+      conversation: { contact: options.conversation.contact },
+      driver,
+      say,
+      render: options.render ?? say,
+      ...(options.script ? { script: options.script } : {}),
+      ...(options.ask ? { ask: options.ask } : {}),
+      ...(options.pinAt ? { pinAt: options.pinAt } : {}),
+    });
+  }
+
+  // The hours are the agent's, from `guardrails.envelope.collection_hours`. An agent that declares none gets no hours rule, which is correct: not every conversation is a collection.
+  const window = typeof s.guardrails.envelope?.["collection_hours"] === "string" ? (s.guardrails.envelope["collection_hours"] as string) : undefined;
+
+  const channel = new WhatsAppChannel({
+    backend,
+    conversation: options.conversation,
+    now: options.now,
+    ...(window ? { hours: { window, timezone: s.guardrails.timezone } } : {}),
+    knownSubjects: knownSubjects(agent),
+    templates: loadTemplates(agent),
+    bundle: options.bundle,
+    say,
+    render: options.render ?? say,
+    ...(options.session ? { session: options.session } : {}),
+  });
+
+  return { channel, ...(driver ? { driver } : {}), ...(sessionKey ? { sessionKey } : {}) };
+}
+
+/** The priced timeline the emulator computed: read for the console, never asserted on. */
+export async function simulatedCost(driver: EmulatorDriver | undefined, sessionKey: string | undefined): Promise<{ total: number; currency: string } | undefined> {
+  if (!driver || !sessionKey) return undefined;
+  const state = (await driver.state(sessionKey).catch(() => undefined)) as { priced?: { total?: number; currency?: string } } | undefined;
+  if (typeof state?.priced?.total !== "number") return undefined;
+  return { total: state.priced.total, currency: state.priced.currency ?? "BRL" };
+}