@codespar/cli 0.16.0 → 0.18.0

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

package/templates/bills-agent/packages/agent-runtime/src/commands/start.ts

@@ -9,14 +9,14 @@
  */
 import { stderr, stdout } from "node:process";
 import { relative, resolve } from "node:path";
-import { NotATestKeyError, isTestKey, loadManifest, resolveFixedClock, type ApprovalMode, type ChannelName } from "@codespar/agent-core";
+import { NotATestKeyError, declaredReplies, isTestKey, loadManifest, resolveFixedClock, type ApprovalMode, type ChannelName } from "@codespar/agent-core";
 import { join } from "node:path";
 import type { Agent } from "../agent.js";
 import type { RailKind } from "../kit.js";
 import { resolveProvider, resolveRailKind, setup, type ProviderKind } from "../setup.js";
 import { checkScenario, listScenarios, loadScenario, runScenario, scenariosDir } from "../scenarios.js";
 import { closeTerminal, defaultAsk, handleExecution, interactive } from "../terminal.js";
-import { resolveConversation } from "../channels/index.js";
+import { loadTemplates, resolveConversation } from "../channels/index.js";
 import { startWhatsApp, type WhatsAppBackendName } from "./start-whatsapp.js";
 
 interface Args {
@@ -159,7 +159,9 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
     say(err instanceof Error ? err.message : String(err));
     return 2;
   }
-  const firstInput = args.input ?? (args.scripted ? conversationScript?.turns[0].text : undefined);
+  // A first turn that is a TAP is looked up by the intent the tap stands for, which is what the model is handed.
+  const firstTurn = args.scripted ? conversationScript?.turns[0] : undefined;
+  const firstInput = args.input ?? firstTurn?.text ?? (firstTurn?.reply ? declaredReplies(loadTemplates(agent)).get(firstTurn.reply.id)?.intent : undefined);
 
   // No model: replay the recorded scenario whose first turn is what the person said first.
   let transcript = args.transcript;
@@ -179,6 +181,7 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
   const startedAt = Date.now();
   try {
     if (args.channel === "whatsapp") {
+      s.conversation = conversationScript;
       return await startWhatsApp({
         agent,
         setup: s,