@codespar/cli 0.18.1 → 0.21.0

package/templates/collections-agent/packages/agent-runtime/src/commands/check.ts

@@ -1,13 +1,29 @@
 /**
  * `codespar-agent check [--json]`: the manifest-coherence gate of section 4.3.
+ *
+ * The files are the core's to check (`checkAgent`). The string tables are
+ * checked here, because they are code: the runner has the agent's kit loaded
+ * and the core, which reads files, does not.
  */
 import { stderr, stdout } from "node:process";
-import { checkAgent } from "@codespar/agent-core";
+import { CORE_STRINGS, checkAgent, tableGaps, type CheckFinding } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
+import type { AgentKit } from "../kit.js";
+
+/**
+ * Every key of the shared table and of the kit's, in every locale. A key that
+ * one locale lacks is a line an agent run in that locale would print as
+ * `undefined`; it fails here, before anybody runs it.
+ */
+export function checkStrings(kit: Pick<AgentKit, "strings">): CheckFinding[] {
+  return [...tableGaps("CORE_STRINGS", CORE_STRINGS), ...tableGaps("kit.strings", kit.strings)].map((message) => ({ level: "error" as const, code: "strings_incomplete", message }));
+}
 
 export function check(agent: Agent, argv: string[]): number {
   const json = argv.includes("--json");
-  const report = checkAgent(agent.dir);
+  const files = checkAgent(agent.dir);
+  const findings = [...files.findings, ...checkStrings(agent.kit)];
+  const report = { ...files, ok: findings.every((f) => f.level !== "error"), findings };
   if (json) stdout.write(JSON.stringify(report) + "\n");
   for (const f of report.findings) stderr.write(`${f.level === "error" ? "ERROR" : "warn "} ${f.code}: ${f.message}\n`);
   stderr.write(report.ok ? `check ok: ${report.agent} agrees with its agent.yaml\n` : `check FAILED for ${report.agent ?? "agent"}\n`);

package/templates/collections-agent/packages/agent-runtime/src/commands/decide.ts

@@ -6,8 +6,9 @@
  */
 import { relative } from "node:path";
 import { stderr, stdout } from "node:process";
+import { railErrorOf } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
-import { setup } from "../setup.js";
+import { localeFlag, setup } from "../setup.js";
 import { handleExecution } from "../terminal.js";
 
 export async function decide(agent: Agent, decision: "approve" | "deny", argv: string[]): Promise<number> {
@@ -16,13 +17,20 @@ export async function decide(agent: Agent, decision: "approve" | "deny", argv: s
   const user = argv.includes("--user") ? argv[argv.indexOf("--user") + 1] : undefined;
   const wait = awaitsPayer && argv.includes("--wait") ? Number(argv[argv.indexOf("--wait") + 1]) : undefined;
   const simulatePayer = awaitsPayer && argv.includes("--simulate-payer");
-  const executionId = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--user" && (!awaitsPayer || argv[i - 1] !== "--wait"));
+  const executionId = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--user" && argv[i - 1] !== "--locale" && (!awaitsPayer || argv[i - 1] !== "--wait"));
   const say = (l: string) => stderr.write(l + "\n");
+  let locale;
+  try {
+    locale = localeFlag(argv);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
   if (!executionId) {
-    say(`usage: npm run ${decision} <execution-id> [--user <id>]${awaitsPayer ? " [--wait <seconds>] [--simulate-payer]" : ""} [--json]`);
+    say(`usage: npm run ${decision} <execution-id> [--user <id>]${awaitsPayer ? " [--wait <seconds>] [--simulate-payer]" : ""} [--locale pt-BR|en] [--json]`);
     return 2;
   }
-  const s = setup(agent, { say, runId: `run_${decision}_${Date.now().toString(36)}` });
+  const s = setup(agent, { say, runId: `run_${decision}_${Date.now().toString(36)}`, locale });
   try {
     const execution = s.engine.get(executionId);
     if (!execution) {
@@ -48,6 +56,7 @@ export async function decide(agent: Agent, decision: "approve" | "deny", argv: s
           execution_id: final.id,
           state: final.state,
           reason: final.reason ?? null,
+          rail_error: railErrorOf(final),
           approval_id: final.approval_id ?? null,
           ...(awaitsPayer ? { charge_ids: final.outcomes.map((o) => o.transaction_id ?? null) } : {}),
           receipt_ids: final.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),

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

@@ -3,22 +3,27 @@
  * 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.
+ *
+ * Its proof bundles go to `runs/eval/`, apart from the runs a person made
+ * (`runs.ts`); `inspect` and `rerun` find them by run id all the same.
  */
 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";
+import { evalRunsDir } from "../runs.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 runsDir = evalRunsDir(agent);
 
   const adversarial = [];
   for (const name of listAdversarialCases(agent)) {
     if (only && only !== name) continue;
-    const result = await runAdversarialCase(agent, loadAdversarialCase(agent, name));
+    const result = await runAdversarialCase(agent, loadAdversarialCase(agent, name), { runsDir });
     adversarial.push(result);
     say(agent.kit.evalAdversarialLine?.(result) ?? adversarialLine(result));
   }
@@ -29,7 +34,7 @@ export async function runEval(agent: Agent, argv: string[]): Promise<number> {
     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" }));
+      const check = checkScenario(scenario, await runScenario(agent, scenario, { mode, rail: "stub", runsDir }));
       scenarios.push({
         name,
         mode,

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

@@ -7,12 +7,12 @@
  * 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 { existsSync, 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 { listRuns, openRun } from "../runs.js";
 import { assembleTimeline, renderHtml, renderText } from "../inspect.js";
 
 const USAGE = "usage: npm run inspect <run-id> [--json] [--html <file>]";
@@ -50,15 +50,15 @@ export function inspect(agent: Agent, argv: string[]): number {
   const runs = runsDir(agent);
   if (!runId) {
     say(USAGE);
-    say(available(runs));
+    say(available(agent));
     return 2;
   }
 
   // An unknown run id is a refusal a person can act on, never a stack trace.
-  const bundle = ProofBundle.open(runs, runId);
+  const bundle = openRun(agent, runId)?.bundle;
   if (!bundle) {
     say(`no proof bundle for run ${runId}: nothing at ${resolve(runs, runId)}`);
-    say(available(runs));
+    say(available(agent));
     return 1;
   }
 
@@ -87,14 +87,12 @@ export function inspect(agent: Agent, argv: string[]): number {
 }
 
 /** 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 {
+function available(agent: Agent): string {
+  const { dir: runs, ids, evalDir, evalCount } = listRuns(agent);
+  // The eval suite's runs are counted, not listed: they are found by id like any other, and there are dozens per pass.
+  const evalNote = evalCount > 0 ? `\n${evalCount} more from \`npm run eval\` in ${evalDir}, inspected by run id the same way` : "";
   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.`;
+  if (!ids.length) return `no runs yet in ${runs}. Run the agent once, then inspect the run id it printed.${evalNote}`;
   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")}`;
+  return `runs in ${runs}${ids.length > shown.length ? ` (newest ${shown.length} of ${ids.length})` : ""}:\n${shown.map((id) => `  ${id}`).join("\n")}${evalNote}`;
 }

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

@@ -29,7 +29,7 @@
  */
 import { stdout } from "node:process";
 import { relative } from "node:path";
-import { ProofBundle, type ChargeInstrument, type Execution } from "@codespar/agent-core";
+import { ProofBundle, isLocale, type ChargeInstrument, type Execution, type Locale } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
 import { runsDir, type Setup } from "../setup.js";
 import { followUp, waitForPayer } from "../terminal.js";
@@ -53,6 +53,8 @@ export interface PollWhatsAppOptions {
   payer?: "pays" | "expires" | "never" | undefined;
   now: () => Date;
   say: (line: string) => void;
+  /** `--locale`, when given. The conversation's recorded locale wins, and a flag that disagrees with it is refused. */
+  locale?: Locale | undefined;
 }
 
 /** How the outcome reached the person, or why it did not. */
@@ -97,14 +99,14 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   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`);
+    say(s.coreStrings.pollNoSubject(script.name));
     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}`);
+    else say(s.coreStrings.pollNothingWaiting(script.name));
     return 0;
   }
 
@@ -114,10 +116,22 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   // 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`);
+    say(s.coreStrings.pollNoBundle(mine.map((e) => e.run_id).join(", ")));
     return 1;
   }
 
+  // The conversation keeps the locale it was recorded in: the outcome is told
+  // in the language the person was spoken to in, template and all. A bundle
+  // written before the field existed records none, and the run's own stands.
+  const recorded = bundle.readMeta()?.["locale"];
+  if (isLocale(recorded)) {
+    if (options.locale !== undefined && options.locale !== recorded) {
+      say(s.coreStrings.pollLocaleConflict(script.name, recorded, options.locale));
+      return 2;
+    }
+    s.locale = recorded;
+  }
+
   const built = buildWhatsApp({
     agent,
     setup: s,
@@ -159,11 +173,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   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"
-      }`,
-    );
+    say(s.coreStrings.pollBanner(s.manifest.manifest.name, s.manifest.manifest.version, channel.backend, script.name, channel.sessionOpen ? Math.round(remaining / 60) : undefined));
     for (const execution of mine) {
       const sessionOpen = channel.sessionOpen;
       const result = await waitForPayer(execution.id, {
@@ -188,11 +198,8 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
         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}` : ""})`
-        }`,
-      );
+      const told = delivery.told ? (delivery.carrier === "template" ? s.coreStrings.pollToldByTemplate(delivery.template ?? "?", delivery.fallback === true) : s.coreStrings.pollToldByText) : s.coreStrings.pollNotTold(delivery.reason, delivery.detail);
+      say(`${closed.id}: ${closed.state}${closed.reason ? ` (${closed.reason})` : ""}${s.coreStrings.afterLooks(result.rounds, result.seconds, false)} — ${told}`);
     }
   } finally {
     await channel.close();
@@ -213,7 +220,7 @@ export async function pollWhatsApp(options: PollWhatsAppOptions): Promise<number
   };
 
   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)` : ""}`);
+  else say(s.coreStrings.waConversationSummary(channelSummary.log, undefined, channelSummary.messages_out, refused.length));
 
   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
@@ -267,7 +274,7 @@ function conversationRecord(agent: Agent, executions: readonly Execution[]): { b
  * 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);
+  for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency, s.locale)) await channel.send(body);
 }
 
 /**
@@ -298,7 +305,7 @@ async function tellOutcome(channel: WhatsAppChannel, s: Setup, execution: Execut
     // 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"));
+    if (sent.refused?.rule !== "session_window_closed") return confirmed(channel, sent, deliveryOf(s, sent, "text"));
     return tellByTemplate(channel, s, execution, { cursorHeld: true });
   }
   return tellByTemplate(channel, s, execution, { cursorHeld: false });
@@ -337,22 +344,23 @@ async function confirmed(channel: WhatsAppChannel, sent: SentMessage, delivery:
  * 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);
+  const chosen: { template: string; variables: string[]; fallback?: true } | undefined = s.kit.outcomeTemplate?.(execution, s.locale) ?? 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`,
+      detail: s.coreStrings.pollNoTemplateForOutcome(`${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`),
     };
   }
+  // The copy in the conversation's language: an English conversation is never sent the pt_BR template.
   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` };
+    return { told: false, reason: "no_template_for_outcome", detail: s.coreStrings.pollTemplateNotDeclared(`${chosen.template} (${channel.language})`) };
   }
   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));
+  s.engine.note("message.debtor", execution.id, { state: execution.state, reason: execution.reason ?? null, template: declared.name, language: declared.language, variables: chosen.variables, ...(chosen.fallback ? { fallback: true } : {}) });
+  return confirmed(channel, sent, deliveryOf(s, sent, "template", declared.name, chosen.fallback));
 }
 
 function fallbackOf(channel: WhatsAppChannel): { template: string; variables: string[]; fallback: true } | undefined {
@@ -360,8 +368,8 @@ function fallbackOf(channel: WhatsAppChannel): { template: string; variables: st
   return name ? { template: name, variables: [], fallback: true } : undefined;
 }
 
-function deliveryOf(sent: SentMessage, carrier: "text" | "template", template?: string, fallback?: boolean): Delivery {
+function deliveryOf(s: Setup, 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" };
+  if (sent.state === "failed") return { told: false, reason: "refused", detail: s.coreStrings.pollProviderRefused };
   return { told: true, carrier, ...(template ? { template } : {}), ...(fallback ? { fallback: true as const } : {}) };
 }

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

@@ -15,9 +15,9 @@
  */
 import { stderr, stdout } from "node:process";
 import { join } from "node:path";
