@codespar/cli 0.16.0 → 0.18.0

package/templates/checkout-agent/packages/agent-runtime/src/commands/eval.ts

@@ -0,0 +1,58 @@
+/**
+ * `codespar-agent eval [--json] [--case <name>]`: the adversarial suite of
+ * section 9 plus every scenario of section 12 in every mode it declares. Runs
+ * on the replay provider and the stub rail, with no model and no network. A
+ * regression blocks merge.
+ */
+import { stderr, stdout } from "node:process";
+import type { Agent } from "../agent.js";
+import { listAdversarialCases, loadAdversarialCase, runAdversarialCase, type AdversarialResult } from "../adversarial.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioCheck } from "../scenarios.js";
+
+export async function runEval(agent: Agent, argv: string[]): Promise<number> {
+  const json = argv.includes("--json");
+  const only = argv.includes("--case") ? argv[argv.indexOf("--case") + 1] : undefined;
+  const say = (l: string) => stderr.write(l + "\n");
+  const awaitsPayer = agent.settlement === "await-payer";
+
+  const adversarial = [];
+  for (const name of listAdversarialCases(agent)) {
+    if (only && only !== name) continue;
+    const result = await runAdversarialCase(agent, loadAdversarialCase(agent, name));
+    adversarial.push(result);
+    say(agent.kit.evalAdversarialLine?.(result) ?? adversarialLine(result));
+  }
+
+  const scenarios = [];
+  for (const name of listScenarios(agent)) {
+    if (only && only !== name) continue;
+    const scenario = loadScenario(agent, name);
+    if (!scenario.rails.includes("stub")) continue;
+    for (const mode of scenario.modes) {
+      const check = checkScenario(scenario, await runScenario(agent, scenario, { mode, rail: "stub" }));
+      scenarios.push({
+        name,
+        mode,
+        ok: check.ok,
+        failures: check.failures,
+        states: check.run.executions.map((e) => e.state),
+        receipts: check.run.receipts,
+        ...(awaitsPayer ? { charges_issued: check.run.charges_issued, debtor_messages: check.run.debtor_messages } : {}),
+      });
+      say(agent.kit.evalScenarioLine?.(check) ?? scenarioLine(check));
+    }
+  }
+
+  const ok = adversarial.every((r) => r.ok) && scenarios.every((r) => r.ok);
+  if (json) stdout.write(JSON.stringify({ ok, adversarial, scenarios }) + "\n");
+  say(ok ? `eval ok: ${adversarial.length} adversarial case(s), ${scenarios.length} scenario run(s)` : "eval FAILED");
+  return ok ? 0 : 1;
+}
+
+function adversarialLine(result: AdversarialResult): string {
+  return `${result.ok ? "ok  " : "FAIL"} adversarial/${result.name} — ${result.attack} — states ${JSON.stringify(result.states)}${result.failures.length ? ` — ${result.failures.join("; ")}` : ""}`;
+}
+
+function scenarioLine(check: ScenarioCheck): string {
+  return `${check.ok ? "ok  " : "FAIL"} scenario/${check.run.scenario} [${check.mode}] — states ${JSON.stringify(check.run.executions.map((e) => e.state))}, ${check.run.receipts} receipt(s)${check.failures.length ? ` — ${check.failures.join("; ")}` : ""}`;
+}

package/templates/checkout-agent/packages/agent-runtime/src/commands/inspect.ts

