@codespar/cli 0.14.1 → 0.16.0

package/templates/collections-agent/agents/collections-agent/src/commands/reconcile.ts

@@ -1,38 +0,0 @@
-/**
- * `npm run reconcile [--json]`: compares local state with the rail. Names
- * executions without an outcome, receivables the rail never saw, paid
- * charges the bundle does not hold. Read-only on the rail: an `executing`
- * execution is closed only from what the rail says, and nothing is issued.
- */
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { stderr, stdout } from "node:process";
-import { readDotEnv, runsDir, setup } from "../setup.js";
-
-const json = process.argv.includes("--json");
-const say = (l: string) => stderr.write(l + "\n");
-readDotEnv();
-const s = setup({ say, runId: `run_reconcile_${Date.now().toString(36)}` });
-try {
-  const findings: Array<{ execution_id: string; kind: string; detail: string }> = [];
-  for (const e of s.engine.list()) {
-    if (e.state === "executing") {
-      const closed = await s.engine.reconcile(e.id);
-      findings.push({ execution_id: e.id, kind: closed.state === "executing" ? (closed.reason === "awaiting_settlement" ? "awaiting_payer" : "still_uncertain") : "closed_from_rail", detail: `executing -> ${closed.state}${closed.detail ? ` (${closed.detail})` : ""}` });
-      continue;
-    }
-    for (const o of e.outcomes) {
-      if (o.receipt_id && !existsSync(join(runsDir(), e.run_id, "receipts", `${o.receipt_id}.json`))) {
-        findings.push({ execution_id: e.id, kind: "record_missing_locally", detail: `paid charge ${o.receipt_id} is not in runs/${e.run_id}/receipts` });
-      }
-    }
-    const outbox = s.store.getOutbox(e.idempotency_key);
-    if (e.state === "settled" && outbox?.status !== "done") findings.push({ execution_id: e.id, kind: "outbox_mismatch", detail: `settled but outbox is ${outbox?.status ?? "absent"}` });
-  }
-  for (const f of findings) say(`${f.kind} ${f.execution_id}: ${f.detail}`);
-  if (json) stdout.write(JSON.stringify({ executions: s.engine.list().length, findings }) + "\n");
-  else say(findings.length ? `${findings.length} finding(s)` : "local state and rail agree");
-  process.exit(0);
-} finally {
-  s.close();
-}

package/templates/collections-agent/agents/collections-agent/src/commands/rerun.ts

@@ -1,55 +0,0 @@
-/**
- * `npm run rerun <run-id> [--json]`: replays a recorded run against the
- * deterministic provider and the stub rail, with no network, in a fresh
- * state, and compares the sequence of states with the original bundle. The
- * model's outputs are the recording; the payer's behaviour is read from the
- * recorded outcomes (paid, expired); every decision of the core is recomputed.
- */
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { stderr, stdout } from "node:process";
-import { ProofBundle, type ApprovalMode, type Execution } from "@codespar/agent-core";
-import { handleExecution } from "../../channels/terminal/index.js";
-import { runsDir, setup } from "../setup.js";
-
-const argv = process.argv.slice(2);
-const json = argv.includes("--json");
-const runId = argv.find((a) => !a.startsWith("--"));
-const say = (l: string) => stderr.write(l + "\n");
-if (!runId) {
-  say("usage: npm run rerun <run-id> [--json]");
-  process.exit(2);
-}
-const original = ProofBundle.open(runsDir(), runId);
-if (!original) {
-  say(`no bundle at runs/${runId}`);
-  process.exit(1);
-}
-const meta = original.readMeta() ?? {};
-const mode = (meta["mode"] as ApprovalMode | undefined) ?? "human";
-const events = original.readEvents();
-const originalTrail = events.filter((e) => e["type"] === "execution.transition").map((e) => (e["payload"] as { to: string }).to);
-const originalDecisions = events.filter((e) => e["type"] === "approval.created").map((e) => ((e["payload"] as { approver: { type: string } }).approver.type === "person" ? "approve" : "mandate"));
-const userTurns = original.readTranscript().filter((l) => l.kind === "user").map((l) => l["text"] as string);
-// The payer's behaviour is part of the recording: a receivable that expired in the original run expires in the rerun.
-const expired = events.some((e) => e["type"] === "execution.transition" && (e["payload"] as { reason?: string }).reason === "charge_expired");
-const transcriptPath = join(original.dir, "transcript.jsonl");
-
-const s = setup({ mode, rail: "stub", provider: "replay", transcript: transcriptPath, runId: `${runId}_rerun_${Date.now().toString(36)}`, stateDir: mkdtempSync(join(tmpdir(), "collections-rerun-")), stubRail: { payer: expired ? "expires" : "pays" }, say });
-try {
-  let decisionIndex = 0;
-  const runtime = s.makeRuntime();
-  const loop = s.makeLoop(runtime, (execution: Execution) => {
-    const decision = execution.state === "awaiting_approval" ? (originalDecisions[decisionIndex++] === "approve" ? "approve" : "deny") : "none";
-    return handleExecution(execution, { setup: s, approver: { id: "usr_rerun", channel: "terminal" }, decision, say, tell: () => undefined, simulatePayer: !expired });
-  });
-  for (const text of userTurns) await loop.turn(text);
-  const trail = s.store.listEvents({ run_id: s.runId }).filter((e) => e.type === "execution.transition").map((e) => (e.payload as { to: string }).to);
-  const same = JSON.stringify(trail) === JSON.stringify(originalTrail);
-  if (json) stdout.write(JSON.stringify({ run_id: runId, rerun_id: s.runId, same_states: same, original: originalTrail, rerun: trail, bundle_dir: s.bundle.dir }) + "\n");
-  say(same ? `rerun ok: ${trail.length} transition(s), same sequence as ${runId}` : `rerun DIFFERS: original ${JSON.stringify(originalTrail)} vs rerun ${JSON.stringify(trail)}`);
-  process.exit(same ? 0 : 1);
-} finally {
-  s.close();
-}