-import { loadManifest, resolveFixedClock, type ChannelName } from "@codespar/agent-core";
+import { loadManifest, parseLocale, resolveFixedClock, type ChannelName, type Locale } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
-import { setup } from "../setup.js";
+import { inLocaleOf, 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";
@@ -30,6 +30,8 @@ const USAGE = `codespar-agent poll [options]
   --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
+  --locale pt-BR|en             the language of this command's lines. An outcome is told in the locale its run recorded,
+                                and --channel whatsapp refuses a --locale that disagrees with the conversation's
   --json                        machine output on stdout, everything else on stderr`;
 
 interface Args {
@@ -40,6 +42,7 @@ interface Args {
   simulatePayer: boolean;
   payer?: "pays" | "expires" | "never";
   now?: string;
+  locale?: Locale;
   json: boolean;
 }
 
@@ -73,6 +76,7 @@ export function parsePollArgs(argv: string[]): Args {
       args.payer = v;
     } else if (a === "--conversation") args.conversation = next();
     else if (a === "--now") args.now = next();
+    else if (a === "--locale") args.locale = parseLocale(next());
     else throw new Error(`unknown argument ${a}`);
   }
   if (args.channel !== "whatsapp" && (args.backend !== undefined || args.conversation !== undefined)) {
@@ -97,7 +101,7 @@ export async function poll(agent: Agent, argv: string[]): Promise<number> {
     return 2;
   }
 
-  const s = setup(agent, { say, runId: `run_poll_${Date.now().toString(36)}`, ...(now ? { now } : {}) });
+  const s = setup(agent, { say, runId: `run_poll_${Date.now().toString(36)}`, ...(now ? { now } : {}), ...(args.locale ? { locale: args.locale } : {}) });
   // 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.
@@ -115,6 +119,7 @@ export async function poll(agent: Agent, argv: string[]): Promise<number> {
         ...(args.payer ? { payer: args.payer } : {}),
         now: now ?? (() => new Date()),
         say,
+        ...(args.locale ? { locale: args.locale } : {}),
       });
     }
     // `behave` only changes the default for receivables the rail has not