@@ -0,0 +1,100 @@
+/**
+ * `codespar-agent inspect <run-id> [--json] [--html <path>]`: the proof bundle
+ * of section 11 read back as a timeline. Defaults to the terminal rendering;
+ * `--json` follows the rule of section 14.5 — machine data on stdout, valid
+ * JSON and nothing else, human messages on stderr.
+ *
+ * It reads the bundle and nothing else, so it works on any agent's run, and
+ * on a folder copied off the machine that produced it.
+ */
+import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stderr, stdout } from "node:process";
+import { ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import { runsDir } from "../setup.js";
+import { assembleTimeline, renderHtml, renderText } from "../inspect.js";
+
+const USAGE = "usage: npm run inspect <run-id> [--json] [--html <file>]";
+
+export function inspect(agent: Agent, argv: string[]): number {
+  const say = (line: string) => stderr.write(line + "\n");
+  let json = false;
+  let html: string | undefined;
+  let runId: string | undefined;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === "--json") json = true;
+    else if (a === "--html") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        say(`--html needs a file path\n${USAGE}`);
+        return 2;
+      }
+      html = value;
+      i += 1;
+    } else if (a === "--help" || a === "-h") {
+      say(USAGE);
+      return 0;
+    } else if (a.startsWith("-")) {
+      say(`unknown argument ${a}\n${USAGE}`);
+      return 2;
+    } else if (runId === undefined) runId = a;
+    else {
+      say(`inspect takes one run id (got ${runId} and ${a})\n${USAGE}`);
+      return 2;
+    }
+  }
+
+  const runs = runsDir(agent);
+  if (!runId) {
+    say(USAGE);
+    say(available(runs));
+    return 2;
+  }
+
+  // An unknown run id is a refusal a person can act on, never a stack trace.
+  const bundle = ProofBundle.open(runs, runId);
+  if (!bundle) {
+    say(`no proof bundle for run ${runId}: nothing at ${resolve(runs, runId)}`);
+    say(available(runs));
+    return 1;
+  }
+
+  // A bundle half-written by a run that was killed is exactly when somebody looks at it: say which file is unreadable, do not throw a stack at them.
+  let report;
+  try {
+    report = assembleTimeline(bundle);
+  } catch (err) {
+    say(`the bundle at ${bundle.dir} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    say("a file in it is missing or not valid JSON; the folder is the run's own output and is safe to delete and re-run");
+    return 1;
+  }
+
+  if (html) {
+    try {
+      writeFileSync(html, renderHtml(report));
+    } catch (err) {
+      say(`could not write ${resolve(html)}: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+    say(`wrote ${resolve(html)} — one file, no network, opens from disk`);
+  }
+  if (json) stdout.write(JSON.stringify(report) + "\n");
+  else stdout.write(renderText(report));
+  return 0;
+}
+
+/** What the person can inspect instead. Bounded: a long-lived agent has many runs and this is an error message, not a listing command. */
+function available(runs: string): string {
+  if (!existsSync(runs)) return `no runs yet: ${runs} does not exist. Run the agent once, then inspect the run id it printed.`;
+  const ids = readdirSync(runs, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort()
+    .reverse();
+  if (!ids.length) return `no runs yet in ${runs}. Run the agent once, then inspect the run id it printed.`;
+  const shown = ids.slice(0, 10);
+  return `runs in ${runs}${ids.length > shown.length ? ` (newest ${shown.length} of ${ids.length})` : ""}:\n${shown.map((id) => `  ${id}`).join("\n")}`;
+}

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

@@ -0,0 +1,367 @@
+/**
+ * `codespar-agent poll --channel whatsapp`: the conversation's loop-closer.
+ *
+ * The terminal already had one, and the reason the channel needs its own is
+ * the whole of issue #25. Over a terminal the operator and the counterparty
+ * are the same pair of eyes and the run never really ends. Over WhatsApp the
+ * debtor agrees on Tuesday and pays on Friday: the run that issued the charge
+ * exited days ago, and by the time the money lands the 24-hour customer
+ * service window has shut, so "recebemos, acordo quitado" can only go out as
+ * a template Meta approved in advance. Without this command that case cannot
+ * be run at all, which is why the confirmation in every recorded run so far
+ * happened inside the turn that issued the charge.
+ *
+ * What it does: reopens a conversation from the RECORD — the bundle of the
+ * run that held it, plus `state.db` — looks at the receivable the way the
+ * terminal poll does, and puts the outcome back into that same conversation.
+ * Nothing about which message may be sent is decided here: the channel's
+ * rules and the session window decide, and this only ASKS the window which of
+ * the two carriers it may use, because composing a message in order to watch
+ * it be refused is not a decision.
+ *
+ * Three things it deliberately does not do. It does not invent a conversation
+ * when there is nothing waiting for a payer — that is a no-op and exits 0,
+ * because a cron that fails when there is no work is a cron somebody turns
+ * off. It does not send a second confirmation when it runs twice, because the
+ * once-only cursor is in `state.db` and outlives the process. And it does not
+ * pin the emulator's clock, unlike the run that started the conversation:
+ * rewinding the provider's clock would reopen a window that really is shut.
+ */
+import { stdout } from "node:process";
+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 { followUp, waitForPayer } from "../terminal.js";
+import { resolveConversation } from "../channels/index.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 { ChannelLogLine, OutboundBody, SentMessage } from "../channels/types.js";
+
+export interface PollWhatsAppOptions {
+  agent: Agent;
+  setup: Setup;
+  conversation: string | undefined;
+  backend: WhatsAppBackendName;
+  json: boolean;
+  waitSeconds?: number | undefined;
+  simulatePayer?: boolean | undefined;
+  /** Stub only: what the fixture payer does with the receivables THIS conversation is waiting on. */
+  payer?: "pays" | "expires" | "never" | undefined;
+  now: () => Date;
+  say: (line: string) => void;
+}
+
+/** How the outcome reached the person, or why it did not. */
+type Delivery =
+  | { 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;
+  state: string;
+  reason: string | null;
+  rounds: number;
+  seconds: number;
+  timed_out: boolean;
+  session_open: boolean;
+  delivery: Delivery;
+}
+
+export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number> {
+  const { agent, setup: s, say, now } = options;
+
+  let script;
+  try {
+    script = resolveConversation(agent, options.conversation);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+
+  // Which open executions belong to THIS conversation. The binding is the
+  // conversation's subject — the agreement alias it is allowed to name — and
+  // that is not a convenience: sending one debtor's outcome into another
+  // debtor's chat is the secrecy rule broken, and the same `subject` is what
+  // the channel already refuses other agreements by. A conversation that
+  // declares no subject binds to nothing and says so, rather than taking
+  // every open execution and hoping.
+  const open = s.engine.list({ state: "executing" }).filter((e) => e.reason === "awaiting_settlement");
+  const subject = script.subject;
+  // EVERY item, not some: an execution that mixes this conversation's
+  // agreement with another's belongs to neither, and confirming it here would
+  // put somebody else's debt in front of this person.
+  const mine = subject ? open.filter((e) => e.items.length > 0 && e.items.every((i) => i.alias === subject || i.payee === subject)) : [];
+
+  if (!subject && open.length) {
+    say(`a conversa ${script.name} nao declara subject: nao da para dizer quais execucoes sao dela, e mandar o desfecho de outra pessoa nesta conversa e exatamente o que a regra de sigilo proibe`);
+    return 2;
+  }
+  if (!mine.length) {
+    // A clean no-op: nothing is waiting, so nothing is opened. The emulator is
+    // not even contacted, which is the point — a poll with no work does no work.
+    if (options.json) stdout.write(JSON.stringify({ polled: [], conversation: script.name, channel: null }) + "\n");
+    else say(`nada aguardando pagador em ${script.name}`);
+    return 0;
+  }
+
+  // The conversation as it was left: the bundle of the run that held it. The
+  // 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, 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;
+  }
+
+  const built = buildWhatsApp({
+    agent,
+    setup: s,
+    conversation: { contact: script.contact, subject: script.subject },
+    backend: options.backend,
+    now,
+    say,
+    bundle,
+    // 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);
+    return 1;
+  }
+  const { channel, driver, sessionKey } = built;
+
+  // Scoped to the receivables of THIS conversation: `behave` set the default
+  // for new ones, and this rewrites the fate of the ones already issued —
+  // another conversation's charge is none of this command's business.
+  if (options.payer) {
+    for (const execution of mine) {
+      for (const outcome of execution.outcomes) if (outcome.status === "accepted") s.payer?.decideFor?.(outcome.attempt_id, options.payer);
+    }
+  }
+
+  try {
+    await channel.open();
+  } catch (err) {
+    if (err instanceof EmulatorUnreachableError) {
+      say(err.message);
+      return 1;
+    }
+    throw err;
+  }
+
+  const results: Polled[] = [];
+  try {
+    const remaining = channel.sessionRemainingSeconds;
+    say(
+      `${s.manifest.manifest.name} ${s.manifest.manifest.version} — poll no canal whatsapp (${channel.backend}) — conversa ${script.name} — janela de 24h ${
+        channel.sessionOpen ? `ABERTA (${Math.round(remaining / 60)} min restantes): mensagem livre` : "FECHADA: so template aprovado"
+      }`,
+    );
+    for (const execution of mine) {
+      const sessionOpen = channel.sessionOpen;
+      const result = await waitForPayer(execution.id, {
+        setup: s,
+        approver: { id: s.kit.labels.defaultUser, channel: "whatsapp" },
+        say,
+        waitSeconds: options.waitSeconds,
+        simulatePayer: options.simulatePayer,
+        presentInstrument: (e, n, id, instrument) => presentInstrument(channel, s, e, n, id, instrument),
+      });
+      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,
+        reason: closed.reason ?? null,
+        rounds: result.rounds,
+        seconds: result.seconds,
+        timed_out: result.timed_out,
+        session_open: sessionOpen,
+        delivery,
+      });
+      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}${delivery.fallback ? " (reserva: o kit nao tem copia para este desfecho)" : ""}` : "mensagem livre"}` : `nao avisado (${delivery.reason}${delivery.detail ? `: ${delivery.detail}` : ""})`
+        }`,
+      );
+    }
+  } finally {
+    await channel.close();
+  }
+
+  const cost = await simulatedCost(driver, sessionKey);
+  const log = channel.log();
+  const refused = log.filter((l) => l.refused).map((l) => ({ rule: l.refused!.rule, detail: l.refused!.detail }));
+  const channelSummary = {
+    name: "whatsapp",
+    backend: channel.backend,
+    conversation: script.name,
+    session_open: channel.sessionOpen,
+    messages_out: log.filter((l) => l.direction === "out" && !l.refused).length,
+    refused,
+    log: relative(process.cwd(), `${bundle.dir}/channel.jsonl`),
+    ...(cost ? { simulated_cost: cost } : {}),
+  };
+
+  if (options.json) stdout.write(JSON.stringify({ polled: results, conversation: script.name, channel: channelSummary }) + "\n");
+  else say(`conversa em ${channelSummary.log} — ${channelSummary.messages_out} enviada(s)${refused.length ? `, ${refused.length} recusada(s)` : ""}`);
+
+  if (results.some((r) => r.timed_out)) return 3;
+  // A cycle that closed and a person who was not told is a failure worth an
+  // exit code: the record says the agreement is settled and the debtor does
+  // 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;
+}
+
+/**
+ * The bundle the conversation lives in, and where its window stood. When
+ * several runs touched the same conversation the LATEST one holds the last
+ * inbound, so that is the record the confirmation is appended to; the window
+ * 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; 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;
+    seen.add(execution.run_id);
+    const opened = ProofBundle.open(runs, execution.run_id);
+    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 }, lines: all };
+}
+
+/**
+ * The payable artifact, the way a person can use it: the QR as an image and
+ * the copy-and-paste as its OWN message. The same shape `converse` sends,
+ * because a payer told how to pay by a poll is told the same way a payer told
+ * by a run is.
+ *
+ * It is only reached for an instrument nobody has shown yet — `markShown` is a
+ * cursor in `state.db` — so in the ordinary resumed conversation nothing is
+ * sent here at all. When it IS reached with the window shut the channel
+ * refuses it, and that refusal is the record: WhatsApp would not have carried
+ * it either.
+ */
+async function presentInstrument(channel: WhatsAppChannel, s: Setup, execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument): Promise<void> {
+  for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency)) await channel.send(body);
+}
+
+/**
+ * The one message per outcome, carried by whichever of the two the window
+ * allows. Both halves share `markTold`, the cursor in `state.db`, so a second
+ * poll sends nothing whichever carrier the first one used.
+ *
+ * The order matters and is deliberate: the cursor is taken BEFORE the send.
+ * Taking it after would mean a process killed between the send and the write
+ * tells the person twice, and on a channel that is a second "recebemos" for
+ * one payment. A send that is then refused is reported instead, with the
+ * rule, and it is the exit code of the command — the record says settled and
+ * the debtor does not know.
+ */
+async function tellOutcome(channel: WhatsAppChannel, s: Setup, execution: Execution): Promise<Delivery> {
+  // Nothing closed, so there is no outcome to carry. Not a failure and not a
+  // silence to explain: the wait ran out and the receivable is still open.
+  if (execution.state === "executing") return { told: false, reason: "still_open" };
+
+  if (channel.sessionOpen) {
+    // The kit writes lines, the channel sends messages. Joined rather than
+    // 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 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 };
+}
+
+/** 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})` : ""}, 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 (!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, 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 } : {}), ...(fallback ? { fallback: true as const } : {}) };
+}

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

