@codespar/cli 0.18.1 → 0.20.0

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

@@ -13,12 +13,22 @@
  * 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 { declaredReplies, type ProofBundle, type QuickReply, type WhatsAppTemplate } from "@codespar/agent-core";
+import { CORE_STRINGS, WHATSAPP_LANGUAGE, declaredReplies, type CoreStrings, type Locale, 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, DeliveryState, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../types.js";
 import { maskContact } from "../contact.js";
 import { SessionWindow, type SessionState } from "./session.js";
 
+/**
+ * How far along a message a status puts it. Status webhooks are not ordered:
+ * the emulator dispatches a send's own `sent` and `delivered` while a status
+ * posted meanwhile goes out between them, and Meta does not promise order
+ * either. A `delivered` that lands after a `failed` must not un-fail the
+ * message (#63), so `failed` ranks above everything, and a late `sent` does
+ * not rewind a `read`.
+ */
+const PROGRESS: Record<DeliveryState, number> = { queued: 0, sent: 1, delivered: 2, read: 3, failed: 4 };
+
 export interface WhatsAppChannelOptions {
   backend: ChannelBackend;
   conversation: Conversation;
@@ -52,6 +62,12 @@ export interface WhatsAppChannelOptions {
   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;
+  /**
+   * The conversation's locale. It picks the language of every template this
+   * channel sends and of the quick replies it reads a tap by, and the words of
+   * the operator's lines. Fixed for the conversation. Default pt-BR.
+   */
+  locale?: Locale | undefined;
 }
 
 export class WhatsAppChannel implements Channel {
@@ -61,7 +77,7 @@ export class WhatsAppChannel implements Channel {
   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. */
+  /** The furthest state the provider reported per message id (`PROGRESS`), this process. */
   private readonly delivery = new Map<string, DeliveryState>();
   /**
    * Failures reported for a message not yet in the log. A provider can post
@@ -71,10 +87,16 @@ export class WhatsAppChannel implements Channel {
    */
   private readonly earlyFailures = new Map<string, ChannelLogLine>();
 
+  /** Meta's language code for this conversation: the one every template send carries. */
+  readonly language: string;
+  private readonly text: CoreStrings;
+
   constructor(private readonly options: WhatsAppChannelOptions) {
     this.conversation = options.conversation;
+    this.language = WHATSAPP_LANGUAGE[options.locale ?? "pt-BR"];
+    this.text = CORE_STRINGS[options.locale ?? "pt-BR"];
     this.session = new SessionWindow(options.templates ?? [], options.session);
-    this.replies = declaredReplies(options.templates ?? []);
+    this.replies = declaredReplies(options.templates ?? [], this.language);
   }
 
   get backend(): string {
@@ -111,9 +133,9 @@ export class WhatsAppChannel implements Channel {
     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. */
+  /** The copy of a template declared in this conversation's language, for a caller about to send it. */
   declaredTemplate(name: string): WhatsAppTemplate | undefined {
-    return this.session.declared(name);
+    return this.session.declared(name, this.language);
   }
 
   async open(): Promise<void> {
@@ -160,7 +182,7 @@ export class WhatsAppChannel implements Channel {
           : undefined;
       if (refusal) {
         this.record({ ...base, kind: "reply", reply: tapped, refused: refusal });
-        this.options.say?.(`  [whatsapp] toque ignorado (${refusal.rule}): ${refusal.detail}`);
+        this.options.say?.(this.text.waTapIgnored(refusal.rule, refusal.detail));
         continue;
       }
       this.record({ ...base, kind: "reply", reply: tapped, text: declared!.intent });
@@ -182,7 +204,8 @@ export class WhatsAppChannel implements Channel {
    */
   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 known = this.delivery.get(status.message_id);
+    if (known === undefined || PROGRESS[status.status] > PROGRESS[known]) this.delivery.set(status.message_id, status.status);
     const line: ChannelLogLine = {
       at: this.options.now().toISOString(),
       direction: "status",
@@ -206,13 +229,11 @@ export class WhatsAppChannel implements Channel {
   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.say?.(this.text.waDeliveryFailed(status.message_id, codes, line.about ? `${line.about.execution_id} (${line.about.state})` : undefined));
     this.options.onDeliveryFailed?.(line);
   }
 
-  /** The latest status the provider reported for a message this process saw a status for. */
+  /** The furthest status the provider reported for a message this process saw a status for; a `failed` stays `failed`. */
   deliveryOf(messageId: string): DeliveryState | undefined {
     return this.delivery.get(messageId);
   }
@@ -234,6 +255,7 @@ export class WhatsAppChannel implements Channel {
       hours: this.options.hours,
       now: this.options.now,
       knownSubjects: this.options.knownSubjects,
+      locale: this.options.locale,
     };
 
     // The house rules first: a message the law refuses is not a message the provider should ever see.
@@ -241,15 +263,15 @@ export class WhatsAppChannel implements Channel {
     if (refusal) {
       const sent: SentMessage = { id: "", state: "failed", refused: refusal };
       this.logOutbound(body, sent);
-      this.options.say?.(`  [whatsapp] recusado (${refusal.rule}): ${refusal.detail}`);
+      this.options.say?.(this.text.waRefused(refusal.rule, refusal.detail));
       return sent;
     }
 
     // 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 buttons = body.kind === "template" ? this.session.declared(body.template, body.language)?.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}`);
+    if (sent.refused) this.options.say?.(this.text.waRefusedByBackend(sent.refused.rule, sent.refused.detail));
     if (sent.refused?.rule === "session_window_closed") this.session.observeProviderShut();
     this.logOutbound(outgoing, sent);
     return sent;
@@ -310,24 +332,24 @@ export class WhatsAppChannel implements Channel {
   private record(line: ChannelLogLine): void {
     this.lines.push(line);
     this.options.bundle?.channel({ ...line, channel: "whatsapp", backend: this.backend });
-    this.options.render?.(`  │ ${draw(line)}`);
+    this.options.render?.(`  │ ${draw(line, this.text)}`);
   }
 }
 
 /** 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 {
+function draw(line: ChannelLogLine, text: CoreStrings): 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:";
+  if (line.kind === "reply") return `${line.contact}: ${text.waTap(line.reply?.title ?? "?")}${line.refused ? text.waTapIgnoredMark(line.refused.rule) : ` -> ${line.text ?? ""}`}`;
+  const who = line.direction === "in" ? `${line.contact}:` : text.waShop;
   const what =
     line.kind === "instrument"
-      ? `[copia e cola] ${line.text ?? ""}`
+      ? `${text.waCopyPaste} ${line.text ?? ""}`
       : line.kind === "media"
-        ? "[imagem: QR Pix]"
+        ? text.waQrImage
         : line.kind === "template"
           ? line.text ?? "[template]"
           : line.text ?? "";
-  return line.refused ? `${who} (nao enviada: ${line.refused.rule}) ${what}` : `${who} ${what}`;
+  return line.refused ? `${who} ${text.waNotSent(line.refused.rule)} ${what}` : `${who} ${what}`;
 }
 
 function textOf(body: OutboundBody): string | undefined {

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

@@ -144,6 +144,7 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
       driver,
       say,
       render: options.render ?? say,
+      locale: s.locale,
       ...(options.script ? { script: options.script } : {}),
       ...(options.ask ? { ask: options.ask } : {}),
       ...(options.pinAt ? { pinAt: options.pinAt } : {}),
@@ -166,6 +167,8 @@ export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | {
     ...(options.session ? { session: options.session } : {}),
     ...(options.priorLines ? { priorLines: options.priorLines } : {}),
     onDeliveryFailed: (line) => recordDeliveryFailure(s, line),
+    // The run's locale, which for a poll is the conversation's recorded one: the templates go out in its language.
+    locale: s.locale,
   });
 
   return { channel, ...(driver ? { driver } : {}), ...(sessionKey ? { sessionKey } : {}) };

package/templates/hello-agent/packages/agent-runtime/src/channels/whatsapp/present.ts

@@ -11,21 +11,22 @@
  * its OWN message underneath, because a code inside a picture cannot be
  * copied and a code inside a paragraph cannot be tapped.
  */
-import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import { CORE_STRINGS, formatDay, type ChargeInstrument, type Execution, type Locale } from "@codespar/agent-core";
 import type { OutboundBody } from "../types.js";
 
-export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string): OutboundBody[] {
-  const money = new Intl.NumberFormat("pt-BR", { style: "currency", currency });
+export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string, locale: Locale = "pt-BR"): OutboundBody[] {
+  const text = CORE_STRINGS[locale];
+  const money = new Intl.NumberFormat(locale === "en" ? "en-US" : "pt-BR", { style: "currency", currency });
   const item = execution.items[instalment - 1];
   const count = execution.items.length;
   const bodies: OutboundBody[] = [
     {
       kind: "text",
       text: [
-        count > 1 ? `Parcela ${instalment}/${count}: ` : "",
+        count > 1 ? text.instalmentOf(instalment, count) : "",
         item ? money.format(item.amount / 100) : "",
-        instrument.due_date ? `, vence ${formatDate(instrument.due_date)}` : "",
-        ` — cobranca ${chargeId}`,
+        instrument.due_date ? text.dueOn(formatDay(instrument.due_date, locale)) : "",
+        text.chargeRef(chargeId),
       ].join(""),
     },
   ];
@@ -34,14 +35,9 @@ export function instrumentBodies(execution: Execution, instalment: number, charg
     bodies.push({ kind: "instrument", instrument: "pix_copy_paste", value: instrument.pix_copy_paste });
   }
   if (instrument.boleto_bank_line) {
-    bodies.push({ kind: "text", text: "Ou pelo boleto, linha digitavel:" });
+    bodies.push({ kind: "text", text: text.boletoLine });
     bodies.push({ kind: "instrument", instrument: "boleto_bank_line", value: instrument.boleto_bank_line });
   }
   return bodies;
 }
 
-/** `2026-09-30` -> `30/09/2026`. */
-export function formatDate(iso: string): string {
-  const [y, m, d] = iso.split("-");
-  return `${d}/${m}/${y}`;
-}

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

@@ -15,7 +15,7 @@
  * a code inside a picture cannot be copied and a code inside a paragraph
  * cannot be tapped.
  */
-import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import type { ChargeInstrument, Execution, NotRunLine } from "@codespar/agent-core";
 import { handleExecution, type TerminalOptions } from "../../terminal.js";
 import type { Setup } from "../../setup.js";
 import type { OutboundBody } from "../types.js";
@@ -42,6 +42,8 @@ export interface ConverseResult {
   replies: string[];
   toolCalls: Array<{ name: string; refused: boolean }>;
   executions: Execution[];
+  /** Lines a tool did not run, across every turn: the run's count needs them. */
+  notRun: NotRunLine[];
 }
 
 /** Keeps outbound messages in the order the run produced them, across await points. */
@@ -67,10 +69,11 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
   let toldOutcome = false;
   const replies: string[] = [];
   const toolCalls: Array<{ name: string; refused: boolean }> = [];
+  const notRun: NotRunLine[] = [];
   let turns = 0;
 
   const presentInstrument = (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument): Promise<void> => {
-    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency)) outbox.push(body);
+    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency, s.locale)) outbox.push(body);
     // Awaited by the poll: the person has the code in hand before the next look, not after the cycle closed.
     return outbox.drain();
   };
@@ -95,7 +98,7 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
   const runtime = s.makeRuntime();
   const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, terminalOptions));
 
-  say(`${s.manifest.manifest.name} ${s.manifest.manifest.version} — canal: whatsapp (${channel.backend}) — approval: ${s.mode} — trilho: ${s.railKind} — ${s.kit.labels.mandateWord} ${s.mandate.id}`);
+  say(s.coreStrings.waBanner(s.manifest.manifest.name, s.manifest.manifest.version, channel.backend, s.mode, s.railKind, s.strings.mandateWord, s.mandate.id));
 
   try {
     for (;;) {
@@ -104,6 +107,7 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
       turns += 1;
       const result = await loop.turn(message.text);
       toolCalls.push(...result.tool_calls);
+      notRun.push(...result.not_run);
       // Whatever the execution put in the conversation goes first: the QR before the sentence that explains it.
       await outbox.drain();
       if (result.reply.trim()) await channel.say(result.reply);
@@ -116,5 +120,5 @@ export async function converse(options: ConverseOptions): Promise<ConverseResult
     await channel.close();
   }
 
-  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId) };
+  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId), notRun };
 }

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

