@codespar/cli 0.17.0 → 0.18.0

package/templates/supplier-payments-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/supplier-payments-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 } : {}) };

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

@@ -20,6 +20,7 @@ import { handleExecution, type TerminalOptions } from "../../terminal.js";
 import type { Setup } from "../../setup.js";
 import type { OutboundBody } from "../types.js";
 import { instrumentBodies } from "./present.js";
+import { statusGraceMs } from "./open.js";
 import type { WhatsAppChannel } from "./index.js";
 
 export interface ConverseOptions {
@@ -63,6 +64,7 @@ class Outbox {
 export async function converse(options: ConverseOptions): Promise<ConverseResult> {
   const { setup: s, channel, approver, say } = options;
   const outbox = new Outbox(channel);
+  let toldOutcome = false;
   const replies: string[] = [];
   const toolCalls: Array<{ name: string; refused: boolean }> = [];
   let turns = 0;
@@ -77,7 +79,10 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
     setup: s,
     approver,
     say,
-    tell: (line: string) => outbox.push({ kind: "text", text: line }),
+    tell: (line: string, about?: Execution) => {
+      if (about) toldOutcome = true;
+      outbox.push({ kind: "text", text: line, ...(about ? { about: { execution_id: about.id, state: about.state } } : {}) });
+    },
     presentInstrument,
     ...(options.decision ? { decision: options.decision } : {}),
     ...(options.ask ? { ask: options.ask } : {}),
@@ -105,6 +110,8 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
       replies.push(result.reply);
     }
     await outbox.drain();
+    // An outcome told in this run may still come back failed; give the provider its bounded moment before the receiver closes.
+    if (toldOutcome) await channel.settle(statusGraceMs());
   } finally {
     await channel.close();
   }

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

@@ -33,6 +33,8 @@ export type TemplateRefusal = { rule: string; detail: string } | undefined;
 export class SessionWindow {
   private readonly templates: Map<string, WhatsAppTemplate>;
   private lastInboundAt: number | undefined;
+  /** The provider said the window is shut (131047) after ours read it open. Holds until the person writes again. */
+  private shutByProvider = false;
 
   constructor(templates: readonly WhatsAppTemplate[], initial?: SessionState) {
     this.templates = new Map(templates.map((t) => [t.name, t]));
@@ -40,12 +42,24 @@ export class SessionWindow {
   }
 
   observeInbound(timestamp: number): void {
-    if (this.lastInboundAt === undefined || timestamp > this.lastInboundAt) this.lastInboundAt = timestamp;
+    if (this.lastInboundAt === undefined || timestamp > this.lastInboundAt) {
+      this.lastInboundAt = timestamp;
+      this.shutByProvider = false;
+    }
+  }
+
+  /**
+   * The provider refused a free-form message because its window is shut. Its
+   * clock is the one the 24 hours are counted on, so from here the window
+   * reads shut whatever ours says, and the next message is a template.
+   */
+  observeProviderShut(): void {
+    this.shutByProvider = true;
   }
 
   /** Seconds left before free-form messages stop being allowed; 0 when the window is shut or was never opened. */
   remainingSeconds(now: Date): number {
-    if (this.lastInboundAt === undefined) return 0;
+    if (this.lastInboundAt === undefined || this.shutByProvider) return 0;
     return Math.max(0, this.lastInboundAt + SESSION_WINDOW_SECONDS - Math.floor(now.getTime() / 1000));
   }
 

package/templates/supplier-payments-agent/packages/agent-runtime/src/commands/poll-whatsapp.ts

@@ -32,14 +32,14 @@ import { relative } from "node:path";
 import { ProofBundle, type ChargeInstrument, type Execution } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
 import { runsDir, type Setup } from "../setup.js";
-import { waitForPayer } from "../terminal.js";
+import { followUp, waitForPayer } from "../terminal.js";
 import { resolveConversation } from "../channels/index.js";
-import { buildWhatsApp, simulatedCost, type WhatsAppBackendName } from "../channels/whatsapp/open.js";
+import { buildWhatsApp, simulatedCost, statusGraceMs, undeliveredCursor, type WhatsAppBackendName } from "../channels/whatsapp/open.js";
 import { EmulatorUnreachableError } from "../channels/whatsapp/emulator.js";
 import { sessionStateFromChannelLog, type SessionState } from "../channels/whatsapp/session.js";
 import { instrumentBodies } from "../channels/whatsapp/present.js";
 import type { WhatsAppChannel } from "../channels/whatsapp/index.js";
-import type { SentMessage } from "../channels/types.js";
+import type { ChannelLogLine, OutboundBody, SentMessage } from "../channels/types.js";
 
 export interface PollWhatsAppOptions {
   agent: Agent;
@@ -57,8 +57,8 @@ export interface PollWhatsAppOptions {
 
 /** How the outcome reached the person, or why it did not. */
 type Delivery =
-  | { told: true; carrier: "text" | "template"; template?: string }
-  | { told: false; reason: "already_told" | "still_open" | "no_template_for_outcome" | "refused"; detail?: string };
+  | { told: true; carrier: "text" | "template"; template?: string; fallback?: true }
+  | { told: false; reason: "already_told" | "still_open" | "no_template_for_outcome" | "refused" | "delivery_failed"; detail?: string };
 
 interface Polled {
   id: string;
@@ -112,7 +112,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   // window is counted from the person's last message on the PROVIDER's clock,
   // which only that record holds, and the confirmation is appended THERE, so
   // one conversation stays one record instead of ending in a second folder.
-  const { bundle, session } = conversationRecord(agent, mine);
+  const { bundle, session, lines: priorLines } = conversationRecord(agent, mine);
   if (!bundle) {
     say(`nenhum bundle encontrado para ${mine.map((e) => e.run_id).join(", ")}: a conversa nao pode ser retomada sem o registro dela`);
     return 1;
@@ -129,6 +129,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
     // Nobody writes in a poll: the person already said what they had to say,
     // and this run is here because the PAYER acted, not because the person did.
     session,
+    priorLines,
   });
   if ("refusal" in built) {
     for (const line of built.refusal) say(line);
@@ -176,6 +177,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
       const closed = result.execution;
       if (closed.state !== "executing") await s.engine.collectReceipts(closed.id);
       const delivery = await tellOutcome(channel, s, closed);
+      await followUp(closed, s, say);
       results.push({
         id: closed.id,
         state: closed.state,
@@ -188,7 +190,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
       });
       say(
         `${closed.id}: ${closed.state}${closed.reason ? ` (${closed.reason})` : ""} apos ${result.rounds} consulta(s), ${result.seconds}s — ${
-          delivery.told ? `avisado por ${delivery.carrier === "template" ? `template ${delivery.template}` : "mensagem livre"}` : `nao avisado (${delivery.reason}${delivery.detail ? `: ${delivery.detail}` : ""})`
+          delivery.told ? `avisado por ${delivery.carrier === "template" ? `template ${delivery.template}${delivery.fallback ? " (reserva: o kit nao tem copia para este desfecho)" : ""}` : "mensagem livre"}` : `nao avisado (${delivery.reason}${delivery.detail ? `: ${delivery.detail}` : ""})`
         }`,
       );
     }
@@ -219,6 +221,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   // not know it. The other two are not failures — `already_told` is this
   // command running twice, which is the thing it is built to be safe under,
   // and `still_open` is a wait that ran out, which the 3 above already said.
+  // `delivery_failed` is the provider saying the person never got it, and is the same failure as a refusal.
   return results.some((r) => !r.delivery.told && r.delivery.reason !== "already_told" && r.delivery.reason !== "still_open") ? 1 : 0;
 }
 
@@ -229,11 +232,12 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
  * itself is read across all of them, because the person's last message is the
  * person's last message whichever run recorded it.
  */
-function conversationRecord(agent: Agent, executions: readonly Execution[]): { bundle: ProofBundle | undefined; session: SessionState } {
+function conversationRecord(agent: Agent, executions: readonly Execution[]): { bundle: ProofBundle | undefined; session: SessionState; lines: ChannelLogLine[] } {
   const runs = runsDir(agent);
   const seen = new Set<string>();
   let bundle: ProofBundle | undefined;
   let lastInboundAt: number | undefined;
+  const all: ChannelLogLine[] = [];
   // `list()` orders by creation, so the last execution that carries a log is the most recent record of the conversation.
   for (const execution of executions) {
     if (seen.has(execution.run_id)) continue;
@@ -242,11 +246,12 @@ function conversationRecord(agent: Agent, executions: readonly Execution[]): { b
     if (!opened) continue;
     const lines = opened.readChannel();
     if (!lines.length) continue;
+    all.push(...(lines as unknown as ChannelLogLine[]));
     bundle = opened;
     const state = sessionStateFromChannelLog(lines);
     if (state.lastInboundAt !== undefined && (lastInboundAt === undefined || state.lastInboundAt > lastInboundAt)) lastInboundAt = state.lastInboundAt;
   }
-  return { bundle, session: { lastInboundAt } };
+  return { bundle, session: { lastInboundAt }, lines: all };
 }
 
 /**
@@ -287,31 +292,76 @@ async function tellOutcome(channel: WhatsAppChannel, s: Setup, execution: Execut
     // last-one-wins, so a kit that says two sentences does not lose one.
     const lines: string[] = [];
     const told = s.kit.announceOutcome?.(execution, s, (line) => void lines.push(line)) ?? false;
-    if (!told) return { told: false, reason: "already_told" };
-    const sent = await channel.send({ kind: "text", text: lines.join("\n") });
-    return deliveryOf(sent, "text");
+    if (!told) return toldBefore(s, execution);
+    const sent = await channel.send({ kind: "text", text: lines.join("\n"), about: aboutOf(execution) });
+    // Our clock read the window open and the provider's read it shut (131047).
+    // The provider's is the one the window is counted on, so the message goes
+    // the way it would have gone had we known: as the template. The cursor is
+    // already this call's, taken by `announceOutcome` above.
+    if (sent.refused?.rule !== "session_window_closed") return confirmed(channel, sent, deliveryOf(sent, "text"));
+    return tellByTemplate(channel, s, execution, { cursorHeld: true });
   }
+  return tellByTemplate(channel, s, execution, { cursorHeld: false });
+}
+
+function aboutOf(execution: Execution): NonNullable<Extract<OutboundBody, { kind: "text" }>["about"]> {
+  return { execution_id: execution.id, state: execution.state };
+}
 
-  const chosen = s.kit.outcomeTemplate?.(execution);
+/** The cursor was taken by an earlier run. Told, unless the provider said since that the message never arrived. */
+function toldBefore(s: Setup, execution: Execution): Delivery {
+  const failed = s.store.getCursor(undeliveredCursor(execution.id, execution.state));
+  return failed ? { told: false, reason: "delivery_failed", detail: `an earlier message came back failed: ${failed}` } : { told: false, reason: "already_told" };
+}
+
+/**
+ * A send that answered is not yet a message that arrived. The provider may
+ * report a failure a moment later; the channel records it (and the bundle,
+ * and the operator hear of it), and this gives it the bounded wait before
+ * saying the person was told.
+ */
+async function confirmed(channel: WhatsAppChannel, sent: SentMessage, delivery: Delivery): Promise<Delivery> {
+  if (!delivery.told || !sent.id) return delivery;
+  await channel.settle(statusGraceMs());
+  if (channel.deliveryOf(sent.id) !== "failed") return delivery;
+  const line = channel.log().find((l: ChannelLogLine) => l.direction === "status" && l.message_id === sent.id && l.state === "failed");
+  return { told: false, reason: "delivery_failed", detail: `the provider reported ${sent.id} failed${line?.errors?.length ? ` (${line.errors.map((e) => e.code).join(", ")})` : ""}` };
+}
+
+/**
+ * The outcome as a template. The kit's own copy when it has one; the
+ * registry's FALLBACK when it has none — a template that says there is news
+ * and asks the person to answer, and states nothing about the outcome, so it
+ * cannot be the wrong news (`npm run check` requires exactly one, taking no
+ * variables). A kit that names a template the registry does not declare is a
+ * defect, reported as one and not papered over by the fallback.
+ */
+async function tellByTemplate(channel: WhatsAppChannel, s: Setup, execution: Execution, options: { cursorHeld: boolean }): Promise<Delivery> {
+  const chosen: { template: string; variables: string[]; fallback?: true } | undefined = s.kit.outcomeTemplate?.(execution) ?? fallbackOf(channel);
   if (!chosen) {
     return {
       told: false,
       reason: "no_template_for_outcome",
-      detail: `a janela de 24h esta fechada e o agente nao declara template para ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`,
+      detail: `a janela de 24h esta fechada e o agente nao declara template para ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}, nem um template de reserva`,
     };
   }
   const declared = channel.declaredTemplate(chosen.template);
   if (!declared) {
     return { told: false, reason: "no_template_for_outcome", detail: `o kit pediu o template ${chosen.template}, que channels/whatsapp/templates.json nao declara` };
   }
-  if (!s.engine.markTold(execution.id, execution.state)) return { told: false, reason: "already_told" };
-  const sent = await channel.send({ kind: "template", template: declared.name, language: declared.language, variables: chosen.variables });
-  s.engine.note("message.debtor", execution.id, { state: execution.state, reason: execution.reason ?? null, template: declared.name, variables: chosen.variables });
-  return deliveryOf(sent, "template", declared.name);
+  if (!options.cursorHeld && !s.engine.markTold(execution.id, execution.state)) return toldBefore(s, execution);
+  const sent = await channel.send({ kind: "template", template: declared.name, language: declared.language, variables: chosen.variables, about: aboutOf(execution) });
+  s.engine.note("message.debtor", execution.id, { state: execution.state, reason: execution.reason ?? null, template: declared.name, variables: chosen.variables, ...(chosen.fallback ? { fallback: true } : {}) });
+  return confirmed(channel, sent, deliveryOf(sent, "template", declared.name, chosen.fallback));
+}
+
+function fallbackOf(channel: WhatsAppChannel): { template: string; variables: string[]; fallback: true } | undefined {
+  const name = channel.fallbackTemplate();
+  return name ? { template: name, variables: [], fallback: true } : undefined;
 }
 
-function deliveryOf(sent: SentMessage, carrier: "text" | "template", template?: string): Delivery {
+function deliveryOf(sent: SentMessage, carrier: "text" | "template", template?: string, fallback?: boolean): Delivery {
   if (sent.refused) return { told: false, reason: "refused", detail: `${sent.refused.rule}: ${sent.refused.detail}` };
   if (sent.state === "failed") return { told: false, reason: "refused", detail: "o provedor nao aceitou a mensagem" };
-  return { told: true, carrier, ...(template ? { template } : {}) };
+  return { told: true, carrier, ...(template ? { template } : {}), ...(fallback ? { fallback: true as const } : {}) };
 }

package/templates/supplier-payments-agent/packages/agent-runtime/src/commands/poll.ts

@@ -18,7 +18,7 @@ import { join } from "node:path";
 import { loadManifest, resolveFixedClock, type ChannelName } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
 import { setup } from "../setup.js";
-import { announceOutcome, waitForPayer } from "../terminal.js";
+import { announceOutcome, followUp, waitForPayer } from "../terminal.js";
 import { pollWhatsApp } from "./poll-whatsapp.js";
 import type { WhatsAppBackendName } from "../channels/whatsapp/open.js";
 
@@ -132,6 +132,7 @@ export async function poll(agent: Agent, argv: string[]): Promise<number> {
       const r = await waitForPayer(open.id, { setup: s, approver: { id: s.kit.labels.defaultUser, channel: "terminal" }, say, tell, waitSeconds: args.wait, simulatePayer: args.simulatePayer });
       announceOutcome(r.execution, s, tell);
       if (r.execution.state !== "executing") await s.engine.collectReceipts(r.execution.id);
+      await followUp(r.execution, s, say);
       results.push({ id: r.execution.id, state: r.execution.state, reason: r.execution.reason ?? null, rounds: r.rounds, seconds: r.seconds, timed_out: r.timed_out });
       say(`${r.execution.id}: ${r.execution.state}${r.execution.reason ? ` (${r.execution.reason})` : ""} after ${r.rounds} look(s), ${r.seconds}s`);
     }

package/templates/supplier-payments-agent/packages/agent-runtime/src/commands/resume.ts

@@ -1,12 +1,15 @@
 /**
  * `codespar-agent resume [--json]`: after a crash or a restart. Executions
- * left in `executing` are reconciled against the rail (idempotent on
- * attempt_id), never repeated; stale open ones expire.
+ * left in `executing` are reconciled against the rail, never repeated: a
+ * lookup presents the same explicit attempt_id, which the API answers from
+ * its record of that attempt without paying again (ent#1671). Stale open
+ * ones expire.
  */
 import { stderr, stdout } from "node:process";
 import type { Execution } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
 import { setup } from "../setup.js";
+import { followUp } from "../terminal.js";
 
 export async function resume(agent: Agent, argv: string[]): Promise<number> {
   const json = argv.includes("--json");
@@ -21,6 +24,9 @@ export async function resume(agent: Agent, argv: string[]): Promise<number> {
       closed.push(e);
       say(e.state === "executing" ? s.kit.labels.stillExecuting(e) : `${e.id}: executing -> ${e.state}`);
     }
+    for (const e of closed) if (e.state !== "executing") await followUp(e, s, say);
+    // What a crash left half-done after an outcome (a service invoice opened and never sent, or sent and never answered).
+    await s.kit.resumeFollowUps?.(s, say);
     const expired = s.engine.expireStale().map((e) => ({ id: e.id, state: e.state }));
     for (const e of expired) say(`${e.id}: -> expired`);
     const open = s.engine.list({ state: ["awaiting_approval", "approved"] }).map((e) => ({ id: e.id, state: e.state }));

package/templates/supplier-payments-agent/packages/agent-runtime/src/commands/start-whatsapp.ts

@@ -109,6 +109,9 @@ export async function startWhatsApp(options: StartWhatsAppOptions): Promise<numb
     messages_in: log.filter((l) => l.direction === "in").length,
     messages_out: log.filter((l) => l.direction === "out" && !l.refused).length,
     refused,
+    // What the provider reported undelivered after it left, and which outcome each one was telling.
+    delivery_failed: log.filter((l) => l.direction === "status" && l.state === "failed").map((l) => ({ message_id: l.message_id, errors: l.errors ?? [], ...(l.about ? { about: l.about } : {}) })),
+    taps: log.filter((l) => l.kind === "reply").map((l) => ({ id: l.reply?.id ?? null, turn: !l.refused, ...(l.refused ? { refused: l.refused.rule } : {}) })),
     log: relative(process.cwd(), `${s.bundle.dir}/channel.jsonl`),
     ...(cost ? { simulated_cost: cost } : {}),
   };