@codespar/cli 0.18.0 → 0.20.0

package/templates/bills-agent/packages/agent-runtime/src/scenarios.ts

@@ -10,9 +10,10 @@ import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { z } from "zod";
-import type { ApprovalMode, Execution } from "@codespar/agent-core";
+import type { ApprovalMode, Execution, Locale, StubChargeRailOptions, StubRailOptions } from "@codespar/agent-core";
 import type { Agent } from "./agent.js";
 import type { RailKind } from "./kit.js";
+import { draftRefusals } from "./outcome.js";
 import { setup, type Setup } from "./setup.js";
 import { announceOutcome, followUp, handleExecution } from "./terminal.js";
 
@@ -84,14 +85,33 @@ export interface ScenarioRun {
   run_id: string;
   bundle_dir: string;
   replies: string[];
-  executions: Array<{ id: string; state: string; reason: string | null; trigger: string | null; total: number; trail: string[]; charge_ids: string[]; receipt_ids: string[] }>;
+  executions: Array<{
+    id: string;
+    state: string;
+    reason: string | null;
+    trigger: string | null;
+    total: number;
+    trail: string[];
+    charge_ids: string[];
+    receipt_ids: string[];
+    /**
+     * A receivable that settled: whether a payable instrument (a Pix or a boleto line) was SEEN before anything paid it.
+     * `null` for anything that is not a settled receivable. `false` means the order settled on something nobody could
+     * have paid, which is how a failed issuance read as a closed cycle on staging (OPEN_QUESTIONS §63).
+     */
+    payable_seen: boolean | null;
+  }>;
   refused_before_draft: number;
   receipts: number;
   settled_total: number;
   charges_issued: number;
   debtor_messages: number;
-  /** Seconds from the first issuance to the last terminal state (wall clock on the API; the fake clock's ticks on the stub). */
-  cycle_seconds: number;
+  /**
+   * Seconds from the first issuance to the last terminal state (wall clock on the API; the fake clock's ticks on the stub).
+   * `null` when there was no real cycle to time: nothing was issued, nothing closed, or a receivable settled with no
+   * payable instrument seen first.
+   */
+  cycle_seconds: number | null;
   payer_calls: string[];
 }
 
@@ -127,6 +147,10 @@ export interface RunScenarioOptions {
   say?: (line: string) => void;
   tell?: (line: string) => void;
   waitSeconds?: number | undefined;
+  /** Test only: stub rail options merged over the scenario's, to script an issuer the packs do not (an error, an unpayable settlement). */
+  stubRail?: StubRailOptions | StubChargeRailOptions;
+  /** The locale of the lines the run prints. The pack's assertions are on states, never on wording, so it passes in either. */
+  locale?: Locale | undefined;
 }
 
 export async function runScenario(agent: Agent, scenario: Scenario, options: RunScenarioOptions): Promise<ScenarioRun> {
@@ -149,7 +173,8 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
     runsDir: options.runsDir ?? join(agent.dir, "runs"),
     stateDir,
     ...(rail === "stub" ? { now: tick } : {}),
-    ...(scenario.stub_refuse_payees.length > 0 ? { stubRail: { refusePayees: scenario.stub_refuse_payees } } : {}),
+    ...(options.locale ? { locale: options.locale } : {}),
+    ...(scenario.stub_refuse_payees.length > 0 || options.stubRail ? { stubRail: { ...(scenario.stub_refuse_payees.length > 0 ? { refusePayees: scenario.stub_refuse_payees } : {}), ...(options.stubRail ?? {}) } } : {}),
     say,
   });
   const stub = s.rail as { armUncertainOnce?: () => void };
@@ -186,7 +211,7 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
       });
       const result = await loop.turn(turn.input);
       replies.push(result.reply);
-      refusedBeforeDraft += s.store.listEvents({ run_id: s.runId }).filter((e) => e.type === "execution.refused_before_draft").length - refusedBeforeDraft;
+      refusedBeforeDraft = draftRefusals(s.store, s.runId).length;
       if (turn.payer === "late") for (const e of s.engine.list({ state: "executing" })) if (!before.has(e.id)) late.push(e.id);
     }
     // A late payer pays after the conversation ended (the receivable was in flight while the world changed).
@@ -219,6 +244,8 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
       if (e.type === "sandbox_payer") payerCalls.push(String((e.payload as { detail: string }).detail));
     }
     const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    const payableSeen = new Map(executions.map((e) => [e.id, awaitsPayer ? payableSeenBeforePayment(e, events) : null]));