package/templates/collections-agent/agents/collections-agent/src/commands/resume.ts

@@ -1,30 +0,0 @@
-/**
- * `npm run resume [--json]`: after a crash or a restart. Executions left in
- * `executing` are reconciled against the rail (idempotent on attempt_id),
- * never repeated: a receivable already issued is looked at, not re-issued;
- * one whose outbox is still pending goes out once. Stale open ones expire.
- */
-import { stderr, stdout } from "node:process";
-import { readDotEnv, setup } from "../setup.js";
-
-const json = process.argv.includes("--json");
-const say = (l: string) => stderr.write(l + "\n");
-readDotEnv();
-const s = setup({ say, runId: `run_resume_${Date.now().toString(36)}` });
-try {
-  const resumed = [];
-  for (const stuck of s.engine.list({ state: "executing" })) {
-    const closed = await s.engine.resumePending(stuck.id);
-    resumed.push({ id: closed.id, state: closed.state, reason: closed.reason ?? null, detail: closed.detail ?? null, charge_ids: closed.outcomes.map((o) => o.transaction_id ?? null), receipt_ids: closed.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id) });
-    say(closed.state === "executing" ? `${closed.id}: still executing (${closed.reason}) — ${closed.detail}; nothing was re-issued; \`npm run poll\` keeps looking` : `${closed.id}: executing -> ${closed.state}`);
-  }
-  const expired = s.engine.expireStale().map((e) => ({ id: e.id, state: e.state }));
-  for (const e of expired) say(`${e.id}: -> expired`);
-  const open = s.engine.list({ state: ["awaiting_approval", "approved"] }).map((e) => ({ id: e.id, state: e.state }));
-  for (const e of open) say(`${e.id}: still ${e.state}; decide it with npm run approve ${e.id} / npm run deny ${e.id}`);
-  if (json) stdout.write(JSON.stringify({ resumed, expired, open, bundle_dir: s.bundle.dir }) + "\n");
-  else say(resumed.length || expired.length ? "resume done" : "nothing to resume");
-  process.exit(resumed.some((r) => r.state === "executing" && r.reason !== "awaiting_settlement") ? 3 : 0);
-} finally {
-  s.close();
-}

package/templates/collections-agent/agents/collections-agent/src/commands/webhook.ts

