@codespar/cli 0.18.1 → 0.20.0

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

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

@@ -6,18 +6,29 @@
  *
  * `--json` puts machine data on stdout (valid JSON, nothing else) and the
  * human messages on stderr.
+ *
+ * A one-shot prints, after the reply, what the run did as the engine counts
+ * it (`outcome.ts`), and exits by it: see `EXIT_CODES`.
  */
+import { statSync } from "node:fs";
 import { stderr, stdout } from "node:process";
 import { relative, resolve } from "node:path";
-import { NotATestKeyError, declaredReplies, isTestKey, loadManifest, resolveFixedClock, type ApprovalMode, type ChannelName } from "@codespar/agent-core";
+import { CORE_STRINGS, NotATestKeyError, WHATSAPP_LANGUAGE, declaredReplies, loadManifest, parseLocale, resolveLocale, testKeyProblem, resolveFixedClock, type ApprovalMode, type ChannelName, type Locale } 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 { envFileOf, 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 { loadTemplates, resolveConversation } from "../channels/index.js";
 import { startWhatsApp, type WhatsAppBackendName } from "./start-whatsapp.js";
+import { outcomeExitCode, refusalLine, sayOutcome } from "../outcome.js";
+
+const EXIT_CODES = `exit (--input): 0 nothing failed (settled, already paid, denied, expired or still open: the last line counts each payment); 1 a payment failed or a line was refused before a draft, and 1 wins over 3; 3 nothing failed and an execution of this run was left executing (npm run reconcile). A line an earlier run still holds is open and exits 0.`;
+
+function isFile(path: string): boolean {
+  return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
+}
 
 interface Args {
   input?: string;
@@ -40,6 +51,8 @@ interface Args {
   conversation?: string;
   /** Replay the conversation's turns instead of reading them from the keyboard. */
   scripted: boolean;
+  /** The language of what the code prints; absent means agent.yaml's `locale`, else pt-BR. */
+  locale?: Locale;
   help: boolean;
 }
 
@@ -92,6 +105,7 @@ export function parseArgs(argv: string[], awaitsPayer: boolean): Args {
       args.backend = v;
     } else if (a === "--conversation") args.conversation = next();
     else if (a === "--scripted") args.scripted = true;
+    else if (a === "--locale") args.locale = parseLocale(next());
     else if (a === "--help" || a === "-h") args.help = true;
     else throw new Error(`unknown argument ${a}`);
   }
@@ -109,10 +123,12 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
     return 2;
   }
   if (args.help) {
-    stderr.write(usage + "\n");
+    stderr.write(`${usage}\n${EXIT_CODES}\n`);
     return 0;
   }
   const say = (line: string) => stderr.write(line + "\n");
+  // Fixed for the run, and for a conversation: the proposal and its approval are asked in the same language.
+  const locale = resolveLocale(args.locale, loadManifest(join(agent.dir, "agent.yaml")).manifest);
 
   // A pinned instant makes the guardrails deterministic: the CI runs the fixture inside the declared hours whatever the hour is.
   let now: (() => Date) | undefined;
@@ -125,12 +141,19 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
 
   // Sandbox by construction: a live key dies here, before anything else runs.
   const railKind = resolveRailKind(process.env, args.rail);
-  if (railKind === "api" && !isTestKey(process.env["CODESPAR_API_KEY"])) {
-    say(new NotATestKeyError().message);
+  const keyProblem = railKind === "api" ? testKeyProblem(process.env["CODESPAR_API_KEY"]) : undefined;
+  if (keyProblem) {
+    say(new NotATestKeyError(keyProblem, envFileOf(agent.dir)).message);
+    return 1;
+  }
+
+  // A recording that is not there is said by its path, before a mandate is asked for or a run is opened.
+  if (args.transcript !== undefined && !isFile(args.transcript)) {
+    say(`no transcript at ${args.transcript}`);
     return 1;
   }
 
-  if (args.scenario) return runScenarioCommand(agent, args, railKind, say);
+  if (args.scenario) return runScenarioCommand(agent, args, railKind, locale, say);
 
   // A channel is a conversation, so the flags a one-shot and a scenario pack use have no meaning on one.
   if (args.channel === "whatsapp" && (args.input !== undefined || args.scenario !== undefined)) {
@@ -147,7 +170,7 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
   }
 
   if (agent.kit.ensureMandate) {
-    const ok = await agent.kit.ensureMandate({ agentDir: agent.dir, argv, say, railKind, oneShot: args.input !== undefined, ask: defaultAsk });
+    const ok = await agent.kit.ensureMandate({ agentDir: agent.dir, argv, locale, say, railKind, oneShot: args.input !== undefined, ask: defaultAsk });
     if (!ok) return 1;
   }
 
@@ -159,9 +182,9 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
     say(err instanceof Error ? err.message : String(err));
     return 2;
   }