+    const cycleIsReal = firstIssued !== undefined && lastClosed !== undefined && [...payableSeen.values()].every((seen) => seen !== false);
     return {
       scenario: scenario.name,
       mode: options.mode,
@@ -235,13 +262,14 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
         trail: e.history.map((h) => h.to),
         charge_ids: e.outcomes.map((o) => o.transaction_id).filter((x): x is string => typeof x === "string"),
         receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id as string),
+        payable_seen: payableSeen.get(e.id) ?? null,
       })),
       refused_before_draft: refusedBeforeDraft,
       receipts: s.bundle.listReceipts().length,
       settled_total: executions.filter((e) => e.state === "settled").reduce((sum, e) => sum + e.total, 0),
       charges_issued: events.filter((e) => e.type === "rail.outcome" && (e.payload as { status: string }).status === "accepted").length,
       debtor_messages: events.filter((e) => e.type === "message.debtor").length,
-      cycle_seconds: firstIssued !== undefined && lastClosed !== undefined ? Math.round(((lastClosed - firstIssued) / 1000) * 10) / 10 : 0,
+      cycle_seconds: cycleIsReal ? Math.round(((lastClosed! - firstIssued!) / 1000) * 10) / 10 : null,
       payer_calls: payerCalls,
     };
   } finally {
@@ -249,6 +277,20 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
   }
 }
 
+/**
+ * For a receivable that settled: was a payable instrument (`charge.instrument` with `payable: true`) recorded for it BEFORE the
+ * first thing that paid it (the sandbox payer's call, `commerce.charge.paid`, or the transition to `settled`)? `null` for an
+ * execution that is not a settled receivable.
+ */
+export function payableSeenBeforePayment(execution: Execution, events: ReadonlyArray<{ seq: number; execution_id: string | null; type: string; payload: unknown }>): boolean | null {
+  if (execution.state !== "settled") return null;
+  const own = events.filter((e) => e.execution_id === execution.id).sort((a, b) => a.seq - b.seq);
+  if (!own.some((e) => e.type === "rail.outcome" && (e.payload as { status?: string }).status === "accepted")) return null;
+  const paid = own.find((e) => e.type === "sandbox_payer" || e.type === "commerce.charge.paid" || (e.type === "execution.transition" && (e.payload as { to?: string }).to === "settled"));
+  if (!paid) return null;
+  return own.some((e) => e.seq < paid.seq && e.type === "charge.instrument" && (e.payload as { payable?: boolean }).payable === true);
+}
+
 function applyHook(s: Setup, hook: "revoke_mandate" | "pause_all" | undefined): void {
   if (hook === "revoke_mandate") s.gate.revoke(s.mandate.id, "revoked mid-run by the scenario");
   if (hook === "pause_all") s.gate.pauseAll();
@@ -267,7 +309,12 @@ export function checkScenario(scenario: Scenario, run: ScenarioRun): ScenarioChe
     if (expect.settled_total !== undefined && run.settled_total !== expect.settled_total) failures.push(`settled_total ${run.settled_total} != ${expect.settled_total}`);
     if (expect.charges_issued !== undefined && run.charges_issued !== expect.charges_issued) failures.push(`charges_issued ${run.charges_issued} != ${expect.charges_issued}`);
     if (expect.debtor_messages !== undefined && run.debtor_messages !== expect.debtor_messages) failures.push(`debtor_messages ${run.debtor_messages} != ${expect.debtor_messages}`);
-    if (expect.max_cycle_seconds !== undefined && run.rail === "api" && run.cycle_seconds > expect.max_cycle_seconds) failures.push(`cycle_seconds ${run.cycle_seconds} > ${expect.max_cycle_seconds}`);
+    if (expect.max_cycle_seconds !== undefined && run.rail === "api" && run.cycle_seconds !== null && run.cycle_seconds > expect.max_cycle_seconds) failures.push(`cycle_seconds ${run.cycle_seconds} > ${expect.max_cycle_seconds}`);
+    if (expect.max_cycle_seconds !== undefined && run.rail === "api" && run.cycle_seconds === null && !run.executions.some((e) => e.payable_seen === false)) failures.push("cycle_seconds: no cycle was measured");
+  }
+  // Every run, every rail: a receivable that settled on an instrument nobody saw is not a closed cycle, whatever state it reached.
+  for (const e of run.executions) {
+    if (e.payable_seen === false) failures.push(`no_payable_instrument: ${e.id} settled on ${e.charge_ids.join(", ") || "a receivable"} with no payable instrument seen before the payment`);
   }
   // Every run, every mode: nothing reaches executing without an approval artifact carrying its hash.
   return { ok: failures.length === 0, mode: run.mode, failures, run };