@@ -0,0 +1,145 @@
+/**
+ * `codespar-agent poll [--channel terminal|whatsapp] [--wait <seconds>] [--simulate-payer] [--json]`:
+ * keeps looking at every receivable still waiting for its payer until it
+ * closes or the wait runs out. This is the loop-closer for a run that has no
+ * webhook URL; `codespar-agent webhook` is the other. Presents an instrument
+ * not yet shown, tells the payer the outcome once, fetches the paid record.
+ *
+ * `--channel` is on THIS command rather than in a second one, and the reason
+ * is that only one thing differs between the two: where the outcome message
+ * goes, and which carriers that place allows. The looking, the once-only
+ * presentation, the sandbox payer, the receipts and the terminal states are
+ * one loop — `pollUntilClosed` — and a second command would have meant a
+ * second copy of it, which is exactly how a channel ends up closing a cycle
+ * differently from the terminal.
+ */
+import { stderr, stdout } from "node:process";
+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, followUp, waitForPayer } from "../terminal.js";
+import { pollWhatsApp } from "./poll-whatsapp.js";
+import type { WhatsAppBackendName } from "../channels/whatsapp/open.js";
+
+const USAGE = `codespar-agent poll [options]
+  --channel terminal|whatsapp   where the outcome is told. Default terminal.
+  --conversation <name>         which channels/whatsapp/<name>.json to come back to (--channel whatsapp)
+  --backend simulator|cloud-api default simulator, the local emulator (--channel whatsapp)
+  --wait <seconds>              how long to keep looking
+  --simulate-payer              let the sandbox payer act once the receivable is payable
+  --payer pays|expires|never    what the fixture payer does when it acts (stub rail only)
+  --now <ISO 8601>              pin the run's clock; env CODESPAR_AGENT_NOW is the same thing
+  --json                        machine output on stdout, everything else on stderr`;
+
+interface Args {
+  channel: ChannelName;
+  conversation?: string;
+  backend?: WhatsAppBackendName;
+  wait?: number;
+  simulatePayer: boolean;
+  payer?: "pays" | "expires" | "never";
+  now?: string;
+  json: boolean;
+}
+
+export function parsePollArgs(argv: string[]): Args {
+  const args: Args = { channel: "terminal", simulatePayer: false, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    const next = () => {
+      const v = argv[i + 1];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      i += 1;
+      return v;
+    };
+    if (a === "--json") args.json = true;
+    else if (a === "--simulate-payer") args.simulatePayer = true;
+    else if (a === "--wait") {
+      const v = Number(next());
+      if (!Number.isFinite(v) || v < 0) throw new Error("--wait must be a number of seconds");
+      args.wait = v;
+    } else if (a === "--channel") {
+      const v = next();
+      if (v !== "terminal" && v !== "whatsapp") throw new Error("--channel must be terminal or whatsapp");
+      args.channel = v;
+    } else if (a === "--backend") {
+      const v = next();
+      if (v !== "simulator" && v !== "cloud-api") throw new Error("--backend must be simulator or cloud-api");
+      args.backend = v;
+    } else if (a === "--payer") {
+      const v = next();
+      if (v !== "pays" && v !== "expires" && v !== "never") throw new Error("--payer must be pays, expires or never");
+      args.payer = v;
+    } else if (a === "--conversation") args.conversation = next();
+    else if (a === "--now") args.now = next();
+    else throw new Error(`unknown argument ${a}`);
+  }
+  if (args.channel !== "whatsapp" && (args.backend !== undefined || args.conversation !== undefined)) {
+    throw new Error("--backend and --conversation belong to --channel whatsapp");
+  }
+  return args;
+}
+
+export async function poll(agent: Agent, argv: string[]): Promise<number> {
+  const say = (l: string) => stderr.write(l + "\n");
+  let args: Args;
+  let now: (() => Date) | undefined;
+  try {
+    args = parsePollArgs(argv);
+    now = resolveFixedClock(args.now, process.env);
+  } catch (err) {
+    say(`${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+    return 2;
+  }
+  if (args.channel === "whatsapp" && !loadManifest(join(agent.dir, "agent.yaml")).manifest.channels.includes("whatsapp")) {
+    say(`${agent.slug} does not declare the whatsapp channel in agent.yaml`);
+    return 2;
+  }
+
+  const s = setup(agent, { say, runId: `run_poll_${Date.now().toString(36)}`, ...(now ? { now } : {}) });
+  // The same flag `start` has, and it means more here: a receivable nobody
+  // paid reaches its due date BETWEEN two runs, never inside one, so "what
+  // happens when it expires" is a question only a poll can be asked.
+  if (args.payer) s.payer?.behave(args.payer);
+  try {
+    if (args.channel === "whatsapp") {
+      return await pollWhatsApp({
+        agent,
+        setup: s,
+        conversation: args.conversation,
+        backend: args.backend ?? "simulator",
+        json: args.json,
+        waitSeconds: args.wait,
+        simulatePayer: args.simulatePayer,
+        ...(args.payer ? { payer: args.payer } : {}),
+        now: now ?? (() => new Date()),
+        say,
+      });
+    }
+    // `behave` only changes the default for receivables the rail has not
+    // looked at, and by now it has looked at these; `decideFor` is what
+    // rewrites the fate of one that already exists.
+    if (args.payer) {
+      for (const open of s.engine.list({ state: "executing" })) {
+        for (const outcome of open.outcomes) if (outcome.status === "accepted") s.payer?.decideFor?.(outcome.attempt_id, args.payer);
+      }
+    }
+    const tell = (l: string) => void (args.json ? stderr : stdout).write(l + "\n");
+    const results = [];
+    for (const open of s.engine.list({ state: "executing" })) {
+      if (open.reason !== "awaiting_settlement") continue;
+      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`);
+    }
+    if (args.json) stdout.write(JSON.stringify({ polled: results }) + "\n");
+    else if (!results.length) say("nothing waiting for a payer");
+    return results.some((r) => r.timed_out) ? 3 : 0;
+  } finally {
+    s.close();
+  }
+}