@@ -129,8 +134,10 @@ export async function poll(agent: Agent, argv: string[]): Promise<number> {
     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);
+      // The payer is told in the locale of the run that issued the charge, which is where they were spoken to.
+      const told = inLocaleOf(s, open);
+      const r = await waitForPayer(open.id, { setup: told, approver: { id: s.kit.labels.defaultUser, channel: "terminal" }, say, tell, waitSeconds: args.wait, simulatePayer: args.simulatePayer });
+      announceOutcome(r.execution, told, 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 });

package/templates/collections-agent/packages/agent-runtime/src/commands/rerun.ts

@@ -8,11 +8,54 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { stderr, stdout } from "node:process";
-import { ProofBundle, type ApprovalMode, type Execution } from "@codespar/agent-core";
+import { isLocale, type ApprovalMode, type Execution } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
-import { runsDir, setup } from "../setup.js";
+import { setup } from "../setup.js";
+import { openRun } from "../runs.js";
 import { handleExecution } from "../terminal.js";
 
+/**
+ * A clock that starts where the original run did and moves a second per
+ * read, which is how the scenario and the adversarial runners keep theirs. Its
+ * first read is the original's `started_at`.
+ */
+function clockFrom(startedAt: Date): () => Date {
+  let at = startedAt.getTime() - 1000;
+  return () => new Date((at += 1000));
+}
+
+const MANDATE_STOPPED: Record<string, string> = {
+  mandate_revoked: "a mandate that was revoked",
+  mandate_paused: "a mandate that was paused",
+  org_paused: "an organization that paused every mandate",
+};
+
+/**
+ * What the original run met that only the world can do, read off its events.
+ * The rerun starts from an active mandate, a rail that answers and a payer
+ * that pays; a run that met anything else would be replayed as a different
+ * run and reported as one that DIFFERS, with nothing to say why.
+ */
+export function notReplayed(events: ReadonlyArray<Record<string, unknown>>): string[] {
+  const found = new Set<string>();
+  const last = new Map<string, string>();
+  const accepted = new Set<string>();
+  for (const event of events) {
+    const payload = (event["payload"] ?? {}) as { reason?: unknown; status?: unknown; to?: unknown };
+    const execution = typeof event["execution_id"] === "string" ? event["execution_id"] : undefined;
+    // An own key only: the reason is a string from a recording, and `constructor` is a key of every object.
+    const stopped = typeof payload.reason === "string" && Object.hasOwn(MANDATE_STOPPED, payload.reason) ? MANDATE_STOPPED[payload.reason] : undefined;
+    if (stopped && (event["type"] === "execution.transition" || event["type"] === "execution.refused_before_draft")) found.add(stopped);
+    // The engine writes all three for one uncertain dispatch; any of them is the run saying the rail did not answer.
+    if ((event["type"] === "rail.outcome" && payload.status === "uncertain") || event["type"] === "rail.uncertain" || event["type"] === "execution.uncertain") found.add("an uncertain answer from the rail");
+    if (event["type"] === "rail.outcome" && payload.status === "accepted" && execution) accepted.add(execution);
+    if (event["type"] === "execution.transition" && execution && typeof payload.to === "string") last.set(execution, payload.to);
+  }
+  // Issued and never closed: the charge was out when the run ended, and nobody paid it.
+  if ([...accepted].some((execution) => last.get(execution) === "executing")) found.add("a payer who had not paid when it ended");
+  return [...found];
+}
+
 export async function rerun(agent: Agent, argv: string[]): Promise<number> {
   const json = argv.includes("--json");
   const runId = argv.find((a) => !a.startsWith("--"));
@@ -21,17 +64,40 @@ export async function rerun(agent: Agent, argv: string[]): Promise<number> {
     say("usage: npm run rerun <run-id> [--json]");
     return 2;
   }
-  const original = ProofBundle.open(runsDir(agent), runId);
-  if (!original) {
+  const found = openRun(agent, runId);
+  const original = found?.bundle;
+  if (!found || !original) {
     say(`no bundle at runs/${runId}`);
     return 1;
   }
   const meta = original.readMeta() ?? {};
+  const startedAt = typeof meta["started_at"] === "string" && Number.isFinite(Date.parse(meta["started_at"])) ? new Date(meta["started_at"]) : undefined;
   const mode = (meta["mode"] as ApprovalMode | undefined) ?? "human";
   const events = original.readEvents();
-  const originalTrail = events.filter((e) => e["type"] === "execution.transition").map((e) => (e["payload"] as { to: string }).to);
-  const originalDecisions = events.filter((e) => e["type"] === "approval.created").map((e) => ((e["payload"] as { approver: { type: string } }).approver.type === "person" ? "approve" : "mandate"));
-  const userTurns = original.readTranscript().filter((l) => l.kind === "user").map((l) => l["text"] as string);
+  const transitions = events.filter((e) => e["type"] === "execution.transition").map((e) => ({ execution: e["execution_id"] as string, ...(e["payload"] as { from: string; to: string }) }));
+  const originalTrail = transitions.map((t) => t.to);
+  // What the original did with each approval it asked for, in the order it asked: approved it, denied it, or left it open. A run that stopped at `awaiting_approval` (a one-shot with no --approve or --deny, an adversarial case that only has to escalate) is replayed to the same place, not decided on its behalf.
+  const asked = transitions.flatMap((t, i) => (t.to === "awaiting_approval" ? [transitions.slice(i + 1).find((n) => n.execution === t.execution)?.to] : []));
+  // Nobody decides an approval that expired either: the rerun's clock does, or the sequences differ and the last line says so.
+  const originalDecisions = asked.map((next) => (next === "approved" ? "approve" : next === "denied" ? "deny" : "none"));
+  const leftOpen = asked.filter((next) => next === undefined).length;
+  const transcript = original.readTranscript();
+  // The transcript is the model's side, and replaying it is all a rerun does. A run that never asked the model recorded no step to replay: an adversarial case of `kind: events` drives rail deliveries and writes no transcript at all.
+  if (!transcript.some((l) => l.kind === "assistant_step")) {
+    const error = `runs/${runId} has no model turn in transcript.jsonl, so there is nothing to replay`;
+    if (json) stdout.write(JSON.stringify({ run_id: runId, error }) + "\n");
+    say(error);
+    return 1;
+  }
+  // What the world did in the original is not in the transcript, and a rerun that ignores it pays what the original denied. It is said by name, before anything is replayed.
+  const unreplayed = notReplayed(events);
+  if (unreplayed.length > 0) {
+    const error = `runs/${runId} cannot be compared with a rerun: it met ${unreplayed.join(", and ")}, which a rerun does not replay`;
+    if (json) stdout.write(JSON.stringify({ run_id: runId, error, not_replayed: unreplayed }) + "\n");
+    say(error);
+    return 1;
+  }
+  const userTurns = transcript.filter((l) => l.kind === "user").map((l) => l["text"] as string);
   const transcriptPath = join(original.dir, "transcript.jsonl");
   const plan = agent.kit.rerunPlan?.(events) ?? {};
 
@@ -40,16 +106,22 @@ export async function rerun(agent: Agent, argv: string[]): Promise<number> {
     rail: "stub",
     provider: "replay",
     transcript: transcriptPath,
-    runId: `${runId}_rerun_${Date.now().toString(36)}`,
+    runId: `${original.runId}_rerun_${Date.now().toString(36)}`,
+    // Beside the run it replays: the rerun of an eval run stays with the eval runs.
+    runsDir: found.runsDir,
     stateDir: mkdtempSync(join(tmpdir(), `${agent.slug}-rerun-`)),
     stubRail: plan.stubRail,
+    // The original's clock, from where it started: a rule on a due date or on the hours of service decides today what it decided then.
+    ...(startedAt ? { now: clockFrom(startedAt) } : {}),
     say,
+    // The recording's locale, so the rerun's refusal details read as the original's did.
+    ...(isLocale(meta["locale"]) ? { locale: meta["locale"] } : {}),
   });
   try {
     let decisionIndex = 0;
     const runtime = s.makeRuntime();
     const loop = s.makeLoop(runtime, (execution: Execution) => {
-      const decision = execution.state === "awaiting_approval" ? (originalDecisions[decisionIndex++] === "approve" ? "approve" : "deny") : "none";
+      const decision = execution.state === "awaiting_approval" ? (originalDecisions[decisionIndex++] ?? "deny") : "none";
       return handleExecution(execution, {
         setup: s,
         approver: { id: "usr_rerun", channel: "terminal" },
@@ -78,7 +150,8 @@ export async function rerun(agent: Agent, argv: string[]): Promise<number> {
         }) + "\n",
       );
     }
-    say(same ? `rerun ok: ${trail.length} transition(s), same sequence as ${runId}` : `rerun DIFFERS: original ${JSON.stringify(originalTrail)} vs rerun ${JSON.stringify(trail)}`);
+    const open = leftOpen > 0 ? `; ${leftOpen} execution(s) left in awaiting_approval, as the original left ${leftOpen === 1 ? "it" : "them"}` : "";
+    say(same ? `rerun ok: ${trail.length} transition(s), same sequence as ${runId}${open}` : `rerun DIFFERS: original ${JSON.stringify(originalTrail)} vs rerun ${JSON.stringify(trail)}`);
     return same ? 0 : 1;
   } finally {
     s.close();

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

@@ -6,7 +6,7 @@
  * ones expire.
  */
 import { stderr, stdout } from "node:process";
-import type { Execution } from "@codespar/agent-core";
+import { railErrorOf, type Execution } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
 import { setup } from "../setup.js";
 import { followUp } from "../terminal.js";
@@ -37,6 +37,7 @@ export async function resume(agent: Agent, argv: string[]): Promise<number> {
         state: e.state,
         ...(awaitsPayer ? { reason: e.reason ?? null } : {}),
         detail: e.detail ?? null,
+        rail_error: railErrorOf(e),
         ...(awaitsPayer ? { charge_ids: e.outcomes.map((o) => o.transaction_id ?? null) } : {}),
         receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
       }));

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

@@ -14,6 +14,7 @@ import { stdout } from "node:process";
 import { relative } from "node:path";
 import type { ConversationScript } from "@codespar/agent-core";
 import type { Agent } from "../agent.js";
+import { outcomeExitCode, refusalLine, sayOutcome } from "../outcome.js";
 import type { Setup } from "../setup.js";
 import { defaultAsk } from "../terminal.js";
 import { converse } from "../channels/whatsapp/run.js";
@@ -116,19 +117,23 @@ export async function startWhatsApp(options: StartWhatsAppOptions): Promise<numb
     ...(cost ? { simulated_cost: cost } : {}),
   };
 
