@codespar/cli 0.18.0 → 0.20.0

package/templates/bills-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");

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

@@ -18,12 +18,17 @@
  * party, payee unmasked; checked with no credential at all — or a copy from a
  * run's `runs/<run-id>/receipts/`, which masks the payee and carries none of
  * the links. A copy reaches check 2 only with `--from-api`: the tenant's
- * `CODESPAR_API_KEY` (the environment, or the `.env` of the agent the copy
- * sits in) reads the receipt from the API, in memory, and nothing unmasked is
+ * `CODESPAR_API_KEY`, against the deployment `CODESPAR_API_URL` names (each
+ * from the environment, or else from the `.env` of the agent the copy sits
+ * in), reads the receipt from the API, in memory, and nothing unmasked is
  * written anywhere. Without it a copy answers `signature_only`, which is the
  * truth about what a masked copy can prove. The approval artifact of a copy
  * is the one its `approval_id` names in the run's own `approval.json`.
  *
+ * Of the read, the output carries only `sealed_payment` (`sandbox`,
+ * `money_moved`) off a body that bound. The tenant's read still carries
+ * `mandate.sig`, a spend credential, and it is never printed.
+ *
  * It is the one command here that does NOT need an agent — `cli.ts`
  * dispatches it before it looks for an `agent.yaml` — because the file it
  * reads has usually been copied off the machine that produced it.
@@ -40,6 +45,7 @@ import { stderr, stdout } from "node:process";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_RECEIPT_KEYS_URL,
+  NotATestKeyError,
   VERDICT_EXIT_CODES,
   copyDisagreesWithRead,
   createCodeSparClient,
@@ -55,7 +61,8 @@ import {
   type ReceiptVerification,
 } from "@codespar/agent-core";
 import { findAgentDir } from "../agent.js";
-import { readDotEnv } from "../setup.js";
+import { readAgentEnv } from "../env.js";
+import { envFileOf } from "../setup.js";
 
 const USAGE =
   "usage: npm run verify <receipt-file> [--json] [--keys <key-set.json> | --url <https://.../.well-known/codespar-receipt-keys.json>] [--approval <approval.json> [--approval-id <apr_...>]] [--from-api]";