@@ -31,13 +31,15 @@ export interface SessionState {
 export type TemplateRefusal = { rule: string; detail: string } | undefined;
 
 export class SessionWindow {
-  private readonly templates: Map<string, WhatsAppTemplate>;
+  /** Every declared copy, by name: one per language, since Meta approves a template per (name, language). */
+  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]));
+    this.templates = new Map();
+    for (const t of templates) this.templates.set(t.name, [...(this.templates.get(t.name) ?? []), t]);
     this.lastInboundAt = initial?.lastInboundAt;
   }
 
@@ -67,9 +69,9 @@ export class SessionWindow {
     return this.remainingSeconds(now) > 0;
   }
 
-  /** The declaration, for a caller that has to build a send: the language is the registry's, never the caller's guess. */
-  declared(name: string): WhatsAppTemplate | undefined {
-    return this.templates.get(name);
+  /** The copy declared in `language`, for a caller that has to build a send. `undefined` when the name or that language was never declared. */
+  declared(name: string, language: string): WhatsAppTemplate | undefined {
+    return this.templates.get(name)?.find((t) => t.language === language);
   }
 
   /**
@@ -80,17 +82,18 @@ export class SessionWindow {
    * delivers nothing, so each is refused here instead.
    */
   refuse(body: { template: string; language: string; variables: readonly string[] }): TemplateRefusal {
-    const declared = this.templates.get(body.template);
-    if (!declared) {
+    const copies = this.templates.get(body.template);
+    if (!copies) {
       return {
         rule: "template_unknown",
         detail: `the agent declares no template named ${body.template}; Meta only delivers templates it approved, and this one was never registered here`,
       };
     }
-    if (declared.language !== body.language) {
+    const declared = copies.find((t) => t.language === body.language);
+    if (!declared) {
       return {
         rule: "template_language_unknown",
-        detail: `${body.template} is declared in ${declared.language}, not ${body.language}; a template approved in one language does not exist in another`,
+        detail: `${body.template} is declared in ${copies.map((t) => t.language).join(", ")}, not ${body.language}; a template approved in one language does not exist in another`,
       };
     }
     const expected = templateArity(declared.body);

package/templates/hello-agent/packages/agent-runtime/src/cli.ts

@@ -5,7 +5,11 @@
  */
 import { stderr } from "node:process";
 import { loadAgent, type Agent } from "./agent.js";
-import { readDotEnv } from "./setup.js";
+import { NotATestKeyError } from "@codespar/agent-core";
+import { readAgentEnv } from "./env.js";
+import { envFileOf, localeFlag, resolveRailKind } from "./setup.js";
+import { loadManifest, resolveLocale } from "@codespar/agent-core";
+import { join } from "node:path";
 import { check } from "./commands/check.js";
 import { decide } from "./commands/decide.js";
 import { runEval } from "./commands/eval.js";
@@ -42,8 +46,23 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
   }
   if (AGENTLESS.includes(command)) return verify(rest);
   const agent = await loadAgent(dir);
-  readDotEnv(agent.dir);
-  return run(agent, command, rest);
+  // The CLI's names for the deployment and the project are aliases of the kit's. Two that disagree stop a command that talks to the API; on the stub rail neither is read, and the run goes on.
+  const disagreement = readAgentEnv(agent.dir);
+  const railFlag = rest.includes("--rail") ? rest[rest.indexOf("--rail") + 1] : undefined;
+  if (disagreement && resolveRailKind(process.env, railFlag === "api" || railFlag === "stub" ? railFlag : undefined) === "api") {
+    stderr.write(disagreement.message + "\n");
+    return 1;
+  }
+  try {
+    return await run(agent, command, rest);
+  } catch (err) {
+    // A key refusal is the first thing a newcomer meets (#50): one sentence naming the file this agent reads, never a stack trace.
+    if (err instanceof NotATestKeyError) {
+      stderr.write(new NotATestKeyError(err.problem, envFileOf(agent.dir)).message + "\n");
+      return 1;
+    }
+    throw err;
+  }
 }
 
 async function run(agent: Agent, command: string, argv: string[]): Promise<number> {
@@ -56,7 +75,14 @@ async function run(agent: Agent, command: string, argv: string[]): Promise<numbe
         stderr.write(`${agent.slug}: this agent has no consent step (its policy is its own file, not a signed mandate)\n`);
         return 2;
       }
-      return agent.kit.consent({ agentDir: agent.dir, argv, say: (l) => void stderr.write(l + "\n") });
+      let locale;
+      try {
+        locale = resolveLocale(localeFlag(argv), loadManifest(join(agent.dir, "agent.yaml")).manifest);
+      } catch (err) {
+        stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+      }
+      return agent.kit.consent({ agentDir: agent.dir, argv, locale, say: (l) => void stderr.write(l + "\n") });
     }
     case "approve":
       return decide(agent, "approve", argv);

package/templates/hello-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/hello-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/hello-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/hello-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}`;
 }