@codespar/cli 0.16.0 → 0.18.0

package/templates/collections-agent/packages/agent-runtime/src/channels/whatsapp/cloud-api.ts

@@ -24,7 +24,7 @@
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { createServer, type Server } from "node:http";
-import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../types.js";
+import type { ChannelBackend, DeliveryState, InboundMessage, InboundReply, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
 
 export interface CloudApiConfig {
   /**
@@ -140,23 +140,36 @@ interface CloudApiEnvelope {
       value?: {
         messaging_product?: string;
         metadata?: { phone_number_id?: string };
-        messages?: Array<{ id?: string; from?: string; timestamp?: string; type?: string; text?: { body?: string } }>;
-        statuses?: Array<{ id?: string; status?: string }>;
+        messages?: Array<{
+          id?: string;
+          from?: string;
+          timestamp?: string;
+          type?: string;
+          text?: { body?: string };
+          interactive?: { type?: string; button_reply?: { id?: string; title?: string }; list_reply?: { id?: string; title?: string } };
+          button?: { payload?: string; text?: string };
+          context?: { id?: string };
+        }>;
+        statuses?: Array<{ id?: string; status?: string; timestamp?: string; errors?: Array<{ code?: number; title?: string; message?: string; error_data?: { details?: string } }> }>;
       };
     }>;
   }>;
 }
 
 /**
- * The text messages inside one delivery. A delivery carries several entries,
- * each with several changes, each with several messages — and also status
- * updates, which are not messages. Anything that is not a `text` is dropped
- * with its id named: this channel reads words, and an image or a location the
- * agent cannot read must not be silently treated as an empty message.
+ * What one delivery carries. A delivery holds several entries, each with
+ * several changes, each with messages and with STATUS updates about messages
+ * we sent. A message is read when it is text, or a tapped quick reply (an
+ * interactive `button_reply` / `list_reply`, or a template's `button`), which
+ * keeps its id — the channel decides whether that id means anything. Anything
+ * else (an image, a location) is dropped with its id named: this channel
+ * reads words and taps, and an unreadable message must not become an empty
+ * turn.
  */
-export function parseInbound(payload: unknown): { messages: InboundMessage[]; ignored: Array<{ id: string; type: string }> } {
+export function parseInbound(payload: unknown): { messages: InboundMessage[]; statuses: StatusUpdate[]; ignored: Array<{ id: string; type: string }> } {
   const envelope = payload as CloudApiEnvelope;
   const messages: InboundMessage[] = [];
+  const statuses: StatusUpdate[] = [];
   const ignored: Array<{ id: string; type: string }> = [];
   for (const entry of envelope.entry ?? []) {
     for (const change of entry.changes ?? []) {
@@ -164,15 +177,51 @@ export function parseInbound(payload: unknown): { messages: InboundMessage[]; ig
         const id = message.id;
         const from = message.from;
         if (!id || !from) continue;
+        const base = { id, from: from.startsWith("+") ? from : `+${from}`, timestamp: Number(message.timestamp ?? 0) };
+        const reply = replyOf(message);
+        if (reply) {
+          messages.push({ ...base, text: reply.title, reply: { ...reply, ...(message.context?.id ? { context_id: message.context.id } : {}) } });
+          continue;
+        }
         if (message.type !== "text" || !message.text?.body) {
-          ignored.push({ id, type: message.type ?? "unknown" });
+          ignored.push({ id, type: message.type === "interactive" ? `interactive:${message.interactive?.type ?? "unknown"}` : message.type ?? "unknown" });
           continue;
         }
-        messages.push({ id, from: from.startsWith("+") ? from : `+${from}`, text: message.text.body, timestamp: Number(message.timestamp ?? 0) });
+        messages.push({ ...base, text: message.text.body });
+      }
+      for (const status of change.value?.statuses ?? []) {
+        if (!status.id || !isDeliveryState(status.status)) continue;
+        statuses.push({
+          message_id: status.id,
+          status: status.status,
+          timestamp: Number(status.timestamp ?? 0),
+          errors: (status.errors ?? []).map((e) => ({
+            ...(typeof e.code === "number" ? { code: e.code } : {}),
+            ...(e.title ?? e.message ? { title: e.title ?? e.message } : {}),
+            ...(e.error_data?.details ? { details: e.error_data.details } : {}),
+          })),
+        });
       }
     }
   }
-  return { messages, ignored };
+  return { messages, statuses, ignored };
+}
+
+type CloudMessage = NonNullable<NonNullable<NonNullable<NonNullable<CloudApiEnvelope["entry"]>[number]["changes"]>[number]["value"]>["messages"]>[number];
+
+function replyOf(message: CloudMessage): Omit<InboundReply, "context_id"> | undefined {
+  if (message.type === "interactive") {
+    const kind = message.interactive?.type;
+    const picked = kind === "button_reply" ? message.interactive?.button_reply : kind === "list_reply" ? message.interactive?.list_reply : undefined;
+    if ((kind === "button_reply" || kind === "list_reply") && picked?.id) return { type: kind, id: picked.id, title: picked.title ?? picked.id };
+    return undefined;
+  }
+  if (message.type === "button" && message.button?.payload) return { type: "button", id: message.button.payload, title: message.button.text ?? message.button.payload };
+  return undefined;
+}
+
+function isDeliveryState(value: unknown): value is DeliveryState {
+  return value === "sent" || value === "delivered" || value === "read" || value === "failed";
 }
 
 export interface SendRequest {
@@ -200,10 +249,6 @@ export function buildSendRequest(config: CloudApiConfig, to: string, body: Outbo
     method: "POST" as const,
     headers: { authorization: `Bearer ${config.accessToken}`, "content-type": "application/json" },
   };
-  // `to` loses its `+`: the Cloud API documents the number in international
-  // format without one, and the emulator keys its conversation on the literal
-  // string, so a `+` here and none on the inbound side splits one person into
-  // two conversations (measured; docs/OPEN_QUESTIONS.md §46c).
   const recipient = { messaging_product: "whatsapp", recipient_type: "individual", to: toGraphNumber(to) };
   switch (body.kind) {
     case "text":
@@ -219,7 +264,7 @@ export function buildSendRequest(config: CloudApiConfig, to: string, body: Outbo
           template: {
             name: body.template,
             language: { code: body.language },
-            ...(body.variables.length ? { components: [{ type: "body", parameters: body.variables.map((text) => ({ type: "text", text })) }] } : {}),
+            ...templateComponents(body),
           },
         }),
       };
@@ -228,6 +273,49 @@ export function buildSendRequest(config: CloudApiConfig, to: string, body: Outbo
   }
 }
 
+/**
+ * A template's parameters as Meta takes them: the body's variables, and one
+ * `quick_reply` button component per declared reply, whose `payload` is the
+ * reply id — what comes back as `button.payload` when the person taps it.
+ */
+function templateComponents(body: Extract<OutboundBody, { kind: "template" }>): { components?: unknown[] } {
+  const components: unknown[] = [];
+  if (body.variables.length) components.push({ type: "body", parameters: body.variables.map((text) => ({ type: "text", text })) });
+  for (const [index, button] of (body.buttons ?? []).entries()) components.push({ type: "button", sub_type: "quick_reply", index: String(index), parameters: [{ type: "payload", payload: button.id }] });
+  return components.length ? { components } : {};
+}
+
+/** Meta's error for a free-form message outside the 24 hours after the person's last one. */
+export const WINDOW_CLOSED_ERROR = 131047;
+
+/**
+ * What a non-2xx from `/messages` means, read from Meta's error body.
+ *
+ * One code gets its own rule: 131047 is the provider saying the 24-hour
+ * window is shut, which is the SAME rule the channel enforces before a send
+ * and is answered the same way — with a template. It reaches here only when
+ * the two clocks disagree (ours read the window open, the provider's read it
+ * shut), which at the boundary is a race and not a bug, so a caller has to be
+ * able to tell it from a refusal it cannot do anything about.
+ */
+export function providerRefusal(status: number, body: string): { rule: string; detail: string } {
+  let error: { code?: unknown; message?: unknown; error_data?: { details?: unknown } } | undefined;
+  try {
+    error = (JSON.parse(body) as { error?: typeof error }).error;
+  } catch {
+    /* an error without Meta's envelope: the status is all there is */
+  }
+  const details = typeof error?.error_data?.details === "string" ? error.error_data.details : undefined;
+  if (error?.code === WINDOW_CLOSED_ERROR) {
+    return {
+      rule: "session_window_closed",
+      detail: `the provider refused the free-form message (${status}/${WINDOW_CLOSED_ERROR}): its 24h window is shut${details ? ` — ${details}` : ""}`,
+    };
+  }
+  const code = typeof error?.code === "number" ? `/${error.code}` : "";
+  return { rule: "provider_refused", detail: `${status}${code} from the Cloud API${details ? ` — ${details}` : ""}` };
+}
+
 /* ── the impure half: one fetch over a request the above built ── */
 
 /** `+5511987654321` -> `5511987654321`, the only form the Graph API takes. */
@@ -249,7 +337,10 @@ export class WhatsAppCloudApi implements ChannelBackend {
   readonly live: boolean;
   private server: Server | undefined;
   private readonly queue: InboundMessage[] = [];
+  /** Message ids already handed on. Meta delivers at-least-once, so the same message can arrive twice. */
+  private readonly seen = new Set<string>();
   private waiting: ((m: InboundMessage | undefined) => void) | undefined;
+  private statusListener: ((status: StatusUpdate) => void) | undefined;
   private closed = false;
 
   constructor(private readonly options: CloudApiOptions) {
@@ -287,15 +378,16 @@ export class WhatsAppCloudApi implements ChannelBackend {
           res.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify({ error: "bad_signature" }));
           return;
         }
-        let parsed: { messages: InboundMessage[]; ignored: Array<{ id: string; type: string }> };
+        let parsed: ReturnType<typeof parseInbound>;
         try {
           parsed = parseInbound(JSON.parse(raw));
         } catch {
           res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: "invalid_json" }));
           return;
         }