@@ -109,7 +116,7 @@ export async function verify(argv: string[]): Promise<number> {
       say(`the key set is public and needs no credential; its default is ${DEFAULT_RECEIPT_KEYS_URL}`);
       say("--keys reads a saved copy of that document instead, so the check runs with no network at all");
       say("the receipt file is the API's read (GET /v1/consumers/receipts/{id}), whose body is recomputed against the signed chain, or a run's copy, which proves the signature only");
-      say("--from-api reads a run's copy from the API with CODESPAR_API_KEY (in memory, nothing written), so its body and its approval are checked too; the key set then defaults to that deployment's");
+      say("--from-api reads a run's copy from the API with CODESPAR_API_KEY (in memory, nothing written), so its body and its approval are checked too; the key set then defaults to that deployment's. CODESPAR_API_KEY and CODESPAR_API_URL come from the environment, or else from the .env of the agent the copy sits in; the CodeSpar CLI's name CODESPAR_BASE_URL is read too, and the two must agree");
       say("--approval holds a v4 receipt's sealed approval link against an approval artifact (a run's copy uses its own approval.json)");
       return 0;
     } else if (a.startsWith("-")) {
@@ -139,6 +146,20 @@ export async function verify(argv: string[]): Promise<number> {
   const receipt = readJson(args.receiptFile, say);
   if (receipt === undefined) return 2;
 
+  // Before the deployment is chosen, not only before the key is read: a
+  // staging key in that `.env` sits next to the staging URL, and a read sent
+  // to production with it is a 401 (#66). Only `--from-api` touches it; the
+  // other paths are the verifier who holds nothing.
+  const agentDir = args.fromApi ? findAgentDir(dirname(resolve(args.receiptFile))) : undefined;
+  // `--from-api` is also the one path that reads the deployment and the project, so it is the one that reconciles the CLI's names for them; a check against `--keys` or the default key set holds no opinion on either. Two names that disagree are a usage error (2), never 1: 1 means the receipt does not verify.
+  if (args.fromApi) {
+    const disagreement = readAgentEnv(agentDir);
+    if (disagreement) {
+      say(`${disagreement.message}\n${USAGE}`);
+      return 2;
+    }
+  }
+
   // The read and the key set must come from ONE deployment: the recipe that
   // binds the body is the key document's, and a staging read checked under
   // production's document is the §47 trap again.
@@ -161,14 +182,14 @@ export async function verify(argv: string[]): Promise<number> {
     if (keysDocument === undefined) return 2;
   }
 
-  const report = await check(receipt, args, apiBase, approval, keysDocument);
+  const report = await check(receipt, args, apiBase, agentDir, approval, keysDocument);
   if (args.json) stdout.write(JSON.stringify(report) + "\n");
   else stdout.write(render(report));
   say(report.message);
   return VERDICT_EXIT_CODES[report.verdict];
 }
 
-async function check(receipt: unknown, args: Args, apiBase: string, approval: ApprovalClaim | undefined, keysDocument: unknown): Promise<ReceiptVerification> {
+async function check(receipt: unknown, args: Args, apiBase: string, agentDir: string | undefined, approval: ApprovalClaim | undefined, keysDocument: unknown): Promise<ReceiptVerification> {
   // Answered before the network is touched, as before: an unsigned or
   // malformed file needs no key set, and fetching one to check a signature
   // that is not there would turn an offline answer into an outage.
@@ -202,7 +223,7 @@ async function check(receipt: unknown, args: Args, apiBase: string, approval: Ap
     return signatureOnly(signature, "read_required", "this is a run's copy, which masks the payee and carries none of the chain's links. Recompute from the API's read: run this again with --from-api (the tenant's key, read-only, nothing written), or verify the read itself");
   }
 
-  const read = await readFromApi(signed.fields.receipt_id, args.receiptFile!, apiBase);
+  const read = await readFromApi(signed.fields.receipt_id, apiBase, agentDir);
   if (!read.ok) return signatureOnly(signature, "read_unavailable", `the API's read of it could not be fetched (${read.detail}), so nothing is proved and nothing is disproved about the body`);
   const differs = copyDisagreesWithRead(receipt as Record<string, unknown>, read.body);
   if (differs.includes("chain")) {
@@ -229,18 +250,18 @@ function unreachable(receiptId: string, label: string, message: string): Receipt
 /**
  * The receipt as the API reads it, for a copy, with the tenant's key. The key
  * is the environment's, or the `.env` of the agent the copy sits in — the
- * same place `npm start` reads it from — and only a `csk_test_` key is
- * accepted, like everywhere else in this repository.
+ * same place `npm start` reads it from, loaded by `verify` before it chose
+ * `apiBase` — and only a `csk_test_` key is accepted, like everywhere else in
+ * this repository.
  */
-async function readFromApi(receiptId: string, receiptFile: string, apiBase: string): Promise<{ ok: true; body: Record<string, unknown> } | { ok: false; detail: string }> {
-  const agentDir = findAgentDir(dirname(resolve(receiptFile)));
-  if (agentDir) readDotEnv(agentDir);
+async function readFromApi(receiptId: string, apiBase: string, agentDir: string | undefined): Promise<{ ok: true; body: Record<string, unknown> } | { ok: false; detail: string }> {
   try {
     const api = createCodeSparClient({ apiKey: process.env["CODESPAR_API_KEY"], baseUrl: apiBase, projectId: process.env["CODESPAR_PROJECT_ID"], timeoutMs: 15_000 });
     const body: unknown = await api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
     if (!isReceiptRead(body)) return { ok: false, detail: "the API answered something that is not a receipt read" };
     return { ok: true, body };
   } catch (err) {
+    if (err instanceof NotATestKeyError) return { ok: false, detail: new NotATestKeyError(err.problem, agentDir ? envFileOf(agentDir) : undefined).message };
     const failure = describeApiError(err);
     return { ok: false, detail: `${failure.code}: ${failure.message}` };
   }
@@ -325,6 +346,10 @@ function render(report: ReceiptVerification): string {
     lines.push(`  approval     ${a.status}: sealed ${a.sealed.items_hash}${a.sealed.batch_hash ? ` batch ${a.sealed.batch_hash}` : ""}`);
     if (a.artifact) lines.push(`               artifact ${a.artifact.approval_id} ${a.artifact.items_hash}${a.artifact.batch_hash ? ` batch ${a.artifact.batch_hash}` : ""}`);
   }
+  if (report.sealed_payment) {
+    const shown = (v: boolean | null) => (v === null ? "not sealed" : String(v));
+    lines.push(`  payment      sandbox ${shown(report.sealed_payment.sandbox)}, money_moved ${shown(report.sealed_payment.money_moved)}`);
+  }
   lines.push(`  reason       ${report.reason}`);
   return lines.join("\n") + "\n";
 }

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

@@ -7,7 +7,7 @@
  */
 import { stderr, stdout } from "node:process";
 import { envName, type Agent } from "../agent.js";
-import { setup } from "../setup.js";
+import { inLocaleOf, localeFlag, setup } from "../setup.js";
 import { announceOutcome, followUp } from "../terminal.js";
 import { startWebhookServer } from "../webhook.js";
 
@@ -15,14 +15,22 @@ export async function webhook(agent: Agent, argv: string[]): Promise<number> {
   const port = Number(argv.includes("--port") ? argv[argv.indexOf("--port") + 1] : process.env[envName(agent, "WEBHOOK_PORT")] ?? "8787");
   const secret = argv.includes("--secret") ? argv[argv.indexOf("--secret") + 1] : process.env[envName(agent, "TRIGGER_SECRET")];
   const say = (l: string) => stderr.write(l + "\n");
-  const s = setup(agent, { say, runId: `run_webhook_${Date.now().toString(36)}` });
+  let locale;
+  try {
+    locale = localeFlag(argv);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+  const s = setup(agent, { say, runId: `run_webhook_${Date.now().toString(36)}`, locale });
   const server = startWebhookServer(
     port,
     {
       engine: s.engine,
       secret,
       onClosed: async (execution) => {
-        announceOutcome(execution, s, (l) => void stdout.write(l + "\n"));
+        // Told in the locale of the run that issued the charge, whatever this receiver's own is.
+        announceOutcome(execution, inLocaleOf(s, execution), (l) => void stdout.write(l + "\n"));
         await followUp(execution, s, say);
       },
     },

package/templates/bills-agent/packages/agent-runtime/src/default-kit.ts

@@ -3,9 +3,32 @@
  * example mandate, the generic console words, and no tools. A read-only agent
  * spreads this and adds its handlers; a payer or a collector replaces the rail.
  */
-import { StubRail, loadMandate, type Execution } from "@codespar/agent-core";
+import { StubRail, formatBRL, isReplayedSettlement, loadMandate, railErrorOf, type Execution, type LocaleTable } from "@codespar/agent-core";
 import { relative } from "node:path";
-import type { AgentKit } from "./kit.js";
+import type { AgentKit, KitStrings } from "./kit.js";
+import type { Setup } from "./setup.js";
+
+/**
+ * The lines a payment execution reads as on the console, in the run's locale:
+ * the default kit's, and the bills and supplier agents', which pay the same
+ * way and describe it the same way.
+ */
+export function describePayment(execution: Execution, setup: Setup): string[] {
+  const text = setup.coreStrings;
+  const words = setup.strings;
+  const lines: string[] = [];
+  lines.push(`  ${text.execution} ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
+  for (const item of execution.items) lines.push(`    - ${item.beneficiary}: ${formatBRL(item.amount, setup.locale)}${item.description ? ` — ${item.description}` : ""}`);
+  lines.push(`    ${text.totalByCore}: ${formatBRL(execution.total, setup.locale)}`);
+  if (execution.escalation) lines.push(`    ${text.escalatedBy}: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
+  if (execution.blocking_reasons.length) lines.push(`    ${text.blocked(execution.blocking_reasons.join(", "), words.notAuthorized)}`);
+  if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
+  if (isReplayedSettlement(execution)) lines.push(`    ${text.replayedSettlement}`);
+  for (const outcome of execution.outcomes) {
+    if (outcome.receipt_id) lines.push(`    ${words.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+  }
+  return lines;
+}
 
 export function formatMinor(minor: number): string {
   const sign = minor < 0 ? "-" : "";
@@ -13,28 +36,45 @@ export function formatMinor(minor: number): string {
   return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${String(abs % 100).padStart(2, "0")}`;
 }
 
+export const DEFAULT_STRINGS: LocaleTable<KitStrings> = {
+  "pt-BR": {
+    mandateWord: "mandato",
+    receiptWord: "recibo",
+    intro: 'Diga o que precisa. Ctrl+D ou "sair" encerra.',
+    prompt: "> ",
+    approveQuestion: "  Aprovar? [s/N] ",
+    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a operação)",
+    notAuthorized: "o mandato não autoriza",
+  },
+  en: {
+    mandateWord: "mandate",
+    receiptWord: "receipt",
+    intro: 'Say what you need. Ctrl+D or "exit" ends.',
+    prompt: "> ",
+    approveQuestion: "  Approve? [y/N] ",
+    uncertainDispatch: "  outcome unknown on the rail; run `npm run resume` to reconcile (never repeat the operation)",
+    notAuthorized: "the mandate does not authorize it",
+  },
+};
+
 export const defaultKit: AgentKit = {
   settlement: "immediate",
   scenarioRail: "stub",
   labels: {
     defaultUser: "usr_terminal",
     evalUser: "usr_demo_titular",
-    mandateWord: "mandato",
-    receiptWord: "recibo",
-    intro: 'Diga o que precisa. Ctrl+D ou "sair" encerra.',
-    prompt: "> ",
-    approveQuestion: "  Aprovar? [s/N] ",
-    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a operacao)",
     missingReceiptKind: "receipt_missing_locally",
     missingReceiptDetail: (receiptId, runId) => `receipt ${receiptId} is not in runs/${runId}/receipts`,
     stillExecuting: (e) => `${e.id}: still executing — ${e.detail}; nothing was re-sent`,
   },
+  strings: DEFAULT_STRINGS,
   usage: (manifest) => `${manifest.manifest.name}
   npm start                              interactive terminal
   npm start -- --input "..."             one turn (add --approve/--deny to decide, --json for machine output)
   npm start -- --scenario <name>         run a scenario pack (see scenarios/)
 options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>  --json
-         --now <ISO 8601>  pin the run to that instant; env CODESPAR_AGENT_NOW is the same thing`,
+         --now <ISO 8601>  pin the run to that instant; env CODESPAR_AGENT_NOW is the same thing
+         --locale pt-BR|en  the language of what the code prints; default: agent.yaml \`locale\`, else pt-BR`,
   buildRail: (ctx) => {
     // A read-only agent has no rail to reach: the stub answers offline, whatever key the environment carries.
     const killAfterDispatch = ctx.envVar("KILL_AFTER_DISPATCH") === "1" ? { afterDispatch: () => process.exit(137) } : {};
@@ -45,19 +85,7 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
     };
   },
   handlers: () => ({}),
-  describeExecution: (execution, setup) => {
-    const lines: string[] = [];
-    lines.push(`  execucao ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
-    for (const item of execution.items) lines.push(`    - ${item.beneficiary}: ${formatMinor(item.amount)}${item.description ? ` — ${item.description}` : ""}`);
-    lines.push(`    total (calculado pelo core): ${formatMinor(execution.total)}`);
-    if (execution.escalation) lines.push(`    escalado por: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
-    if (execution.blocking_reasons.length) lines.push(`    bloqueado: ${execution.blocking_reasons.join(", ")} — o mandato nao autoriza; nao ha o que aprovar`);
-    if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
-    for (const outcome of execution.outcomes) {
-      if (outcome.receipt_id) lines.push(`    recibo: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
-    }
-    return lines;
-  },
+  describeExecution: (execution, setup) => describePayment(execution, setup),
   oneShotPayload: ({ setup: s, reply, toolCalls, executions }) => ({
     run_id: s.runId,
     agent: `${s.manifest.manifest.name}@${s.manifest.manifest.version}`,
@@ -71,11 +99,13 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
       id: e.id,
       state: e.state,
       reason: e.reason ?? null,
+      rail_error: railErrorOf(e),
       escalation: e.escalation ?? null,
       total_minor: e.total,
       items: e.items.map((i) => ({ beneficiary: i.beneficiary, amount_minor: i.amount })),
       approval_id: e.approval_id ?? null,
       receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+      replayed: isReplayedSettlement(e),
     })),
     receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
     bundle_dir: relative(process.cwd(), s.bundle.dir),

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

@@ -0,0 +1,64 @@
+/**
+ * Two names for the same two settings. The kit reads `CODESPAR_API_URL` and
+ * `CODESPAR_PROJECT_ID`; the CodeSpar CLI (`@codespar/cli`) reads
+ * `CODESPAR_BASE_URL` and `CODESPAR_PROJECT`. A shell prepared for one of them
+ * left the other on its default, production, with nothing said: a staging key
+ * then meets the wrong deployment.
+ *
+ * The kit takes the CLI's names as aliases of its own, and a command that
+ * talks to the API refuses to start when the two disagree. Only the
+ * environment and the agent's `.env` are read: the CLI's own config file
+ * (`~/.codespar/config.json`, what `codespar login` writes) is not.
+ */
+import { readDotEnv } from "./setup.js";
+
+const PAIRS: ReadonlyArray<{ kit: string; cli: string; same: (a: string, b: string) => boolean }> = [
+  { kit: "CODESPAR_API_URL", cli: "CODESPAR_BASE_URL", same: (a, b) => a.replace(/\/+$/, "") === b.replace(/\/+$/, "") },
+  { kit: "CODESPAR_PROJECT_ID", cli: "CODESPAR_PROJECT", same: (a, b) => a === b },
+];
+
+export class EnvNamesDisagreeError extends Error {
+  constructor(kit: string, kitValue: string, cli: string, cliValue: string) {
+    super(`${kit}=${kitValue} and ${cli}=${cliValue} disagree. The kit reads ${kit} and the CodeSpar CLI reads ${cli}; they must name the same thing. Set one of them, or both to the same value.`);
+    this.name = "EnvNamesDisagreeError";
+  }
+}
+
+/**
+ * Makes the two names of each pair say one thing: whichever is set fills the
+ * other, and two that are set and differ throw. Both are left set, so a later
+ * reader of either name, and a later `.env`, finds the pair already decided.
+ * An empty value counts as unset, as it does in the CLI.
+ */
+export function reconcileEnvNames(env: NodeJS.ProcessEnv = process.env): void {
+  for (const { kit, cli, same } of PAIRS) {
+    const kitValue = env[kit]?.trim() || undefined;
+    const cliValue = env[cli]?.trim() || undefined;
+    if (kitValue && cliValue && !same(kitValue, cliValue)) throw new EnvNamesDisagreeError(kit, kitValue, cli, cliValue);
+    const value = kitValue ?? cliValue;
+    if (value !== undefined) env[kit] = env[cli] = value;
+  }
+}
+
+/**
+ * The agent's `.env` under the rule `readDotEnv` already has, extended to the
+ * aliases: what the shell exported wins, and the file fills only what is
+ * unset. The shell is reconciled first, so a name it set under either spelling
+ * closes the pair before the file is read; then the file's own names are.
+ *
+ * It returns the disagreement instead of throwing it: only a command that is
+ * about to use the URL or the project should stop on it.
+ */
+export function readAgentEnv(agentDir: string | undefined): EnvNamesDisagreeError | undefined {
+  try {
+    reconcileEnvNames();
+    if (agentDir) readDotEnv(agentDir);
+    reconcileEnvNames();
+    return undefined;
+  } catch (err) {
+    if (!(err instanceof EnvNamesDisagreeError)) throw err;
+    // The shell disagreed with itself before the file was read: the file is still owed, for the key it may hold.
+    if (agentDir) readDotEnv(agentDir);
+    return err;
+  }
+}

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

@@ -2,6 +2,7 @@ export * from "./agent.js";
 export * from "./kit.js";
 export * from "./default-kit.js";
 export * from "./setup.js";
+export * from "./runs.js";
 export * from "./terminal.js";
 export * from "./channels/index.js";
 export * from "./poll.js";
@@ -10,4 +11,5 @@ export * from "./scenarios.js";
 export * from "./adversarial.js";
 export * from "./inspect.js";
 export { main } from "./cli.js";
+export { checkStrings } from "./commands/check.js";
 export { pollWhatsApp, type PollWhatsAppOptions } from "./commands/poll-whatsapp.js";