@codespar/cli 0.18.0 → 0.20.0

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

@@ -15,6 +15,8 @@ import type {
   LoadedManifest,
   LocalMandateStatusStub,
   Guardrails,
+  Locale,
+  LocaleTable,
   Mandate,
   MandateStatusSource,
   PaymentRail,
@@ -95,12 +97,30 @@ export interface RailBuild {
   pollIntervalMs?: number;
 }
 
+/**
+ * What an agent calls the people and the records of a run. None of it is
+ * localized, on purpose: who approved is an id in a signed artifact, and an
+ * approver that changed with the language would be a different approver.
+ */
 export interface RuntimeLabels {
   /** Who decides when no `--user` is given: `usr_terminal`, `usr_operator`. */
   defaultUser: string;
   /** Who decides inside a scenario or an adversarial case. */
   evalUser: string;
-  /** The word for the signed instrument in the banner: `mandato`, `politica`. */
+  /** `reconcile`'s finding kind and detail for a sealed outcome the bundle does not hold. */
+  missingReceiptKind: string;
+  missingReceiptDetail(receiptId: string, runId: string): string;
+  /** `resume`'s line for an execution it could not close. */
+  stillExecuting(execution: Execution): string;
+}
+
+/**
+ * The words the runner prints on an agent's behalf, one entry per locale
+ * (`kit.strings`). A kit adds keys of its own to the same entries; every key
+ * must exist in every locale, which `npm run check` verifies.
+ */
+export interface KitStrings {
+  /** The word for the signed instrument in the banner: `mandato`, `política`. */
   mandateWord: string;
   /** The word for a sealed outcome in the console: `recibo`, `registro`. */
   receiptWord: string;
@@ -108,15 +128,12 @@ export interface RuntimeLabels {
   intro: string;
   /** The interactive prompt. */
   prompt: string;
-  /** The question an `awaiting_approval` execution asks at the keyboard. */
+  /** The question an `awaiting_approval` execution asks at the keyboard. Its answers are read the same in every locale. */
   approveQuestion: string;
   /** What the console says when a dispatch ended with an unknown outcome. */
   uncertainDispatch: string;
-  /** `reconcile`'s finding kind and detail for a sealed outcome the bundle does not hold. */
-  missingReceiptKind: string;
-  missingReceiptDetail(receiptId: string, runId: string): string;
-  /** `resume`'s line for an execution it could not close. */
-  stillExecuting(execution: Execution): string;
+  /** Who refuses a blocked execution: "o mandato não autoriza", "the policy does not authorize". */
+  notAuthorized: string;
   /** `await-payer` only: the line printed every few looks while the payer has not acted. */
   waitingForPayer?(round: number): string;
 }
@@ -132,6 +149,8 @@ export interface OneShotContext {
 
 export interface ConsentContext {
   agentDir: string;
+  /** The run's locale: the consent summary and its question are printed in it. */
+  locale: Locale;
   argv: string[];
   say(line: string): void;
 }
@@ -153,6 +172,8 @@ export interface AgentKit {
    */
   scenarioRail?: "stub" | "requested";
   labels: RuntimeLabels;
+  /** The words the runner prints for this agent, per locale. */
+  strings: LocaleTable<KitStrings>;
   /** The usage text `--help`, a bad flag and a bad `--now` print. */
   usage(manifest: LoadedManifest): string;
   buildRail(ctx: RailContext): RailBuild;
@@ -169,13 +190,13 @@ export interface AgentKit {
    */
   executeOnApproval?: boolean;
   /** The deterministic policy the core runs as its `policyExtension`. `store` is the run's state.db, for a policy that judges durable state of the agent's own (a cart). */
-  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails; store: StateStore }): PolicyExtension | undefined;
+  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails; store: StateStore; locale: () => Locale }): PolicyExtension | undefined;
   /** The console lines that describe one execution. */
   describeExecution(execution: Execution, setup: Setup): string[];
   /** The `--json` body of a one-shot. */
   oneShotPayload(ctx: OneShotContext): Record<string, unknown>;
   /** `await-payer` only: what the payer reads when a receivable becomes payable. */
-  presentInstrument?(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void): void;
+  presentInstrument?(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void, locale: Locale): void;
   /** `await-payer` only: the one message per outcome the counterparty receives. */
   announceOutcome?(execution: Execution, setup: Setup, tell: (line: string) => void): boolean;
   /**
@@ -189,12 +210,13 @@ export interface AgentKit {
    * close on, or it cannot tell the person at all.
    *
    * The name must be one the agent declares in
-   * `channels/whatsapp/templates.json`; the language is the registry's and is
-   * not repeated here. `undefined` means this agent has no approved copy for
+   * `channels/whatsapp/templates.json`; the language is the conversation's
+   * locale's, and the registry declares every template in each. `locale` is
+   * there for the variables, which are display text too (a formatted total). `undefined` means this agent has no approved copy for
    * that outcome, which the caller REPORTS rather than papers over: a person
    * who was not told was not told.
    */
-  outcomeTemplate?(execution: Execution): { template: string; variables: string[] } | undefined;
+  outcomeTemplate?(execution: Execution, locale: Locale): { template: string; variables: string[] } | undefined;
   /**
    * Work that FOLLOWS an outcome and is not part of it: a sale's service
    * invoice once the order is `settled`. Runs after `announceOutcome`,

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

@@ -0,0 +1,118 @@
+/**
+ * What a run did, counted from what the engine holds and not from what the
+ * model said. A reply is the model's (or a recording's) and may claim a
+ * payroll ran when every line was already paid or every line failed; this is
+ * the line the terminal prints after it, and the one-shot's exit code.
+ *
+ * The unit is the payment, not the execution: an execution that paid three
+ * bills and failed the fourth closes `failed`, and counts three settled and
+ * one failed.
+ */
+import { isDeclinedReason, isTerminal, type CoreStrings, type Execution, type ExecutionEngine, type NotRunLine, type StateStore } from "@codespar/agent-core";
+
+export interface RunOutcome {
+  /** Payments this run settled. */
+  settled: number;
+  /** Payments the rail failed, executions that failed before any, and lines refused before a draft existed. */
+  failed: number;
+  /** Denied or expired, or closed by a declined reason (`isDeclinedReason`): somebody said no, or nobody answered or paid in time. */
+  declined: number;
+  /** Payments an earlier run already made: skipped here, or answered by the API with the earlier payment. */
+  already_paid: number;
+  /** Executions not yet terminal, plus lines an earlier execution still holds. */
+  open: number;
+}
+
+/** A request the engine refused before a draft existed (`execution.refused_before_draft`): the gate's own reason and detail. */
+export interface DraftRefusal {
+  reason: string;
+  detail: string;
+}
+
+/**
+ * Every refusal before a draft the engine recorded for this run, in order,
+ * for the sentence on the terminal and for `--json`. It is NOT what the count
+ * is taken from: each tool reports its refused request through `onNotRun`,
+ * and that is the one source of the count.
+ */
+export function draftRefusals(store: StateStore, runId: string): DraftRefusal[] {
+  return store
+    .listEvents({ run_id: runId })
+    .filter((e) => e.type === "execution.refused_before_draft")
+    .map((e) => {
+      const payload = e.payload as { reason?: unknown; detail?: unknown };
+      return { reason: String(payload.reason ?? "unknown"), detail: String(payload.detail ?? "") };
+    });
+}
+
+export function refusalLine(refusal: DraftRefusal): string {
+  return `  -> refused_before_draft (${refusal.reason}): ${refusal.detail}`;
+}
+
+export function runOutcome(executions: readonly Execution[], notRun: readonly NotRunLine[]): RunOutcome {
+  const out: RunOutcome = { settled: 0, failed: 0, declined: 0, already_paid: 0, open: 0 };
+  for (const e of executions) {
+    if (!isTerminal(e.state)) out.open += 1;
+    else if (e.state === "denied" || e.state === "expired") out.declined += 1;
+    // Closed with no attempt on record: the execution is the one thing to count.
+    else if (e.outcomes.length === 0) out[e.state === "settled" ? "settled" : isDeclinedReason(e.reason) ? "declined" : "failed"] += 1;
+    else {
+      for (const o of e.outcomes) {
+        if (o.status === "settled") out[o.replayed === true ? "already_paid" : "settled"] += 1;
+        else if (o.status === "failed") out[isDeclinedReason(o.code) ? "declined" : "failed"] += 1;
+        else out.open += 1;
+      }
+    }
+  }
+  for (const line of notRun) {
+    if (line.why === "already_settled") out.already_paid += 1;
+    else if (line.why === "refused") out.failed += 1;
+    else out.open += 1;
+  }
+  return out;
+}
+
+export function outcomeLine(text: CoreStrings, outcome: RunOutcome): string {
+  return text.runOutcome(outcome.settled, outcome.failed, outcome.declined, outcome.already_paid, outcome.open);
+}
+
+/** The executions of one run as the engine holds them now, each once. */
+export function runExecutions(engine: ExecutionEngine, runId: string): Execution[] {
+  const byId = new Map<string, Execution>();
+  for (const e of engine.list()) if (e.run_id === runId) byId.set(e.id, e);
+  return [...byId.values()];
+}
+
+/**
+ * The one place the terminal and the one-shot count a run: the engine's
+ * executions of this run plus the lines that created none. The refusals
+ * before a draft come back with it, to be said and listed. `say`, when given,
+ * receives the count line.
+ */
+export function sayOutcome(
+  source: { engine: ExecutionEngine; store: StateStore; runId: string; coreStrings: CoreStrings },
+  notRun: readonly NotRunLine[],
+  say?: (line: string) => void,
+): { executions: Execution[]; refusals: DraftRefusal[]; outcome: RunOutcome; line: string } {
+  const executions = runExecutions(source.engine, source.runId);
+  const refusals = draftRefusals(source.store, source.runId);
+  const outcome = runOutcome(executions, notRun);
+  const line = outcomeLine(source.coreStrings, outcome);
+  say?.(line);
+  return { executions, refusals, outcome, line };
+}
+
+/**
+ * The one-shot's exit code. 1 when a payment failed or a line was refused
+ * before a draft, and it wins over 3: a run that failed something and left
+ * something else `executing` is a failed run, and the line still counts what
+ * is open. 3 when nothing failed and an execution OF THIS RUN was left
+ * `executing`, whose outcome the rail did not say. 0 otherwise: settled,
+ * already paid, still open, and also denied or expired, which are the agent
+ * doing its job and are named on the line. A line an earlier run still holds
+ * (`in_progress`) is open and exits 0: this run left nothing behind.
+ */
+export function outcomeExitCode(outcome: RunOutcome, executions: readonly Execution[] = []): 0 | 1 | 3 {
+  if (outcome.failed > 0) return 1;
+  return executions.some((e) => e.state === "executing") ? 3 : 0;
+}

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

@@ -30,9 +30,8 @@ export interface PollOptions extends PollHooks {
   timeoutMs: number;
   /** Cap on looks, for a zero-interval (stub) loop: the fixture payer acts within two looks; a third proves nothing changes. */
   maxRounds?: number;
-  /** When set, the payer plays once every instalment is payable, or after `payerAfterRounds` looks (a scenario, `--simulate-payer`). */
+  /** When set, the payer plays once every instalment is payable (a scenario, `--simulate-payer`), and never before. */
   payer?: SandboxPayer | undefined;
-  payerAfterRounds?: number;
   clock?: () => Date;
   sleep?: (ms: number) => Promise<void>;
 }
@@ -85,13 +84,14 @@ export async function pollUntilClosed(engine: ExecutionEngine, executionId: stri
     rounds += 1;
     execution = await engine.reconcile(execution.id);
     await present(execution);
-    // The sandbox payer plays once every receivable is payable (the QR was shown first, as in the scene), or after a few looks if the
-    // clearing house is still registering: the API's test route settles a PROCESSING charge too, and on the shared sandbox the
-    // registration can take minutes. A real payer is not this hook.
+    // The sandbox payer plays once every receivable is payable, the QR shown first, as in the scene, and never before. It used to
+    // play after a few looks whatever it found, because the API's test route settles a charge still registering; on staging on
+    // 2026-09-27 that route settled a charge the issuer had ended in ERROR, with no QR at all, and the scenario called the order
+    // settled (OPEN_QUESTIONS §63, ent#1816). A payer can only pay what it can see, so a registration that never ends payable
+    // leaves the order open until the wait runs out, or closes it with the issuer's own failure.
     const issued = execution.outcomes.filter((o) => o.status === "accepted" && o.transaction_id);
     const allPayable = issued.length > 0 && issued.every((o) => o.instrument?.payable);
-    const patienceOver = rounds >= (options.payerAfterRounds ?? 5);
-    if (options.payer && !paidRequested && execution.state === "executing" && issued.length > 0 && issued.length === execution.outcomes.filter((o) => o.status === "accepted").length && (allPayable || patienceOver)) {
+    if (options.payer && !paidRequested && execution.state === "executing" && issued.length > 0 && issued.length === execution.outcomes.filter((o) => o.status === "accepted").length && allPayable) {
       paidRequested = true;
       for (const outcome of issued) {
         const result = await options.payer.pay(outcome.transaction_id!, outcome.attempt_id);

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

@@ -0,0 +1,51 @@
+/**
+ * Where a run's proof bundle lives. A run a person made (`npm start`, a
+ * scenario pack run by name) is `runs/<run-id>`. `npm run eval` writes dozens
+ * per pass, and they used to land beside the person's own, so the folder a
+ * person looks in was mostly the suite's. They go to `runs/eval/<run-id>`.
+ *
+ * A run id is still all `inspect` and `rerun` take: an eval run is found by
+ * its id alone, and `eval/<run-id>` is accepted too.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "./agent.js";
+import { runsDir } from "./setup.js";
+
+/** The folder name under `runs/` that holds what the eval suite wrote. Never a run id: every run id starts with `run_`. */
+export const EVAL_RUNS = "eval";
+
+export function evalRunsDir(agent: Agent, env: NodeJS.ProcessEnv = process.env): string {
+  return join(runsDir(agent, env), EVAL_RUNS);
+}
+
+/** The bundle of a run by its id, a person's or the eval suite's, and the folder it was found in. */
+export function openRun(agent: Agent, runId: string, env: NodeJS.ProcessEnv = process.env): { bundle: ProofBundle; runsDir: string } | undefined {
+  const own = runsDir(agent, env);
+  const id = runId.startsWith(`${EVAL_RUNS}/`) ? runId.slice(EVAL_RUNS.length + 1) : runId;
+  // The folder itself is not a run, and neither is a path that climbs out of the runs folder.
+  if (id === "" || id === EVAL_RUNS || id.includes("/") || id.includes("\\") || id === "." || id === "..") return undefined;
+  for (const dir of runId === id ? [own, evalRunsDir(agent, env)] : [evalRunsDir(agent, env)]) {
+    const bundle = ProofBundle.open(dir, id);
+    if (bundle) return { bundle, runsDir: dir };
+  }
+  return undefined;
+}
+
+/** Run ids in a folder, newest first. Run ids start with a timestamp or a case name, so the order is by name. */
+function idsIn(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== EVAL_RUNS)
+    .map((e) => e.name)
+    .sort()
+    .reverse();
+}
+
+/** The runs a person made, and how many the eval suite left beside them. */
+export function listRuns(agent: Agent, env: NodeJS.ProcessEnv = process.env): { dir: string; ids: string[]; evalDir: string; evalCount: number } {
+  const dir = runsDir(agent, env);
+  const evalDir = evalRunsDir(agent, env);
+  return { dir, ids: idsIn(dir), evalDir, evalCount: idsIn(evalDir).length };
+}

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