-        for (const ignored of parsed.ignored) say(`[whatsapp] ignored ${ignored.type} message ${ignored.id}: this channel reads text`);
+        for (const ignored of parsed.ignored) say(`[whatsapp] ignored ${ignored.type} message ${ignored.id}: this channel reads text and taps`);
         for (const message of parsed.messages) this.push(message);
+        for (const status of parsed.statuses) this.statusListener?.(status);
         // Always 200 once read: Meta retries on anything else, and a duplicate is not an error.
         res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ received: parsed.messages.length }));
       });
@@ -309,6 +401,13 @@ export class WhatsAppCloudApi implements ChannelBackend {
   }
 
   private push(message: InboundMessage): void {
+    // A redelivery is the same message, not a second turn: answering it twice
+    // would put two replies in front of the person for one thing they said.
+    if (this.seen.has(message.id)) {
+      this.options.say(`[whatsapp] duplicate delivery of ${message.id} dropped`);
+      return;
+    }
+    this.seen.add(message.id);
     if (this.waiting) {
       const resolve = this.waiting;
       this.waiting = undefined;
@@ -318,6 +417,10 @@ export class WhatsAppCloudApi implements ChannelBackend {
     this.queue.push(message);
   }
 
+  onStatus(listener: (status: StatusUpdate) => void): void {
+    this.statusListener = listener;
+  }
+
   async next(): Promise<InboundMessage | undefined> {
     if (this.closed) return undefined;
     const queued = this.queue.shift();
@@ -335,9 +438,7 @@ export class WhatsAppCloudApi implements ChannelBackend {
     const doFetch = this.options.fetchImpl ?? fetch;
     const response = await doFetch(request.url, { method: request.method, headers: request.headers, body: request.body });
     const text = await response.text();
-    if (!response.ok) {
-      return { id: "", state: "failed", refused: { rule: "provider_refused", detail: `${response.status} from the Cloud API` } };
-    }
+    if (!response.ok) return { id: "", state: "failed", refused: providerRefusal(response.status, text) };
     let id = "";
     try {
       id = String((JSON.parse(text) as { messages?: Array<{ id?: string }> }).messages?.[0]?.id ?? "");

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

@@ -26,8 +26,8 @@
  * `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";
+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",
@@ -93,18 +93,23 @@ export class EmulatorDriver {
     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> {
+  /** 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,
-      // 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,
+      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(
@@ -156,20 +161,21 @@ export class WhatsAppEmulator implements ChannelBackend {
 
   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,
-    });
+    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();
   }
 
-  private async nextText(): Promise<string | undefined> {
+  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];
@@ -178,8 +184,12 @@ export class WhatsAppEmulator implements ChannelBackend {
       // 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;
+      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 {

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

@@ -13,9 +13,9 @@
  * 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 { 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, InboundMessage, OutboundBody, SentMessage } from "../types.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";
 
@@ -44,6 +44,14 @@ export interface WhatsAppChannelOptions {
    * 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 {
@@ -52,10 +60,21 @@ export class WhatsAppChannel implements Channel {
   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 {
@@ -87,33 +106,125 @@ export class WhatsAppChannel implements Channel {
     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> {
-    const message = await this.options.backend.next();
-    if (!message) return undefined;
-    this.lastInbound = message;
-    this.session.observeInbound(message.timestamp);
-    this.record({
+    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: "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;
+      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> {
@@ -134,9 +245,13 @@ export class WhatsAppChannel implements Channel {
       return sent;
     }
 
-    const sent = await this.options.backend.deliver(to, body);
+    // 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}`);
-    this.logOutbound(body, sent);
+    if (sent.refused?.rule === "session_window_closed") this.session.observeProviderShut();
+    this.logOutbound(outgoing, sent);
     return sent;
   }
 
@@ -154,6 +269,12 @@ export class WhatsAppChannel implements Channel {
   }
 
   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",
@@ -163,6 +284,8 @@ export class WhatsAppChannel implements Channel {
       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) } : {}),
     });
   }
 