-  // A first turn that is a TAP is looked up by the intent the tap stands for, which is what the model is handed.
+  // A first turn that is a TAP is looked up by the intent the tap stands for in the run's language, 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);
+  const firstInput = args.input ?? firstTurn?.text ?? (firstTurn?.reply ? declaredReplies(loadTemplates(agent), WHATSAPP_LANGUAGE[locale]).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;
@@ -175,7 +198,7 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
     }
   }
 
-  const s = setup(agent, { mode: args.mode, rail: railKind, provider, transcript, now, say });
+  const s = setup(agent, { mode: args.mode, rail: railKind, provider, transcript, now, say, locale });
   if (args.payer) s.payer?.behave(args.payer);
   const approver = { id: args.user ?? s.kit.labels.defaultUser, channel: "terminal" };
   const startedAt = Date.now();
@@ -207,18 +230,23 @@ export async function start(agent: Agent, argv: string[]): Promise<number> {
       handleExecution(execution, { setup: s, approver, decision: args.decision ?? "none", say, waitSeconds: args.wait, simulatePayer: args.simulatePayer, ...(args.json ? { tell: say } : {}) }),
     );
     const result = await loop.turn(args.input);
-    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    // Counted from the engine, printed whatever the reply says: a recorded reply cannot know what this run found.
+    const { executions, refusals, outcome, line } = sayOutcome(s, result.not_run);
+    // A request refused before a draft left no execution to describe: said here with the engine's own reason, or the terminal would be silent about it.
+    for (const refusal of refusals) say(refusalLine(refusal));
     const payload = s.kit.oneShotPayload({ setup: s, reply: result.reply, toolCalls: result.tool_calls, executions, startedAt });
-    if (args.json) stdout.write(JSON.stringify(payload) + "\n");
-    else stdout.write(result.reply + "\n");
-    return executions.some((e) => e.state === "executing") ? 3 : 0;
+    // `run_outcome`, not `outcome`: the payload is the kit's, and a kit may name a field of its own that.
+    if (args.json) stdout.write(JSON.stringify({ ...payload, run_outcome: outcome, refused_before_draft: refusals }) + "\n");
+    else stdout.write(`${result.reply}\n${line}\n`);
+    return outcomeExitCode(outcome, executions);
   } finally {
     closeTerminal();
     s.close();
   }
 }
 
-async function runScenarioCommand(agent: Agent, args: Args, railKind: RailKind, say: (l: string) => void): Promise<number> {
+async function runScenarioCommand(agent: Agent, args: Args, railKind: RailKind, locale: Locale, say: (l: string) => void): Promise<number> {
+  const text = CORE_STRINGS[locale];
   const scenario = loadScenario(agent, args.scenario!);
   const picksRail = agent.kit.scenarioRail === "requested";
   const rail: RailKind = picksRail ? railKind : "stub";
@@ -237,10 +265,13 @@ async function runScenarioCommand(agent: Agent, args: Args, railKind: RailKind,
       say: args.json ? () => undefined : say,
       ...(picksRail ? { tell: args.json ? () => undefined : (l: string) => void stdout.write(l + "\n") } : {}),
       waitSeconds: args.wait,
+      locale,
     });
     const check = checkScenario(scenario, run);
-    for (const reply of run.replies) say(`agente: ${reply}`);
-    say(check.ok ? `== ok — ${agent.settlement === "await-payer" ? `${run.cycle_seconds}s — ` : ""}bundle em ${relative(process.cwd(), run.bundle_dir)}` : `== FAIL: ${check.failures.join("; ")}`);
+    for (const reply of run.replies) say(text.scenarioReply(reply));
+    // Seconds are said only where a clock measured them. On the stub the clock is the scenario's, ticking a second per read: its "16s" is a count of reads in a run that took under one.
+    const measured = agent.settlement === "await-payer" && run.rail === "api" ? run.cycle_seconds : undefined;
+    say(check.ok ? text.scenarioOk(measured, relative(process.cwd(), run.bundle_dir)) : `== FAIL: ${check.failures.join("; ")}`);
     results.push({ mode, ok: check.ok, failures: check.failures, run });
   }
   if (args.json) stdout.write(JSON.stringify({ scenario: scenario.name, ...(picksRail ? { rail } : {}), results }) + "\n");