@@ -1,36 +0,0 @@
-/**
- * `npm run webhook [--port <n>] [--secret <trigger secret>]`: starts the
- * receiving end of `channels/webhook` on localhost. A stub for the
- * developer who has a URL the API can reach; the terminal's default is
- * `npm run poll`. Reads `COLLECTIONS_WEBHOOK_PORT` and
- * `COLLECTIONS_TRIGGER_SECRET` when the flags are absent.
- */
-import { stderr, stdout } from "node:process";
-import { announceOutcome } from "../../channels/terminal/index.js";
-import { startWebhookServer } from "../../channels/webhook/index.js";
-import { readDotEnv, setup } from "../setup.js";
-
-const argv = process.argv.slice(2);
-readDotEnv();
-const port = Number(argv.includes("--port") ? argv[argv.indexOf("--port") + 1] : process.env["COLLECTIONS_WEBHOOK_PORT"] ?? "8787");
-const secret = argv.includes("--secret") ? argv[argv.indexOf("--secret") + 1] : process.env["COLLECTIONS_TRIGGER_SECRET"];
-const say = (l: string) => stderr.write(l + "\n");
-const s = setup({ say, runId: `run_webhook_${Date.now().toString(36)}` });
-const server = startWebhookServer(
-  port,
-  {
-    engine: s.engine,
-    secret,
-    onClosed: (execution) => {
-      announceOutcome(execution, s, (l) => stdout.write(l + "\n"));
-    },
-  },
-  say,
-);
-const stop = () => {
-  server.close();
-  s.close();
-  process.exit(0);
-};
-process.on("SIGINT", stop);
-process.on("SIGTERM", stop);

package/templates/collections-agent/agents/collections-agent/src/main.ts