+  // The same count, refusals and exit code as the terminal's one-shot: the channel changes who is told, not what the run did.
+  const { executions, refusals, outcome, line } = sayOutcome(s, result.notRun);
+  for (const refusal of refusals) say(refusalLine(refusal));
   if (options.json) {
     const payload = s.kit.oneShotPayload({
       setup: s,
       reply: result.replies[result.replies.length - 1] ?? "",
       toolCalls: result.toolCalls,
-      executions: result.executions,
+      executions,
       startedAt: options.startedAt,
     });
-    stdout.write(JSON.stringify({ ...payload, channel: channelSummary }) + "\n");
+    stdout.write(JSON.stringify({ ...payload, run_outcome: outcome, refused_before_draft: refusals, channel: channelSummary }) + "\n");
   } else {
-    say(`conversa em ${channelSummary.log} — ${channelSummary.messages_in} recebida(s), ${channelSummary.messages_out} enviada(s)${refused.length ? `, ${refused.length} recusada(s)` : ""}`);
-    if (cost) say(`custo simulado desta conversa nas regras da Meta: ${cost.total.toFixed(4)} ${cost.currency} (conta do emulador, nao nossa)`);
+    say(line);
+    say(s.coreStrings.waConversationSummary(channelSummary.log, channelSummary.messages_in, channelSummary.messages_out, refused.length));
+    if (cost) say(s.coreStrings.waSimulatedCost(cost.total.toFixed(4), cost.currency));
   }
 
-  return result.executions.some((e) => e.state === "executing") ? 3 : 0;
+  return outcomeExitCode(outcome, executions);
 }