@@ -193,6 +316,8 @@ export class WhatsAppChannel implements Channel {
 
 /** 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"
@@ -214,7 +339,7 @@ function textOf(body: OutboundBody): string | undefined {
     case "media":
       return body.caption;
     case "template":
-      return `[template ${body.template}] ${body.variables.join(" | ")}`;
+      return `[template ${body.template}] ${body.variables.join(" | ")}${body.buttons?.length ? ` [${body.buttons.map((b) => b.title).join("] [")}]` : ""}`;
   }
 }
 

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

@@ -15,9 +15,9 @@ 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 type { ChannelBackend, ChannelLogLine, Conversation } from "../types.js";
 import { WhatsAppChannel } from "./index.js";
-import { toGraphNumber, WhatsAppCloudApi, loadCloudApiConfig, type CloudApiConfig } from "./cloud-api.js";
+import { WhatsAppCloudApi, loadCloudApiConfig, type CloudApiConfig } from "./cloud-api.js";
 import { EmulatorDriver, EMULATOR_DEFAULTS, EMULATOR_ENV, WhatsAppEmulator } from "./emulator.js";
 import type { SessionState } from "./session.js";
 
@@ -52,6 +52,41 @@ export interface OpenWhatsAppOptions {
   session?: SessionState | undefined;
   /** Draws the conversation on the operator's console. */
   render?: ((line: string) => void) | undefined;
+  /** What earlier runs wrote for this conversation: a status about one of their messages is tied back to it. */
+  priorLines?: ReadonlyArray<ChannelLogLine> | undefined;
+}
+
+/**
+ * How long a command that has just told an outcome waits for status webhooks
+ * before it reports the outcome as told. A provider reports a failed delivery
+ * AFTER the send answered, and a process that has exited hears nothing; this
+ * bounds the wait. `WHATSAPP_STATUS_GRACE_MS` overrides it (0 turns it off).
+ */
+export function statusGraceMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env["WHATSAPP_STATUS_GRACE_MS"]);
+  return Number.isFinite(raw) && raw >= 0 && env["WHATSAPP_STATUS_GRACE_MS"]?.trim() ? raw : 1000;
+}
+
+/** The cursor that says an outcome's message came back `failed`, so a later poll reports it as not told rather than as told. */
+export function undeliveredCursor(executionId: string, state: string): string {
+  return `undelivered:${executionId}:${state}`;
+}
+
+/**
+ * A `failed` status is an event in the proof bundle, always. When the message
+ * told an outcome it is `message.debtor.failed`, and the cursor above is taken:
+ * the cursor that says the person was told (`markTold`) stays held — a failed
+ * delivery is not retried by itself, because the usual cause (not a WhatsApp
+ * number, blocked) fails again — but nothing reports that outcome as told.
+ */
+export function recordDeliveryFailure(s: Setup, line: ChannelLogLine): void {
+  const payload = { message_id: line.message_id, errors: line.errors ?? [], channel: "whatsapp" };
+  if (!line.about) {
+    s.engine.note("message.failed", null, payload);
+    return;
+  }
+  s.store.setCursor(undeliveredCursor(line.about.execution_id, line.about.state), JSON.stringify(payload));
+  s.engine.note("message.debtor.failed", line.about.execution_id, { ...payload, state: line.about.state });
 }
 
 export interface OpenedWhatsApp {
@@ -102,7 +137,7 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
       webhookPort: Number(env[EMULATOR_ENV.webhookPort]?.trim() || EMULATOR_DEFAULTS.webhookPort),
     };
     driver = new EmulatorDriver(url);
-    sessionKey = `${config.phoneNumberId}:${toGraphNumber(options.conversation.contact)}`;
+    sessionKey = `${config.phoneNumberId}:${options.conversation.contact}`;
     backend = new WhatsAppEmulator({
       config,
       conversation: { contact: options.conversation.contact },
@@ -129,6 +164,8 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
     say,
     render: options.render ?? say,
     ...(options.session ? { session: options.session } : {}),
+    ...(options.priorLines ? { priorLines: options.priorLines } : {}),
+    onDeliveryFailed: (line) => recordDeliveryFailure(s, line),
   });
 
   return { channel, ...(driver ? { driver } : {}), ...(sessionKey ? { sessionKey } : {}) };