@codespar/cli 0.13.0 → 0.14.1

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

@@ -0,0 +1,38 @@
+/**
+ * `npm run reconcile [--json]`: compares local state with the rail. Names
+ * executions without an outcome, attempts the rail never saw, receipts the
+ * rail sealed that the bundle does not hold. Read-only unless an execution
+ * is in `executing`, which it closes from what the rail says.
+ */
+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" ? "still_uncertain" : "closed_from_rail", detail: `executing -> ${closed.state}` });
+      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: "receipt_missing_locally", detail: `receipt ${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/bills-agent/agents/bills-agent/src/commands/rerun.ts

@@ -0,0 +1,65 @@
+/**
+ * `npm run rerun <run-id> [--json]`: replays a recorded run against the
+ * deterministic provider, with no network, in a fresh state, and compares
+ * the sequence of states with the original bundle. The model's outputs are
+ * the recording; every decision of the core is recomputed.
+ */
+import { mkdtempSync, readFileSync } 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 originalTrail = original
+  .readEvents()
+  .filter((e) => e["type"] === "execution.transition")
+  .map((e) => (e["payload"] as { to: string }).to);
+const originalDecisions = original.readEvents().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 rail's answers are part of the recording: a payee the rail refused in the original run is refused in the rerun.
+const events = original.readEvents();
+const dispatched = new Map(events.filter((e) => e["type"] === "rail.dispatch").map((e) => [(e["payload"] as { attempt_id: string }).attempt_id, (e["payload"] as { payee: string }).payee]));
+const refusedPayees = events
+  .filter((e) => e["type"] === "rail.outcome" && (e["payload"] as { status: string }).status === "failed")
+  .map((e) => dispatched.get((e["payload"] as { attempt_id: string }).attempt_id))
+  .filter((p): p is string => typeof p === "string");
+const transcriptPath = join(original.dir, "transcript.jsonl");
+readFileSync(transcriptPath, "utf8");
+
+const s = setup({ mode, rail: "stub", provider: "replay", transcript: transcriptPath, runId: `${runId}_rerun_${Date.now().toString(36)}`, stateDir: mkdtempSync(join(tmpdir(), "bills-rerun-")), stubRail: { refusePayees: refusedPayees }, 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 });
+  });
+  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 outcomesOf = (list: Record<string, unknown>[]) => list.filter((e) => e["type"] === "rail.outcome").map((e) => (e["payload"] as { status: string }).status);
+  const originalOutcomes = outcomesOf(events);
+  const rerunOutcomes = outcomesOf(s.bundle.readEvents());
+  const same = JSON.stringify(trail) === JSON.stringify(originalTrail) && JSON.stringify(rerunOutcomes) === JSON.stringify(originalOutcomes);
+  if (json) stdout.write(JSON.stringify({ run_id: runId, rerun_id: s.runId, same_states: same, original: originalTrail, rerun: trail, original_outcomes: originalOutcomes, rerun_outcomes: rerunOutcomes, 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/bills-agent/agents/bills-agent/src/commands/resume.ts

@@ -0,0 +1,30 @@
+/**
+ * `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; 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 = [];
+  // Only resume dispatches, and only what the outbox proves was never sent; everything else is reconciled from the rail.
+  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, detail: closed.detail ?? null, receipt_ids: closed.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id) });
+    say(closed.state === "executing" ? `${closed.id}: still executing — ${closed.detail}; nothing was re-sent` : `${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") ? 3 : 0);
+} finally {
+  s.close();
+}

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

@@ -0,0 +1,185 @@
+/**
+ * `npm start`                                  interactive terminal
+ * `npm start -- --input "pague a escola de outubro"`   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, defaultAsk, handleExecution, interactive } from "../channels/terminal/index.js";
+import { runEmbeddedConsent, loadLocalMandate } from "./modules/embedded-consent.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, scenariosDir } from "./scenarios.js";
+import { AGENT_DIR, MANDATE_PATH, NoMandateError, readDotEnv, resolveRailKind, setup, type RailKind } from "./setup.js";
+import { loadMandate, createCodeSparClient } from "@codespar/agent-core";
+
+interface Args {
+  input?: string;
+  scenario?: string;
+  mode?: "human" | "mandate";
+  json: boolean;
+  decision?: "approve" | "deny";
+  provider?: "anthropic" | "replay";
+  transcript?: string;
+  rail?: RailKind;
+  user: string;
+  help: boolean;
+}
+
+export function parseArgs(argv: string[]): Args {
+  const args: Args = { json: false, user: "usr_terminal", 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 === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return args;
+}
+
+const USAGE = `bills-agent
+  npm start                                         interactive terminal
+  npm start -- --input "pague a escola de outubro"  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`;
+
+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");
+
+  if (args.scenario) return runScenarioCommand(args, say);
+
+  // 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;
+  }
+
+  // Embedded consent: with a test key and no signed mandate, the mandate is born first.
+  if (railKind === "api" && !loadLocalMandate(MANDATE_PATH)) {
+    if (args.input) {
+      say(new NoMandateError().message);
+      return 1;
+    }
+    const api = createCodeSparClient({ apiKey: process.env["CODESPAR_API_KEY"], baseUrl: process.env["CODESPAR_API_URL"], projectId: process.env["CODESPAR_PROJECT_ID"] });
+    const example = loadMandate(resolve(AGENT_DIR, "mandate.example.json"));
+    await runEmbeddedConsent({ api, example, mandatePath: MANDATE_PATH, say, confirm: async (q: string) => /^(s|sim|y|yes)$/i.test((await defaultAsk(q)).trim()) });
+  }
+
+  // One-shot without a model: replay the recorded happy-path when the input is its first turn.
+  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 });
+  const approver = { id: args.user, channel: "terminal" };
+  try {
+    const runtime = s.makeRuntime();
+    if (!args.input) {
+      await interactive({ setup: s, approver, runtime, say });
+      return 0;
+    }
+    const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, { setup: s, approver, decision: args.decision ?? "none", say }));
+    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,
+      mandate_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) => ({ 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),
+      })),
+      receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
+      bundle_dir: relative(process.cwd(), s.bundle.dir),
+    };
+    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, say: (l: string) => void): Promise<number> {
+  const scenario = loadScenario(args.scenario!);
+  const modes = args.mode ? [args.mode] : scenario.modes;
+  const results = [];
+  for (const mode of modes) {
+    say(`== scenario ${scenario.name} — approval: ${mode}`);
+    say(scenario.description);
+    const run = await runScenario(scenario, { mode, say: args.json ? () => undefined : say });
+    const check = checkScenario(scenario, run);
+    for (const reply of run.replies) say(`agente: ${reply}`);
+    say(check.ok ? `== ok — 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, 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/bills-agent/agents/bills-agent/src/modules/embedded-consent.ts

@@ -0,0 +1,125 @@
+/**
+ * Module `embedded-consent`: the mandate is born at a consent the CONSUMER
+ * authorizes. In the sandbox the kit runs the `partner` surface: it is the
+ * partner's backend, the titular is at the keyboard, and the submit carries
+ * an `in_person` attestation. That is what hands the kit the signed envelope
+ * `{ mandate, signature }`, which `POST /v1/consumer-payments/execute`
+ * presents on every spend. The `hosted` surface (a page the consumer opens)
+ * returns the envelope to a `callback_url` a terminal kit does not have;
+ * see docs/OPEN_QUESTIONS.md.
+ *
+ * With a test key and no `.codespar/mandate.json`, `npm start` runs this
+ * first. The stored file carries the signature: mode 0600, never in the
+ * bundle, never committed.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ApiClient } from "@codespar/sdk";
+import { MandateSchema, windowCap, type Mandate, describeApiError } from "@codespar/agent-core";
+
+export interface ConsentOptions {
+  api: ApiClient;
+  example: Mandate;
+  mandatePath: string;
+  /** Where to write the lines the person reads. */
+  say: (line: string) => void;
+  /** Asks the titular to authorize. Returns true on yes. */
+  confirm: (question: string) => Promise<boolean>;
+  /** The consumer this mandate is for. Defaults to the example's. */
+  consumerId?: string;
+  now?: () => Date;
+}
+
+const YEAR_SECONDS = 365 * 24 * 3600;
+
+export function loadLocalMandate(path: string): Mandate | undefined {
+  if (!existsSync(path)) return undefined;
+  return MandateSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export async function runEmbeddedConsent(options: ConsentOptions): Promise<Mandate> {
+  const { api, example, say } = options;
+  const now = options.now ?? (() => new Date());
+  const consumerId = options.consumerId ?? example.consumer_id;
+
+  const init = await api.post("/v1/consents/init", {
+    body: {
+      agent_id: example.agent_id,
+      intent: {
+        purpose: example.purpose,
+        cap_minor: example.cap_minor,
+        per_tx_cap_minor: example.per_tx_cap_minor,
+        currency: "BRL",
+        mandate_ttl_seconds: YEAR_SECONDS,
+        merchant_allowlist: example.beneficiaries.map((b) => b.payee),
+        merchant_pin_kind: "pix-key",
+        ...(example.periodic_cap ? { periodic_cap: example.periodic_cap } : {}),
+        display_name: "bills-agent: contas do mes",
+        intent_note: `Pagar as contas do mes aos favorecidos nomeados: ${example.beneficiaries.map((b) => b.name).join(", ")}.`,
+      },
+      surface: "partner",
+    },
+  });
+
+  say("");
+  say("O mandato ainda nao existe. Este e o consentimento que o titular assina (sandbox):");
+  say(`  agente: ${example.agent_id}    finalidade: ${example.purpose}`);
+  say(`  teto por pagamento: ${example.per_tx_cap_minor} centavos    teto do mes: ${windowCap(example)} centavos    vitalicio: ${example.cap_minor} centavos`);
+  for (const b of example.beneficiaries) say(`  favorecido: ${b.name} (${b.alias})`);
+  say(`  validade: 1 ano    (o token do consentimento vale ate ${init.expires_at})`);
+  const yes = await options.confirm("  Voce e o titular e autoriza este mandato? [s/N] ");
+  if (!yes) throw new Error("consent not authorized by the titular; nothing was created");
+
+  // The consumer's "browser" is this terminal: the submit is the same call the hosted page makes,
+  // plus the attestation the partner surface requires. Sandbox rails accept a placeholder token.
+  const submitted = (await api.request("post", "/v1/consents/{token}/submit" as never, {
+    path: { token: init.token },
+    body: {
+      consumer_id: consumerId,
+      rail: "pix-consent",
+      provider_token: `sandbox-pix-consent-${consumerId}`,
+      display_label: "bills-agent (sandbox)",
+      attestation: { method: "in_person", asserted_at: Math.floor(now().getTime() / 1000), reference: "terminal" },
+    },
+  } as never)) as { mandate_id: string; mandate: Record<string, unknown>; signature: string };
+
+  const signed = submitted.mandate;
+  const mandate = MandateSchema.parse({
+    id: submitted.mandate_id,
+    version: 1,
+    consumer_id: String(signed["consumer_id"]),
+    agent_id: String(signed["agent_id"]),
+    purpose: String(signed["purpose"]),
+    currency: String(signed["currency"]),
+    cap_minor: Number(signed["cap_minor"]),
+    per_tx_cap_minor: Number(signed["per_tx_cap_minor"]),
+    ...(signed["periodic_cap"] ? { periodic_cap: signed["periodic_cap"] } : {}),
+    merchant_pin_kind: String(signed["merchant_pin_kind"]),
+    merchant_allowlist: signed["merchant_allowlist"],
+    beneficiaries: example.beneficiaries.filter((b) => (signed["merchant_allowlist"] as string[]).includes(b.payee)),
+    status: "active",
+    expires_at: new Date(Number(signed["expires_at"]) * 1000).toISOString(),
+    signature: submitted.signature,
+    canonical: signed,
+    source: "consent",
+  });
+
+  mkdirSync(dirname(options.mandatePath), { recursive: true });
+  writeFileSync(options.mandatePath, JSON.stringify(mandate, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(options.mandatePath, 0o600);
+  say(`Mandato assinado: ${mandate.id} (consumidor ${mandate.consumer_id}).`);
+
+  await fundSandbox(api, mandate, say);
+  return mandate;
+}
+
+/** Best effort: the sandbox account is credited with one window's cap. A `pix-consent` source has no Celcoin account to credit, and the sandbox spend does not need one. */
+export async function fundSandbox(api: ApiClient, mandate: Mandate, say: (line: string) => void): Promise<void> {
+  try {
+    const funded = await api.post("/v1/test/fund", { body: { consumer_id: mandate.consumer_id, amount_minor: windowCap(mandate) } });
+    say(`Sandbox creditado: ${funded.amount_minor} centavos em ${funded.account} (deposit ${funded.deposit_id}).`);
+  } catch (err) {
+    const f = describeApiError(err);
+    say(`Sandbox nao creditado (${f.code}); o gasto de teste sob pix-consent nao depende disso.`);
+  }
+}

package/templates/bills-agent/agents/bills-agent/src/modules/pix-out.ts

@@ -0,0 +1,73 @@
+/**
+ * Module `pix-out`: the tool handlers the model can reach. `codespar_pay`
+ * hands the proposal to the engine and gets an execution in `drafted` (then
+ * whatever the core decided); it cannot pay. `codespar_ledger` and
+ * `list_bills` are reads.
+ */
+import type { ToolHandler } from "@codespar/agent-core";
+import { formatBRL } from "../bills.js";
+import { BILLS, MONTH } from "../bills.js";
+
+interface PayInput {
+  action?: unknown;
+  items?: unknown;
+  total_minor?: unknown;
+}
+
+export const listBills: ToolHandler = async (_input, ctx) => {
+  const settled = ctx.engine.list({ state: "settled" });
+  const paidAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
+  return {
+    month: MONTH,
+    bills: BILLS.map((b) => ({ ...b, amount: formatBRL(b.amount_minor), paid_this_window: paidAliases.has(b.alias) })),
+    payees: ctx.engine.mandate.beneficiaries.map((b) => ({ alias: b.alias, name: b.name })),
+  };
+};
+
+export const codesparPay: ToolHandler = async (raw, ctx) => {
+  const input = raw as PayInput;
+  if (input.action !== "pix") throw new Error(`codespar_pay: unsupported action ${String(input.action)}; this agent only does pix`);
+  if (!Array.isArray(input.items) || input.items.length === 0) throw new Error("codespar_pay: items must be a non-empty array");
+  const items = input.items.map((item, i) => {
+    const it = item as { payee?: unknown; amount_minor?: unknown; description?: unknown };
+    if (typeof it.payee !== "string" || !it.payee.trim()) throw new Error(`codespar_pay: items[${i}].payee must be a payee alias`);
+    if (typeof it.amount_minor !== "number" || !Number.isInteger(it.amount_minor) || it.amount_minor <= 0) throw new Error(`codespar_pay: items[${i}].amount_minor must be a positive integer`);
+    return { payee: it.payee, amount: it.amount_minor, ...(typeof it.description === "string" ? { description: it.description } : {}) };
+  });
+  const claimed = typeof input.total_minor === "number" ? { claimed_total: input.total_minor } : {};
+
+  const draft = await ctx.engine.draft({ items, ...claimed });
+  if (!draft.ok) {
+    return { status: "refused", reason: draft.reason, message: draft.message, paid: false };
+  }
+  const execution = await ctx.onExecution(draft.execution);
+  return {
+    status: execution.state,
+    execution_id: execution.id,
+    total_minor: execution.total,
+    total: formatBRL(execution.total),
+    items: execution.items.map((i) => ({ payee: i.beneficiary, amount: formatBRL(i.amount) })),
+    ...(execution.reason ? { reason: execution.reason, detail: execution.detail } : {}),
+    ...(execution.escalation ? { escalated_by: execution.escalation.trigger } : {}),
+    receipt_ids: execution.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+    paid: execution.state === "settled",
+  };
+};
+
+export const codesparLedger: ToolHandler = async (raw, ctx) => {
+  const input = raw as { action?: unknown; receipt_id?: unknown };
+  if (input.action === "executions") {
+    return {
+      executions: ctx.engine.list().map((e) => ({ id: e.id, state: e.state, total: formatBRL(e.total), reason: e.reason ?? null, receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id) })),
+    };
+  }
+  if (input.action === "receipt") {
+    if (typeof input.receipt_id !== "string") throw new Error("codespar_ledger: receipt_id is required for action=receipt");
+    const owner = ctx.engine.list().find((e) => e.outcomes.some((o) => o.receipt_id === input.receipt_id));
+    if (!owner) return { found: false, message: "no receipt with that id in this mandate's executions" };
+    const outcome = owner.outcomes.find((o) => o.receipt_id === input.receipt_id)!;
+    const item = owner.items[outcome.index];
+    return { found: true, receipt_id: outcome.receipt_id, state: owner.state, payee: item?.beneficiary, amount: item ? formatBRL(item.amount) : null, mandate_id: owner.mandate.id };
+  }
+  throw new Error(`codespar_ledger: unsupported action ${String(input.action)}`);
+};