package/templates/bills-agent/packages/agent-runtime/src/setup.ts

@@ -5,7 +5,7 @@
  * rail, the tool handlers and the policy extension, through its kit.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import {
   AgentLoop,
   ExecutionEngine,
@@ -19,7 +19,13 @@ import {
   loadToolsFile,
   newRunId,
   resolveFixedClock,
+  resolveLocale,
+  isLocale,
+  parseLocale,
+  CORE_STRINGS,
   type AgentRuntime,
+  type CoreStrings,
+  type Locale,
   type ApprovalMode,
   type ConversationScript,
   type Execution,
@@ -32,15 +38,30 @@ import {
   type StubRailOptions,
   type ToolContext,
   type ToolHandler,
+  CODESPAR_KEY_PLACEHOLDER,
 } from "@codespar/agent-core";
 import { AnthropicRuntime } from "@codespar/agent-core/providers/anthropic";
 import type { ApiClient } from "@codespar/sdk";
 import { envName, type Agent } from "./agent.js";
-import type { AgentKit, RailKind, SandboxPayer, Settlement } from "./kit.js";
+import type { AgentKit, KitStrings, RailKind, SandboxPayer, Settlement } from "./kit.js";
 
 /** The `.env.example` placeholder counts as no key: a copied example must replay, not call Anthropic with a fake key. */
 export const ANTHROPIC_KEY_PLACEHOLDER = "sk-ant-your_key_here";
-export const CODESPAR_KEY_PLACEHOLDER = "csk_test_your_key_here";
+export { CODESPAR_KEY_PLACEHOLDER };
+
+/**
+ * The `.env` an agent reads (`readDotEnv(agent.dir)`), as a person would type
+ * it from where they ran the command: relative when it is below, absolute when
+ * it is not. `npm run` moves a workspace script into the agent's directory, so
+ * where the PERSON ran it is `INIT_CWD`, which npm sets; `npm run consent` at
+ * the root names `agents/bills-agent/.env`, not `.env`. The key refusals name
+ * this path, never a guess (#50).
+ */
+export function envFileOf(agentDir: string, cwd: string = process.env["INIT_CWD"] || process.cwd()): string {
+  const path = join(agentDir, ".env");
+  const rel = relative(cwd, path);
+  return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? path : rel;
+}
 
 export type ProviderKind = "anthropic" | "replay";
 
@@ -71,6 +92,8 @@ export interface SetupOptions {
   mandate?: Mandate | undefined;
   env?: NodeJS.ProcessEnv;
   say?: ((line: string) => void) | undefined;
+  /** `--locale`. Absent: the manifest's `locale`, else pt-BR. */
+  locale?: Locale | undefined;
 }
 
 export interface Setup {
@@ -97,6 +120,18 @@ export interface Setup {
   system: string;
   handlers: Record<string, ToolHandler>;
   tools: ReturnType<typeof loadToolsFile>;
+  /**
+   * The language of what the code prints in this run. Fixed at setup, and
+   * recorded in the bundle's `run.json`. The one command that changes it is
+   * `poll --channel whatsapp`, which sets it to the locale the conversation
+   * was recorded in before it says anything, so a conversation that started
+   * in one language is not told its outcome in the other.
+   */
+  locale: Locale;
+  /** The kit's words in `locale`. */
+  readonly strings: KitStrings;
+  /** The words every agent shares, in `locale`. */
+  readonly coreStrings: CoreStrings;
   /**
    * The conversation this run is bound to, when a channel binds one (WhatsApp):
    * its contact and its subject. Set by the channel's start, read by a kit
@@ -144,6 +179,7 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
   const tools = loadToolsFile(manifest.resolvePath(manifest.manifest.tools));
   const system = readFileSync(join(agent.dir, "SYSTEM_PROMPT.md"), "utf8");
   const mode: ApprovalMode = options.mode ?? manifest.manifest.default_approval;
+  const locale = resolveLocale(options.locale, manifest.manifest);
   if (!manifest.manifest.approval.includes(mode)) throw new Error(`agent.yaml does not support approval: ${mode}`);
 
   // <PREFIX>_STATE_DIR / <PREFIX>_RUNS_DIR exist for the restart test, which drives a child process over a scratch state.
@@ -174,9 +210,10 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
   const bundle = new ProofBundle(runs, runId);
   bundle.mandateSnapshot(mandate);
   // Section 11: mode, rail and mandate id. The VERSION rides with the id, so a reader knows which signing of the mandate authorised the run without opening the snapshot.
-  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, mandate_version: mandate.version, started_at: (now ?? (() => new Date()))().toISOString() });
+  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, mandate_version: mandate.version, locale, started_at: (now ?? (() => new Date()))().toISOString() });
 
-  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails, store });
+  // Read at call time, because `poll --channel whatsapp` may move the run to the conversation's recorded locale after setup.
+  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails, store, locale: () => s.locale });
   const engine = new ExecutionEngine({
     store,
     rail,
@@ -223,6 +260,13 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
     system,
     handlers: {},
     tools,
+    locale,
+    get strings() {
+      return agent.kit.strings[this.locale];
+    },
+    get coreStrings() {
+      return CORE_STRINGS[this.locale];
+    },
     makeRuntime,
     makeLoop: (runtime, onExecution, onBatch) => new AgentLoop({ runtime, tools, handlers: s.handlers, system, bundle, engine, onExecution, ...(onBatch ? { onBatch } : {}), ...(now ? { clock: now } : {}) }),
     close: () => store.close(),
@@ -231,6 +275,32 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
   return s;
 }
 
+/** `--locale <pt-BR|en>` out of a command's argv, validated. `undefined` when absent. */
+export function localeFlag(argv: readonly string[]): Locale | undefined {
+  const at = argv.indexOf("--locale");
+  if (at < 0) return undefined;
+  const value = argv[at + 1];
+  if (value === undefined) throw new Error("--locale needs a value");
+  return parseLocale(value);
+}
+
+/** The locale the run `runId` recorded in its bundle, if the bundle is here and records one. */
+export function recordedLocale(agent: Agent, runId: string, env: NodeJS.ProcessEnv = process.env): Locale | undefined {
+  const locale = ProofBundle.open(runsDir(agent, env), runId)?.readMeta()?.["locale"];
+  return isLocale(locale) ? locale : undefined;
+}
+
+/**
+ * The same setup, speaking the locale the run that created `execution`
+ * recorded. For a command that tells an outcome days after the run that
+ * proposed it (`poll`, `webhook`): the counterparty is told in the language
+ * they were spoken to in, whatever this command's own locale is.
+ */
+export function inLocaleOf(s: Setup, execution: Execution): Setup {
+  const locale = recordedLocale(s.agent, execution.run_id);
+  return locale === undefined || locale === s.locale ? s : (Object.create(s, { locale: { value: locale } }) as Setup);
+}
+
 export class NoMandateError extends Error {
   constructor() {
     super("no signed mandate yet: run `npm run consent -- --yes` first (or `npm start` without --input, which starts the consent when a test key is present)");

package/templates/bills-agent/packages/agent-runtime/src/terminal.ts

@@ -2,15 +2,18 @@
  * The terminal channel: what `codespar-agent start` opens. No account, no
  * server. It shows what the core decided, asks the person when an execution
  * is awaiting approval, and prints where the sealed outcome landed. The
- * words are the agent's (`kit.labels`, `kit.describeExecution`); the order
- * of the gates is the runner's and is the same for every agent.
+ * words are the agent's (`kit.strings`, `kit.describeExecution`) and the
+ * shared ones (`CORE_STRINGS`), in the run's locale; the order of the gates
+ * is the runner's and is the same for every agent, and so is what an answer
+ * decides: the parsers below read both languages whatever the locale.
  */
 import { createInterface } from "node:readline/promises";
 import { stdin, stderr, stdout } from "node:process";
 import { relative } from "node:path";
-import type { AgentRuntime, BatchGesture, BatchPresentation, ChargeInstrument, Execution } from "@codespar/agent-core";
+import { formatBRL, railErrorOf, type AgentRuntime, type BatchGesture, type BatchPresentation, type ChargeInstrument, type Execution, type NotRunLine } from "@codespar/agent-core";
 import { pollUntilClosed, type PollResult } from "./poll.js";
-import type { Setup } from "./setup.js";
+import { draftRefusals, refusalLine, sayOutcome } from "./outcome.js";
+import { inLocaleOf, type Setup } from "./setup.js";
 
 export interface TerminalOptions {
   setup: Setup;
@@ -69,7 +72,7 @@ export async function followUp(execution: Execution, setup: Setup, say: (line: s
 
 function receiptLines(execution: Execution, setup: Setup, say: (line: string) => void): void {
   for (const outcome of execution.outcomes) {
-    if (outcome.receipt_id) say(`  ${setup.kit.labels.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+    if (outcome.receipt_id) say(`  ${setup.strings.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
   }
 }
 
@@ -78,7 +81,8 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
   const { setup, approver } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
   const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
-  const labels = setup.kit.labels;
+  const words = setup.strings;
+  const text = setup.coreStrings;
   const engine = setup.engine;
 
   for (const line of describeExecution(execution, setup)) say(line);
@@ -91,42 +95,43 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
     } else {
       let decision = options.decision;
       if (!decision) {
-        if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
+        if (current.blocking_reasons.length > 0) say(text.onlyDeny);
         const ask = options.ask ?? defaultAsk;
-        const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
-        decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
+        decision = parseApproval(await ask(words.approveQuestion));
       }
       if (decision === "approve") current = engine.approve(current.id, approver);
       else if (decision === "deny") current = engine.deny(current.id, approver);
       else {
-        say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
+        say(text.leftAwaiting);
         return current;
       }
     }
-    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    say(transitionLine(current));
   }
 
   // An agent that issues on request (`executeOnApproval: false`) leaves the approved execution for its own tool to issue.
   if (current.state === "approved" && setup.kit.executeOnApproval !== false) {
     current = await engine.execute(current.id);
-    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    say(transitionLine(current));
     if (setup.settlement === "immediate") {
       receiptLines(current, setup, say);
-      if (current.state === "executing") say(labels.uncertainDispatch);
+      if (current.state === "executing") say(words.uncertainDispatch);
     }
   }
 
   if (setup.settlement === "await-payer") {
+    // The counterparty is spoken to in the locale of the run that proposed this execution (`npm run approve` is a later command); the operator's lines stay in this one's.
+    const counterparty = inLocaleOf(setup, current);
     if (current.state === "executing" && current.reason === "awaiting_settlement") {
-      const result = await waitForPayer(current.id, options);
+      const result = await waitForPayer(current.id, { ...options, setup: counterparty });
       current = result.execution;
-      say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""} apos ${result.rounds} consulta(s), ${result.seconds}s${result.timed_out ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`);
+      say(`${transitionLine(current)}${text.afterLooks(result.rounds, result.seconds, result.timed_out)}`);
       receiptLines(current, setup, say);
     } else if (current.state === "executing") {
-      say(labels.uncertainDispatch);
+      say(words.uncertainDispatch);
     }
     const told = current;
-    announceOutcome(told, setup, (line) => tell(line, told));
+    announceOutcome(told, counterparty, (line) => tell(line, told));
     await followUp(current, setup, say);
   }
   return current;
@@ -150,6 +155,16 @@ function decideByGesture(execution: Execution, gesture: BatchGestureRecord, setu
   return engine.approve(execution.id, approver);
 }
 
+/**
+ * What the person answered to the per-line question. Yes is s, sim, y or yes,
+ * in any locale; anything else is no, which is the default the `[s/N]` and
+ * `[y/N]` prompts show.
+ */
+export function parseApproval(answer: string): "approve" | "deny" {
+  const text = answer.trim().toLowerCase();
+  return text === "s" || text === "sim" || text === "y" || text === "yes" ? "approve" : "deny";
+}
+
 /**
  * What the person answered to a whole list, or `undefined` when the answer
  * cannot be read as one. Lines are numbered from 1, as they were shown.
@@ -181,28 +196,30 @@ export async function presentBatch(batch: BatchPresentation, options: TerminalOp
   const { setup, approver } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
   const ask = options.ask ?? defaultAsk;
-  say(`  lote ${batch.ref} — ${batch.label}: ${batch.count} linha(s), total ${batch.total}, batch_hash ${batch.batch_hash.slice(0, 19)}…`);
+  const text = setup.coreStrings;
+  // The amounts are formatted here from their minor units, in the run's locale; the presentation's own strings are the model's.
+  say(text.batchHeader(batch.ref, batch.label, batch.count, formatBRL(batch.total_minor, setup.locale), batch.batch_hash.slice(0, 19)));
   for (const line of batch.lines) {
     const note =
       line.status === "already_settled"
-        ? " (ja paga; nao roda de novo)"
+        ? text.batchAlreadySettled
         : line.status === "in_progress"
-          ? " (em andamento; nao roda de novo)"
+          ? text.batchInProgress
           : line.status === "attempt_id_conflict"
-            ? " (tentativa presa a outro pagamento; nao roda de novo)"
+            ? text.batchAttemptConflict
             : "";
-    say(`    ${line.index + 1}. ${line.beneficiary}: ${line.amount}${note}`);
+    say(`    ${line.index + 1}. ${line.beneficiary}: ${formatBRL(line.amount_minor, setup.locale)}${note}`);
   }
   let parsed: { vetoed: number[] } | undefined;
   while (!parsed) {
-    parsed = parseBatchGesture(await ask("  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] "), batch.count);
-    if (!parsed) say(`  nao entendi; responda todas, todas exceto <numeros de 1 a ${batch.count}> ou nenhuma`);
+    parsed = parseBatchGesture(await ask(text.batchQuestion), batch.count);
+    if (!parsed) say(text.batchUnreadable(batch.count));
   }
   const vetoed = new Set(parsed.vetoed);
   const gesture: BatchGesture = { batch_hash: batch.batch_hash, approved: batch.lines.map((l) => l.index).filter((i) => !vetoed.has(i)), vetoed: parsed.vetoed };
   options.gestures.set(batch.ref, { batch_hash: batch.batch_hash, count: batch.count, vetoed });
   setup.engine.note("batch.gesture", null, { batch_ref: batch.ref, batch_hash: batch.batch_hash, count: batch.count, total_minor: batch.total_minor, approved: gesture.approved, vetoed: gesture.vetoed, approver: { type: "human", id: approver.id, channel: approver.channel } });
-  say(`  -> lista ${gesture.vetoed.length === 0 ? "aprovada inteira" : gesture.approved.length === 0 ? "negada inteira" : `aprovada exceto ${gesture.vetoed.map((i) => i + 1).join(", ")}`}`);
+  say(gesture.vetoed.length === 0 ? text.batchApprovedAll : gesture.approved.length === 0 ? text.batchDeniedAll : text.batchApprovedExcept(gesture.vetoed.map((i) => i + 1).join(", ")));
   return gesture;
 }
 
@@ -215,9 +232,9 @@ export async function waitForPayer(executionId: string, options: TerminalOptions
     intervalMs: setup.pollIntervalMs,
     timeoutMs: waitSeconds * 1000,
     payer: options.simulatePayer ? setup.payer : undefined,
-    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell),
+    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell, setup.locale),
     onWait: (_e, round) => {
-      const line = setup.kit.labels.waitingForPayer?.(round);
+      const line = setup.strings.waitingForPayer?.(round);
       if (setup.railKind === "api" && line !== undefined && round % 5 === 0) say(line);
     },
   });
@@ -238,18 +255,20 @@ export function closeTerminal(): void {
 export async function interactive(options: TerminalOptions & { runtime: AgentRuntime }): Promise<void> {
   const { setup } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
-  const labels = setup.kit.labels;
+  const words = setup.strings;
   // Interactive only: a person at the keyboard can decide a list in one go. The one-shot and the scenario runner pass one decision to every line and never reach this.
   const gestures: BatchGestures = new Map();
   const withGestures = { ...options, gestures };
   const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, withGestures), (batch) => presentBatch(batch, withGestures));
-  say(`${setup.manifest.manifest.name} ${setup.manifest.manifest.version} — approval: ${setup.mode} — trilho: ${setup.railKind} — ${labels.mandateWord} ${setup.mandate.id}`);
-  say(`run ${setup.runId} — bundle em ${relative(process.cwd(), setup.bundle.dir)}`);
-  say(labels.intro);
+  say(setup.coreStrings.banner(setup.manifest.manifest.name, setup.manifest.manifest.version, setup.mode, setup.railKind, words.mandateWord, setup.mandate.id));
+  say(setup.coreStrings.bundleAt(setup.runId, relative(process.cwd(), setup.bundle.dir)));
+  say(words.intro);
+  const notRun: NotRunLine[] = [];
+  let refusalsSaid = 0;
   for (;;) {
     let text: string;
     try {
-      text = await defaultAsk(labels.prompt);
+      text = await defaultAsk(words.prompt);
     } catch {
       break;
     }
@@ -257,7 +276,26 @@ export async function interactive(options: TerminalOptions & { runtime: AgentRun
     if (!trimmed) continue;
     if (["sair", "exit", "quit"].includes(trimmed.toLowerCase())) break;
     const result = await loop.turn(trimmed);
-    stdout.write(result.reply + "\n");
+    stdout.write(`${result.reply}\n`);
+    // The line counts the run so far, and is said only after a turn that paid, tried to, or skipped a line: a greeting or a read moved nothing.
+    notRun.push(...result.not_run);
+    // A request refused before a draft: said with the engine's own reason, once, in the turn that met it.
+    const refused = draftRefusals(setup.store, setup.runId).slice(refusalsSaid);
+    refusalsSaid += refused.length;
+    for (const refusal of refused) say(refusalLine(refusal));
+    if (result.executions.length > 0 || result.not_run.length > 0 || refused.length > 0) sayOutcome(setup, notRun, (line) => stdout.write(`${line}\n`));
   }
   closeTerminal();
 }
+
+/**
+ * `  -> failed (rail_failed): insufficient_funds — wallet cannot reserve the requested amount`.
+ * The reason says which gate closed the execution; on a failure, or an answer
+ * that left an attempt unknown, the rail's own code and message follow it,
+ * verbatim, so the first failure explains itself (#50).
+ */
+export function transitionLine(execution: Execution): string {
+  const failure = execution.state === "failed" || execution.state === "executing" ? railErrorOf(execution) : null;
+  const answer = failure ? `: ${failure.code}${failure.message && failure.message !== failure.code ? ` — ${failure.message}` : ""}` : "";
+  return `  -> ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}${answer}`;
+}

package/templates/bills-agent/packages/agent-runtime/test/env-names.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The kit reads `CODESPAR_API_URL` and `CODESPAR_PROJECT_ID`; the CodeSpar CLI
+ * reads `CODESPAR_BASE_URL` and `CODESPAR_PROJECT`. A shell set up for one
+ * must not send the other to production in silence: the kit takes the CLI's
+ * names as aliases, and refuses to start when the two names disagree.
+ */
+import { describe, expect, it } from "vitest";
+import { EnvNamesDisagreeError, reconcileEnvNames } from "../src/env.js";
+
+const STAGING = "https://api.staging.codespar.dev";
+
+describe("reconcileEnvNames", () => {
+  it("fills the kit's names from the CLI's when only the CLI's are set", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_BASE_URL: STAGING, CODESPAR_PROJECT: "prj_cli" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT_ID"]).toBe("prj_cli");
+  });
+
+  it("fills the CLI's names from the kit's too, so a .env read later cannot reopen a pair the shell closed", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_PROJECT_ID: "prj_kit" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_BASE_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT"]).toBe("prj_kit");
+  });
+
+  it("leaves the kit's names alone when the CLI's are unset or empty", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_BASE_URL: "", CODESPAR_PROJECT_ID: "prj_kit" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT_ID"]).toBe("prj_kit");
+  });
+
+  it("treats an empty kit name as unset, as the CLI does with its own", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: "", CODESPAR_BASE_URL: STAGING };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+  });
+
+  it("accepts both names when they say the same thing, a trailing slash aside", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_BASE_URL: `${STAGING}/`, CODESPAR_PROJECT_ID: "prj_1", CODESPAR_PROJECT: "prj_1" };
+    expect(() => reconcileEnvNames(env)).not.toThrow();
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+  });
+
+  it("refuses two URLs that disagree, naming both", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: "https://api.codespar.dev", CODESPAR_BASE_URL: STAGING };
+    expect(() => reconcileEnvNames(env)).toThrow(EnvNamesDisagreeError);
+    expect(() => reconcileEnvNames(env)).toThrow(/CODESPAR_API_URL=https:\/\/api\.codespar\.dev.*CODESPAR_BASE_URL=https:\/\/api\.staging\.codespar\.dev/);
+  });
+
+  it("refuses two projects that disagree, naming both", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_PROJECT_ID: "prj_kit", CODESPAR_PROJECT: "prj_cli" };
+    expect(() => reconcileEnvNames(env)).toThrow(/CODESPAR_PROJECT_ID=prj_kit.*CODESPAR_PROJECT=prj_cli/);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/inspect-mandate-status.test.ts

@@ -0,0 +1,80 @@
+/**
+ * The header of `inspect` and the mandate's status. The snapshot in the
+ * bundle is the local copy at the start of the run and says `active` for a
+ * mandate the API answered was revoked two lines below; the header says what
+ * a gate of the run heard, when that is the last word the run has.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ProofBundle } from "@codespar/agent-core";
+import { assembleTimeline, renderHtml, renderText } from "../src/inspect.js";
+
+const AGENT = { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo_titular" };
+const SNAPSHOT = "active in the snapshot at the start of the run";
+
+type Step = { execution: string | null; to?: string; reason?: string; detail?: string; at: string };
+
+function bundleOf(steps: Step[]): ProofBundle {
+  const bundle = new ProofBundle(mkdtempSync(join(tmpdir(), "inspect-mandate-status-")), "run_status_mandate_abc123");
+  bundle.meta({ run_id: bundle.runId, agent: "bills-agent@0.1.0", mode: "mandate", rail: "api", mandate_id: "cm_fixture", mandate_version: 1, started_at: "2026-09-23T18:00:00.000Z" });
+  writeFileSync(join(bundle.dir, "mandate.snapshot.json"), JSON.stringify({ id: "cm_fixture", version: 1, status: "active", currency: "BRL", cap_minor: 7200000, per_tx_cap_minor: 250000, expires_at: "2027-09-23T00:00:00.000Z", beneficiaries: [] }));
+  steps.forEach((step, i) => {
+    const payload = { ...(step.to ? { from: "approved", to: step.to, at: step.at, actor: AGENT } : {}), ...(step.reason ? { reason: step.reason } : {}), ...(step.detail ? { detail: step.detail } : {}) };
+    bundle.event({ seq: i + 1, run_id: bundle.runId, execution_id: step.execution, type: step.to ? "execution.transition" : "execution.refused_before_draft", payload, at: step.at, actor: AGENT });
+  });
+  return bundle;
+}
+
+const header = (bundle: ProofBundle) => renderText(assembleTimeline(bundle)).split("\n")[2];
+
+describe("inspect: the mandate's status in the header", () => {
+  it("is the snapshot's when no gate of the run heard otherwise", () => {
+    const bundle = bundleOf([
+      { execution: "exe_a", to: "executing", at: "2026-09-23T18:00:10.000Z" },
+      { execution: "exe_a", to: "settled", at: "2026-09-23T18:00:12.000Z" },
+    ]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+    expect(header(bundle)).toMatch(/^ {2}mandate active, expires 2027-09-23T00:00:00.000Z · /);
+  });
+
+  it("is what the API answered at the gate, with the source, the time and what the snapshot had said", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "denied", reason: "mandate_revoked", detail: "mandate cm_fixture was revoked (source: api)", at: "2026-09-23T18:00:13.000Z" }]);
+    const report = assembleTimeline(bundle);
+    expect(report.mandate).toMatchObject({ status: "active", status_seen: { status: "revoked", source: "api", at: "2026-09-23T18:00:13.000Z" } });
+    expect(header(bundle)).toContain(`mandate revoked (source: api, 18:00:13; ${SNAPSHOT}), expires `);
+    expect(header(bundle)).not.toContain("mandate active,");
+    // The page says the same thing as the terminal.
+    expect(renderHtml(report)).toContain(`mandate revoked (source: api, 18:00:13; ${SNAPSHOT}), expires `);
+    expect(renderHtml(report)).not.toContain("mandate active,");
+  });
+
+  it("reads a refusal before a draft the same way, and a paused mandate, and the stub", () => {
+    const refused = bundleOf([{ execution: null, reason: "mandate_revoked", detail: "mandate cm_fixture was revoked (source: stub)", at: "2026-09-23T18:02:00.000Z" }]);
+    expect(header(refused)).toContain(`mandate revoked (source: stub, 18:02:00; ${SNAPSHOT})`);
+    const paused = bundleOf([{ execution: "exe_a", to: "denied", reason: "mandate_paused", detail: "mandate cm_fixture is paused (source: api)", at: "2026-09-23T18:00:13.000Z" }]);
+    expect(header(paused)).toContain(`mandate paused (source: api, 18:00:13; ${SNAPSHOT})`);
+  });
+
+  it("an expiry the run's own clock found names the clock, not a source that never answered it", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "expired", reason: "mandate_expired", detail: "mandate cm_fixture expired at 2027-09-23T00:00:00.000Z", at: "2027-09-23T00:00:05.000Z" }]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toMatchObject({ status: "expired", source: null });
+    expect(header(bundle)).toContain(`mandate expired (by the run's clock, 00:00:05; ${SNAPSHOT})`);
+  });
+
+  it("a payment that executed after a pause is the last word: the mandate was resumed, and the header is the snapshot's again", () => {
+    const bundle = bundleOf([
+      { execution: "exe_a", to: "denied", reason: "mandate_paused", detail: "mandate cm_fixture is paused (source: api)", at: "2026-09-23T18:00:13.000Z" },
+      { execution: "exe_b", to: "executing", at: "2026-09-23T18:05:00.000Z" },
+      { execution: "exe_b", to: "settled", at: "2026-09-23T18:05:02.000Z" },
+    ]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+    expect(header(bundle)).toContain("mandate active, expires ");
+  });
+
+  it("a refusal that is not about the mandate's status leaves the header alone", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "denied", reason: "cap_exceeded", detail: "300000 is above the cap per payment", at: "2026-09-23T18:00:13.000Z" }]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+  });
+});