@@ -1,193 +0,0 @@
-/**
- * `npm start`                                                  interactive terminal (you are the payer)
- * `npm start -- --input "oi, recebi a mensagem do acordo 1042"`  one turn, no prompt
- * `npm start -- --scenario happy-path`                         a scenario pack, both modes it declares
- *
- * `--json` puts machine data on stdout (valid JSON, nothing else) and the
- * human messages on stderr.
- */
-import { stderr, stdout } from "node:process";
-import { relative, resolve } from "node:path";
-import { NotATestKeyError, isTestKey } from "@codespar/agent-core";
-import { closeTerminal, handleExecution, interactive } from "../channels/terminal/index.js";
-import { checkScenario, listScenarios, loadScenario, runScenario, scenariosDir } from "./scenarios.js";
-import { readDotEnv, resolveRailKind, setup, type RailKind } from "./setup.js";
-
-interface Args {
-  input?: string;
-  scenario?: string;
-  mode?: "human" | "mandate";
-  json: boolean;
-  decision?: "approve" | "deny";
-  provider?: "anthropic" | "replay";
-  transcript?: string;
-  rail?: RailKind;
-  user: string;
-  wait?: number;
-  simulatePayer: boolean;
-  payer?: "pays" | "expires" | "never";
-  help: boolean;
-}
-
-export function parseArgs(argv: string[]): Args {
-  const args: Args = { json: false, user: "usr_operator", simulatePayer: false, help: false };
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i]!;
-    const next = () => {
-      const v = argv[i + 1];
-      if (v === undefined) throw new Error(`${a} needs a value`);
-      i += 1;
-      return v;
-    };
-    if (a === "--input") args.input = next();
-    else if (a === "--scenario") args.scenario = next();
-    else if (a === "--mode") {
-      const v = next();
-      if (v !== "human" && v !== "mandate") throw new Error("--mode must be human or mandate");
-      args.mode = v;
-    } else if (a === "--json") args.json = true;
-    else if (a === "--approve") args.decision = "approve";
-    else if (a === "--deny") args.decision = "deny";
-    else if (a === "--provider") {
-      const v = next();
-      if (v !== "anthropic" && v !== "replay") throw new Error("--provider must be anthropic or replay");
-      args.provider = v;
-    } else if (a === "--transcript") args.transcript = next();
-    else if (a === "--rail") {
-      const v = next();
-      if (v !== "stub" && v !== "api") throw new Error("--rail must be stub or api");
-      args.rail = v;
-    } else if (a === "--user") args.user = next();
-    else if (a === "--wait") {
-      const v = Number(next());
-      if (!Number.isFinite(v) || v < 0) throw new Error("--wait must be a number of seconds");
-      args.wait = v;
-    } else if (a === "--simulate-payer") args.simulatePayer = true;
-    else if (a === "--payer") {
-      const v = next();
-      if (v !== "pays" && v !== "expires" && v !== "never") throw new Error("--payer must be pays, expires or never");
-      args.payer = v;
-    } else if (a === "--help" || a === "-h") args.help = true;
-    else throw new Error(`unknown argument ${a}`);
-  }
-  return args;
-}
-
-const USAGE = `collections-agent
-  npm start                                                    interactive terminal (you are the payer)
-  npm start -- --input "oi, recebi a mensagem do acordo 1042"    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>
-         --wait <seconds>  --simulate-payer  --payer pays|expires|never (stub only)  --json`;
-
-export async function main(argv = process.argv.slice(2)): Promise<number> {
-  let args: Args;
-  try {
-    args = parseArgs(argv);
-  } catch (err) {
-    stderr.write(`${err instanceof Error ? err.message : String(err)}\n${USAGE}\n`);
-    return 2;
-  }
-  if (args.help) {
-    stderr.write(USAGE + "\n");
-    return 0;
-  }
-  readDotEnv();
-  const say = (line: string) => stderr.write(line + "\n");
-
-  // 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);
-    return 1;
-  }
-
-  if (args.scenario) return runScenarioCommand(args, railKind, say);
-
-  // One-shot without a model: replay the recorded scenario whose first turn is this input.
-  let transcript = args.transcript;
-  const provider = args.provider ?? (process.env["ANTHROPIC_API_KEY"] && process.env["ANTHROPIC_API_KEY"] !== "sk-ant-your_key_here" ? "anthropic" : "replay");
-  if (provider === "replay" && !transcript && args.input) {
-    const match = listScenarios().map(loadScenario).find((s) => s.turns[0].input === args.input);
-    if (match) transcript = resolve(scenariosDir(), match.transcript);
-    else {
-      say(`no ANTHROPIC_API_KEY and no recorded transcript for that input. Set the key, pass --transcript, or use one of: ${listScenarios().map((n) => `"${loadScenario(n).turns[0].input}"`).join(", ")}`);
-      return 1;
-    }
-  }
-
-  const s = setup({ mode: args.mode, rail: railKind, provider, transcript, say });
-  if (args.payer) s.payer.behave(args.payer);
-  const approver = { id: args.user, channel: "terminal" };
-  const started = Date.now();
-  try {
-    const runtime = s.makeRuntime();
-    if (!args.input) {
-      await interactive({ setup: s, approver, runtime, say, waitSeconds: args.wait, simulatePayer: args.simulatePayer });
-      return 0;
-    }
-    const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, { setup: s, approver, decision: args.decision ?? "none", say, waitSeconds: args.wait, simulatePayer: args.simulatePayer, tell: args.json ? say : undefined }));
-    const result = await loop.turn(args.input);
-    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
-    const payload = {
-      run_id: s.runId,
-      agent: `${s.manifest.manifest.name}@${s.manifest.manifest.version}`,
-      mode: s.mode,
-      rail: s.railKind,
-      policy_id: s.mandate.id,
-      actor: s.engine.agentActor,
-      reply: result.reply,
-      tool_calls: result.tool_calls,
-      executions: executions.map((e) => ({
-        id: e.id,
-        state: e.state,
-        reason: e.reason ?? null,
-        escalation: e.escalation ?? null,
-        total_minor: e.total,
-        items: e.items.map((i) => ({ debtor: i.beneficiary, amount_minor: i.amount, due_date: i.due_date ?? null })),
-        approval_id: e.approval_id ?? null,
-        charges: e.outcomes.map((o) => ({ instalment: o.index + 1, charge_id: o.transaction_id ?? null, status: o.status, code: o.code ?? null, payable: o.instrument?.payable ?? null, pix_copy_paste: o.instrument?.pix_copy_paste ?? null })),
-        receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
-      })),
-      receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
-      bundle_dir: relative(process.cwd(), s.bundle.dir),
-      seconds: Math.round(((Date.now() - started) / 1000) * 10) / 10,
-    };
-    if (args.json) stdout.write(JSON.stringify(payload) + "\n");
-    else stdout.write(result.reply + "\n");
-    return executions.some((e) => e.state === "executing") ? 3 : 0;
-  } finally {
-    closeTerminal();
-    s.close();
-  }
-}
-
-async function runScenarioCommand(args: Args, railKind: RailKind, say: (l: string) => void): Promise<number> {
-  const scenario = loadScenario(args.scenario!);
-  if (!scenario.rails.includes(railKind)) {
-    say(`scenario ${scenario.name} runs on ${scenario.rails.join("/")} only (asked: ${railKind})`);
-    return 2;
-  }
-  const modes = args.mode ? [args.mode] : scenario.modes;
-  const results = [];
-  for (const mode of modes) {
-    say(`== scenario ${scenario.name} — approval: ${mode} — rail: ${railKind}`);
-    say(scenario.description);
-    const run = await runScenario(scenario, { mode, rail: railKind, say: args.json ? () => undefined : say, tell: args.json ? () => undefined : (l) => stdout.write(l + "\n"), waitSeconds: args.wait });
-    const check = checkScenario(scenario, run);
-    for (const reply of run.replies) say(`agente: ${reply}`);
-    say(check.ok ? `== ok — ${run.cycle_seconds}s — bundle em ${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, rail: railKind, results }) + "\n");
-  return results.every((r) => r.ok) ? 0 : 1;
-}
-
-if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
-  main()
-    .then((code) => process.exit(code))
-    .catch((err) => {
-      stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
-      process.exit(1);
-    });
-}

package/templates/collections-agent/agents/collections-agent/src/setup.ts

@@ -1,250 +0,0 @@
-/**
- * Wires the core for this agent: manifest, guardrails, envelope, collection
- * policy, state, rail, status source, signer, bundle, provider. Everything
- * the commands and the terminal channel share.
- *
- * There is no consent step: the collection policy is the MERCHANT's own
- * (the receiving side has no API-signed policy today, section 16), so the
- * example file is the policy in both rails. With a test key the rail is the
- * CodeSpar sandbox (`POST /v1/charges`) and the payer is the sandbox route.
- */
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import {
-  LocalMandateStatusStub,
-  AgentLoop,
-  CodeSparChargeRail,
-  ExecutionEngine,
-  ProofBundle,
-  ReplayRuntime,
-  StateStore,
-  StubChargeRail,
-  createCodeSparClient,
-  isTestKey,
-  loadGuardrails,
-  loadManifest,
-  loadMandate,
-  loadOrCreateLocalApprovalKey,
-  loadToolsFile,
-  newRunId,
-  NotATestKeyError,
-  paySandboxCharge,
-  type AgentRuntime,
-  type ApprovalMode,
-  type Execution,
-  type LoadedManifest,
-  type Mandate,
-  type MandateStatusSource,
-  type PaymentRail,
-  type StubChargeRailOptions,
-  type StubPayerBehaviour,
-  type ToolHandler,
-} from "@codespar/agent-core";
-import { AnthropicRuntime } from "@codespar/agent-core/providers/anthropic";
-import type { ApiClient } from "@codespar/sdk";
-import { envelopePolicy, loadEnvelope, type Envelope } from "./envelope.js";
-import { makeHandlers } from "./modules/bolepix-receivables.js";
-
-export const AGENT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-export const STATE_DIR = join(AGENT_DIR, ".codespar");
-export const RUNS_DIR = join(AGENT_DIR, "runs");
-
-/** The runs folder in use: the agent's own, or the scratch one the restart test points at. */
-export function runsDir(env: NodeJS.ProcessEnv = process.env): string {
-  return env["COLLECTIONS_RUNS_DIR"] ?? RUNS_DIR;
-}
-
-export type RailKind = "stub" | "api";
-
-/**
- * Who plays the debtor. With the stub rail it is the fixture inside the
- * rail; with a test key it is `POST /v1/test/charges/{id}/pay`, which the
- * kit calls only when a scenario or `--simulate-payer` asks for it.
- */
-export interface SandboxPayer {
-  kind: "stub" | "api";
-  /** Pays a receivable this run issued. Returns what the payer reported, or the refusal. */
-  pay(chargeId: string, attemptId: string): Promise<{ ok: true; detail: string } | { ok: false; detail: string }>;
-  /** Stub only: what the fixture does with receivables issued from now on. */
-  behave(behaviour: StubPayerBehaviour): void;
-}
-
-export interface SetupOptions {
-  mode?: ApprovalMode | undefined;
-  rail?: RailKind | undefined;
-  provider?: "anthropic" | "replay" | undefined;
-  transcript?: string | undefined;
-  runId?: string | undefined;
-  runsDir?: string | undefined;
-  stateDir?: string | undefined;
-  now?: (() => Date) | undefined;
-  stubRail?: StubChargeRailOptions | undefined;
-  /** Use this policy instead of the example one (tests). */
-  mandate?: Mandate | undefined;
-  env?: NodeJS.ProcessEnv;
-  say?: ((line: string) => void) | undefined;
-}
-
-export interface Setup {
-  manifest: LoadedManifest;
-  mode: ApprovalMode;
-  mandate: Mandate;
-  envelope: Envelope;
-  store: StateStore;
-  gate: LocalMandateStatusStub;
-  rail: PaymentRail;
-  railKind: RailKind;
-  api: ApiClient | undefined;
-  payer: SandboxPayer;
-  status: MandateStatusSource;
-  bundle: ProofBundle;
-  runId: string;
-  engine: ExecutionEngine;
-  system: string;
-  handlers: Record<string, ToolHandler>;
-  tools: ReturnType<typeof loadToolsFile>;
-  /** Milliseconds between two looks at an issued receivable: 0 on the stub, a few seconds on the API. */
-  pollIntervalMs: number;
-  makeLoop(runtime: AgentRuntime, onExecution: (execution: Execution) => Promise<Execution>): AgentLoop;
-  makeRuntime(): AgentRuntime;
-  close(): void;
-}
-
-export function readDotEnv(agentDir = AGENT_DIR): void {
-  const path = join(agentDir, ".env");
-  if (!existsSync(path)) return;
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    const m = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
-    if (!m || !m[1]) continue;
-    const value = (m[2] ?? "").replace(/^["']|["']$/g, "");
-    if (process.env[m[1]] === undefined) process.env[m[1]] = value;
-  }
-}
-
-export function resolveRailKind(env: NodeJS.ProcessEnv, requested: RailKind | undefined): RailKind {
-  if (requested) return requested;
-  const key = env["CODESPAR_API_KEY"];
-  if (!key || key === "csk_test_your_key_here") return "stub";
-  return "api";
-}
-
-export function setup(options: SetupOptions = {}): Setup {
-  const env = options.env ?? process.env;
-  const say = options.say ?? ((line: string) => process.stderr.write(line + "\n"));
-  const manifest = loadManifest(join(AGENT_DIR, "agent.yaml"));
-  const guardrails = loadGuardrails(manifest.resolvePath(manifest.manifest.guardrails));
-  const envelope = loadEnvelope(guardrails);
-  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;
-  if (!manifest.manifest.approval.includes(mode)) throw new Error(`agent.yaml does not support approval: ${mode}`);
-
-  // COLLECTIONS_STATE_DIR / COLLECTIONS_RUNS_DIR exist for the restart test, which drives a child process over a scratch state.
-  const stateDir = options.stateDir ?? env["COLLECTIONS_STATE_DIR"] ?? STATE_DIR;
-  const runs = options.runsDir ?? runsDir(env);
-  const store = new StateStore(join(stateDir, "state.db"));
-  // The collection policy is the merchant's own file: there is no `GET /v1/mandates/{id}` to read for it, so the section 4.7 gate
-  // is the local stub in BOTH rails (the bills-agent reads the API with a test key). See docs/OPEN_QUESTIONS.md section 25.
-  const gate = new LocalMandateStatusStub(store, options.now);
-  const signer = loadOrCreateLocalApprovalKey(stateDir);
-  const mandate = options.mandate ?? loadMandate(manifest.resolvePath(manifest.manifest.mandate_schema));
-
-  const railKind = resolveRailKind(env, options.rail);
-  let api: ApiClient | undefined;
-  let rail: PaymentRail;
-  let payer: SandboxPayer;
-  let pollIntervalMs: number;
-  if (railKind === "api") {
-    if (!isTestKey(env["CODESPAR_API_KEY"])) throw new NotATestKeyError();
-    const client = createCodeSparClient({ apiKey: env["CODESPAR_API_KEY"], baseUrl: env["CODESPAR_API_URL"], projectId: env["CODESPAR_PROJECT_ID"] });
-    api = client;
-    rail = new CodeSparChargeRail(client);
-    pollIntervalMs = 3000;
-    payer = {
-      kind: "api",
-      async pay(chargeId) {
-        const result = await paySandboxCharge(client, chargeId);
-        if (!result.ok) return { ok: false, detail: `${result.failure.code}: ${result.failure.message}` };
-        const s = result.state;
-        return { ok: true, detail: `sandbox payer: ${s.charge_id} ${s.status} (${s.payment}, ${s.paid_minor} of ${s.quoted_minor}), simulated=${s.simulated}, settled_against=${s.settled_against}, money_moved=${s.money_moved}${s.idempotent_replay ? ", replay" : ""}` };
-      },
-      behave() {
-        /* the API's payer is a route, not a fixture; a scenario that needs "expires" declares rails: [stub] */
-      },
-    };
-  } else {
-    // COLLECTIONS_KILL_AFTER_DISPATCH=1 simulates a crash right after the issuer accepted the charge and before the outcome was recorded.
-    const killAfterDispatch = env["COLLECTIONS_KILL_AFTER_DISPATCH"] === "1" ? { afterDispatch: () => process.exit(137) } : {};
-    // COLLECTIONS_STUB_PAYER=pays|expires|never: what the fixture payer does, from a test process.
-    const behaviour = env["COLLECTIONS_STUB_PAYER"];
-    const fixture: Pick<StubChargeRailOptions, "payer"> = behaviour === "pays" || behaviour === "expires" || behaviour === "never" ? { payer: behaviour } : {};
-    const refuse = env["COLLECTIONS_STUB_REFUSE"] ? { refusePayees: env["COLLECTIONS_STUB_REFUSE"].split(",").map((p) => p.trim()).filter(Boolean) } : {};
-    const stub = new StubChargeRail(store, { ...(options.now ? { clock: options.now } : {}), ...killAfterDispatch, ...fixture, ...refuse, ...(options.stubRail ?? {}) });
-    rail = stub;
-    pollIntervalMs = 0;
-    payer = {
-      kind: "stub",
-      async pay(_chargeId, attemptId) {
-        stub.decide(attemptId, "pays");
-        return { ok: true, detail: "stub payer: will pay at the next look" };
-      },
-      behave: (b) => stub.setPayer(b),
-    };
-  }
-
-  const runId = options.runId ?? newRunId(mode);
-  const bundle = new ProofBundle(runs, runId);
-  bundle.mandateSnapshot(mandate);
-  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, started_at: (options.now ?? (() => new Date()))().toISOString() });
-
-  const engine = new ExecutionEngine({
-    store,
-    rail,
-    status: gate,
-    signer,
-    manifest: manifest.manifest,
-    guardrails: { ...guardrails, approval: mode },
-    mandate,
-    bundle,
-    mode,
-    runId,
-    onBehalfOf: mandate.consumer_id,
-    policyExtension: envelopePolicy(envelope),
-    ...(options.now ? { clock: options.now } : {}),
-  });
-
-  const handlers = makeHandlers(envelope);
-
-  const makeRuntime = (): AgentRuntime => {
-    const provider = options.provider ?? (env["ANTHROPIC_API_KEY"] && env["ANTHROPIC_API_KEY"] !== "sk-ant-your_key_here" ? "anthropic" : "replay");
-    if (provider === "anthropic") return new AnthropicRuntime({ apiKey: env["ANTHROPIC_API_KEY"] });
-    if (!options.transcript) throw new Error("the replay provider needs a transcript (--transcript <file> or --scenario <name>)");
-    say(`[replay] no ANTHROPIC_API_KEY: replaying ${options.transcript}`);
-    return ReplayRuntime.fromFile(options.transcript);
-  };
-
-  return {
-    manifest,
-    mode,
-    mandate,
-    envelope,
-    store,
-    gate,
-    rail,
-    railKind,
-    api,
-    payer,
-    status: gate,
-    bundle,
-    runId,
-    engine,
-    system,
-    handlers,
-    tools,
-    pollIntervalMs,
-    makeRuntime,
-    makeLoop: (runtime, onExecution) => new AgentLoop({ runtime, tools, handlers, system, bundle, engine, onExecution, ...(options.now ? { clock: options.now } : {}) }),
-    close: () => store.close(),
-  };
-}