@codespar/cli 0.14.0 → 0.16.0

package/templates/supplier-payments-agent/agents/supplier-payments-agent/test/check.test.ts

@@ -0,0 +1,109 @@
+import { cpSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { checkAgent } from "@codespar/agent-core";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+
+function copyAgent(): string {
+  const dir = mkdtempSync(join(tmpdir(), "supplier-check-"));
+  for (const f of ["agent.yaml", "SYSTEM_PROMPT.md", "tools.json", "guardrails.json", "mandate.example.json", "AGENTS.md", "CLAUDE.md", "README.md", "runbook.md", ".env.example"]) cpSync(join(AGENT_DIR, f), join(dir, f));
+  cpSync(join(AGENT_DIR, "scenarios"), join(dir, "scenarios"), { recursive: true });
+  cpSync(join(AGENT_DIR, "evals"), join(dir, "evals"), { recursive: true });
+  return dir;
+}
+
+const codes = (dir: string) => checkAgent(dir).findings.filter((f) => f.level === "error").map((f) => f.code);
+
+describe("npm run check: the manifest is the index", () => {
+  it("passes on the shipped agent", () => {
+    expect(codes(AGENT_DIR)).toEqual([]);
+  });
+
+  it("fails when guardrails contradict the manifest", () => {
+    const dir = copyAgent();
+    const g = JSON.parse(readFileSync(join(dir, "guardrails.json"), "utf8")) as { approval: string; escalate_above: { amount: number } };
+    g.approval = "mandate";
+    writeFileSync(join(dir, "guardrails.json"), JSON.stringify(g));
+    expect(codes(dir)).toContain("guardrails_contradict_manifest");
+    g.approval = "human";
+    g.escalate_above.amount = 999;
+    writeFileSync(join(dir, "guardrails.json"), JSON.stringify(g));
+    expect(codes(dir)).toContain("guardrails_contradict_manifest");
+  });
+
+  it("fails when the prompt names a tool tools.json does not have, or when tools.json drops the payment tool", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, "SYSTEM_PROMPT.md"), readFileSync(join(dir, "SYSTEM_PROMPT.md"), "utf8") + "\nYou may also call codespar_wallet.\n");
+    expect(codes(dir)).toContain("prompt_contradicts_tools");
+    const t = JSON.parse(readFileSync(join(dir, "tools.json"), "utf8")) as { meta_tools: Array<{ effect: string }> };
+    t.meta_tools = t.meta_tools.filter((x) => x.effect !== "payment");
+    writeFileSync(join(dir, "tools.json"), JSON.stringify(t));
+    expect(codes(dir)).toContain("tools_contradict_manifest");
+  });
+
+  it("fails when AGENTS.md and CLAUDE.md diverge", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, "CLAUDE.md"), readFileSync(join(dir, "CLAUDE.md"), "utf8") + "\nextra line\n");
+    expect(codes(dir)).toContain("agents_md_diverges");
+  });
+
+  it("fails when mcp, cli or schema are missing", () => {
+    for (const field of ["mcp", "cli", "schema"]) {
+      const dir = copyAgent();
+      writeFileSync(join(dir, "agent.yaml"), readFileSync(join(dir, "agent.yaml"), "utf8").split("\n").filter((l) => !l.startsWith(`${field}:`)).join("\n"));
+      expect(codes(dir)).toContain("manifest_field_missing");
+    }
+  });
+
+  it("fails when a doc claims third-party verifiability and never says which signature it means", () => {
+    const dir = copyAgent();
+    // The claim with no mechanism named: true of the Ed25519 seal on a receipt, false of the approval artifact and of every receipt sealed before it.
+    writeFileSync(join(dir, "README.md"), "# supplier-payments-agent\n\nO recibo é verificável por terceiro.\n");
+    expect(codes(dir)).toContain("doc_overclaims");
+    // The same claim, with the mechanism named: allowed, and what the shipped README does.
+    writeFileSync(join(dir, "README.md"), "# supplier-payments-agent\n\nO recibo é verificável por terceiro: a assinatura Ed25519 confere contra as chaves públicas.\n");
+    expect(codes(dir)).not.toContain("doc_overclaims");
+  });
+
+
+  it("refuses the claim, mechanism named and all, when the agent itself says receipt-verification is blocked", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, "README.md"), readFileSync(join(dir, "README.md"), "utf8") + "\nThe receipt is third-party verifiable: the Ed25519 signature checks against the published keys.\n");
+    expect(codes(dir)).not.toContain("doc_overclaims");
+    writeFileSync(join(dir, "agent.yaml"), readFileSync(join(dir, "agent.yaml"), "utf8").replace("receipt-verification: sandbox", "receipt-verification: blocked"));
+    expect(codes(dir)).toContain("doc_overclaims");
+  });
+
+  it("fails when .env.example grows a third key", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, ".env.example"), readFileSync(join(dir, ".env.example"), "utf8") + "APPROVAL_KEY=x\n");
+    expect(codes(dir)).toContain("env_example_extra");
+  });
+
+  it("fails when agent.yaml declares an event the API does not publish", () => {
+    const dir = copyAgent();
+    const manifest = join(dir, "agent.yaml");
+    writeFileSync(manifest, readFileSync(manifest, "utf8").replace("commerce.payment.succeeded", "commerce.payment.settled"));
+    const report = checkAgent(dir);
+    expect(report.findings.filter((f) => f.code === "events_unknown").map((f) => f.message)).toEqual([expect.stringContaining("commerce.payment.settled")]);
+  });
+
+  it("fails when eval.yaml does not extend the manifest or redeclares a field", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, "evals", "eval.yaml"), "extends: ../agent.yaml\nname: other\n");
+    expect(codes(dir)).toContain("eval_redeclares_manifest");
+    writeFileSync(join(dir, "evals", "eval.yaml"), "cases: []\n");
+    expect(codes(dir)).toContain("eval_extends");
+  });
+
+  it("fails when the batch capability is declared without the payment tool that runs it", () => {
+    const dir = copyAgent();
+    const t = JSON.parse(readFileSync(join(dir, "tools.json"), "utf8")) as { meta_tools: Array<{ effect: string }> };
+    t.meta_tools = t.meta_tools.filter((x) => x.effect !== "payment");
+    writeFileSync(join(dir, "tools.json"), JSON.stringify(t));
+    // `batch-payout` rides on `pix-out`, so dropping the payment tool is what the gate catches.
+    expect(codes(dir)).toContain("tools_contradict_manifest");
+  });
+});

package/templates/supplier-payments-agent/agents/supplier-payments-agent/test/scenarios.test.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { checkScenario, listScenarios, loadScenario, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "supplier-runs-"));
+
+describe("section 12: scenario packs, on the replay provider", () => {
+  const required = ["happy-path", "partial-batch-failure", "cap-exceeded", "beneficiary-not-allowed", "prompt-injection", "escalated-above-threshold", "mandate-revoked"];
+
+  it("ships every scenario the spec asks for, including this agent's own", () => {
+    for (const name of required) expect(listScenarios(agent)).toContain(name);
+  });
+
+  for (const name of required) {
+    const scenario = loadScenario(agent, name);
+    for (const mode of scenario.modes) {
+      it(`${name} [${mode}] ends in the states the pack declares`, async () => {
+        const run = await runScenario(agent, scenario, { mode, runsDir });
+        const check = checkScenario(scenario, run);
+        expect(check.failures).toEqual([]);
+        expect(check.ok).toBe(true);
+        // Every event of the bundle carries an actor.
+        const events = readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { actor?: unknown });
+        expect(events.length).toBeGreaterThan(0);
+        for (const e of events) expect(e.actor).toBeDefined();
+        // Every receipt carries an actor and no raw payee.
+        for (const file of readdirSync(join(run.bundle_dir, "receipts"))) {
+          const receipt = JSON.parse(readFileSync(join(run.bundle_dir, "receipts", file), "utf8")) as { actor?: unknown; payment: { payee: string | null } };
+          expect(receipt.actor).toBeDefined();
+          expect(receipt.payment.payee ?? "").toContain("***");
+        }
+      });
+    }
+  }
+
+  it("happy-path: the batch is three executions and three artifacts, in both modes", async () => {
+    const scenario = loadScenario(agent, "happy-path");
+    for (const mode of ["human", "mandate"] as const) {
+      const run = await runScenario(agent, scenario, { mode, runsDir });
+      expect(run.executions).toHaveLength(3);
+      const artifacts = JSON.parse(readFileSync(join(run.bundle_dir, "approval.json"), "utf8")) as Array<{ execution_id: string; items: unknown[]; items_hash: string; approver: { type: string } }>;
+      expect(artifacts).toHaveLength(3);
+      // The approved list is attested line by line: one item per artifact, one hash each, and a person decided every one. The set they belong to is bound too (batch.test.ts).
+      for (const a of artifacts) {
+        expect(a.items).toHaveLength(1);
+        expect(a.approver.type).toBe("person");
+      }
+      expect(new Set(artifacts.map((a) => a.items_hash)).size).toBe(3);
+      expect(artifacts.map((a) => a.execution_id).sort()).toEqual(run.executions.map((e) => e.id).sort());
+    }
+  });
+
+  it("partial-batch-failure: the refused line is one execution, and the line after it still settled", async () => {
+    const scenario = loadScenario(agent, "partial-batch-failure");
+    const run = await runScenario(agent, scenario, { mode: "human", runsDir });
+    expect(run.executions.map((e) => e.state)).toEqual(["settled", "failed", "settled"]);
+    expect(run.settled_total).toBe(174000);
+    // Each line carries its own terminal state, so the refusal is `failed` on
+    // one row while the others are `settled` on theirs.
+    expect(run.executions[2]?.trail).toContain("executing");
+    expect(run.receipts).toBe(2);
+  });
+
+  it("nothing reaches executing without an approval artifact carrying its items_hash", async () => {
+    for (const name of required) {
+      const scenario = loadScenario(agent, name);
+      for (const mode of scenario.modes) {
+        const run = await runScenario(agent, scenario, { mode, runsDir });
+        const approvalPath = join(run.bundle_dir, "approval.json");
+        const artifacts = existsSync(approvalPath) ? (JSON.parse(readFileSync(approvalPath, "utf8")) as Array<{ execution_id: string; items_hash: string }>) : [];
+        for (const e of run.executions) {
+          if (!e.trail.includes("executing")) continue;
+          expect(artifacts.some((a) => a.execution_id === e.id)).toBe(true);
+        }
+      }
+    }
+  });
+});

package/templates/supplier-payments-agent/agents/supplier-payments-agent/tools.json

@@ -0,0 +1,53 @@
+{
+  "meta_tools": [
+    {
+      "name": "codespar_pay",
+      "effect": "payment",
+      "description": "Propose Pix payouts. This does NOT pay: it creates executions in `drafted` that the core checks against the mandate and, depending on the approval mode, asks a person or runs. Two shapes. With `batch_ref` it runs a whole batch from list_payables (suppliers, commissions or payroll) as one execution PER LINE, so a refusal on one payee does not stop the others and re-running the same batch pays nobody twice; the lines come from the payables file, so never send items or total_minor with it. With `items` it proposes a single one-off payout to named payees. Amounts are in BRL cents.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["pix"] },
+          "batch_ref": { "type": "string", "description": "A batch_ref from list_payables (e.g. folha-2026-10). Runs every open line of that batch. Cannot be combined with items." },
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "description": "A one-off payout, outside any batch. Cannot be combined with batch_ref.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "payee": { "type": "string", "description": "A payee alias from list_payables. Never a raw Pix key somebody typed in the chat." },
+                "amount_minor": { "type": "integer", "minimum": 1, "description": "BRL cents." },
+                "description": { "type": "string" }
+              },
+              "required": ["payee", "amount_minor"]
+            }
+          },
+          "total_minor": { "type": "integer", "description": "Optional, and only with items. What you believe the total is. The core recomputes it and yours is only recorded." }
+        },
+        "required": ["action"]
+      }
+    },
+    {
+      "name": "codespar_ledger",
+      "effect": "read",
+      "description": "Read the receipt of a settled payout by receipt id, or list the executions of this mandate with their states.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["receipt", "executions"] },
+          "receipt_id": { "type": "string" }
+        },
+        "required": ["action"]
+      }
+    }
+  ],
+  "local_tools": [
+    {
+      "name": "list_payables",
+      "effect": "read",
+      "description": "The month's payables, grouped into the batches the company runs: suppliers, commissions, payroll. Each line carries its payee alias, name, amount in BRL cents, reference, and whether a previous run of that batch already covers it (`open`, `already_settled`, `in_progress`). Read-only.",
+      "input_schema": { "type": "object", "properties": {} }
+    }
+  ]
+}

package/templates/supplier-payments-agent/agents/supplier-payments-agent/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/templates/supplier-payments-agent/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice.",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "packages/agent-core",
+    "packages/agent-runtime",
+    "agents/supplier-payments-agent"
+  ],
+  "scripts": {
+    "start": "npm start --workspace=agents/supplier-payments-agent --",
+    "check": "npm run check --workspaces --if-present --",
+    "test": "vitest run --pool=forks --maxWorkers=1",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/tsconfig.json && tsc --noEmit -p agents/supplier-payments-agent/tsconfig.json",
+    "approve": "npm run approve --workspace=agents/supplier-payments-agent --",
+    "deny": "npm run deny --workspace=agents/supplier-payments-agent --",
+    "eval": "npm run eval --workspace=agents/supplier-payments-agent --",
+    "inspect": "npm run inspect --workspace=agents/supplier-payments-agent --",
+    "reconcile": "npm run reconcile --workspace=agents/supplier-payments-agent --",
+    "rerun": "npm run rerun --workspace=agents/supplier-payments-agent --",
+    "resume": "npm run resume --workspace=agents/supplier-payments-agent --",
+    "verify": "npm run verify --workspace=agents/supplier-payments-agent --"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}

package/templates/supplier-payments-agent/packages/agent-core/README.md

@@ -0,0 +1,21 @@
+# @codespar/agent-core
+
+The primitives every CodeSpar starter-kit agent inherits (spec v5.1.1, section 4): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract and the two providers.
+
+This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|check|eval`, the setup that wires this package to an agent directory, and the scenario and adversarial runners — is [`@codespar/agent-runtime`](../agent-runtime), which depends on this one and is what an agent's `package.json` scripts call (#13). Nothing here knows an agent's name.
+
+## The state machine, and what the types do and do not prove
+
+`transition(execution, to, input)` accepts only a `to` that the table in `state-machine.ts` lists for `execution.state`. On a **narrowed** value (`Execution<"drafted">`, `Execution<"executing">`, ...) a transition outside the table is a compile error, and `test/transitions.type-test.ts` keeps that true with `@ts-expect-error` lines that `tsc` refuses to leave unused. An **un-narrowed** `Execution` (the union, which is what a row read back from SQLite is) compiles for any target; the engine narrows with casts at its call sites. So the guard that always holds is the runtime one: `transition()` throws `IllegalTransitionError` on any pair the table does not list, whatever the static type said. The type test proves the table is closed; the runtime check enforces it.
+
+## The one policy, three gates
+
+`ExecutionEngine.policy()` runs at draft, at a human's approval and again immediately before `executing`, inside the transaction that writes the outbox row. Mandate status, allowlist, per-transaction cap, the window cap (counting settled, in flight AND awaiting executions as reservations), `escalate_above` and the artifact's `items_hash` are all re-checked at the last gate. A person's approval satisfies `escalate_above` and nothing else.
+
+## Reconcile never re-dispatches
+
+An execution left in `executing` is looked up on the rail, attempt by attempt. A recorded settled or failed outcome closes it; `in_flight`, `uncertain` or unknown leaves it in `executing` with `reason: rail_uncertain` for a human. The single exception is an outbox row still `pending` (the state changed, no call was ever made): those attempts go out once, under the same ids.
+
+## Stubs
+
+`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, and a read that does not answer is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.

package/templates/supplier-payments-agent/packages/agent-core/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@codespar/agent-core",
+  "version": "0.1.0",
+  "description": "The primitives every CodeSpar starter-kit agent inherits: the execution state machine, the approval artifact, the agent.yaml manifest, escalate_above, actor, local state and providers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./providers/anthropic": "./src/providers/anthropic.ts",
+    "./providers/replay": "./src/providers/replay.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --pool=forks --maxWorkers=1 --root ../.. packages/agent-core"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.128.0",
+    "@codespar/sdk": "0.16.6",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  }
+}

package/templates/supplier-payments-agent/packages/agent-core/src/agent.ts

@@ -0,0 +1,125 @@
+/**
+ * The tool-use loop. The provider says what the model wants; this file
+ * dispatches only the tools `tools.json` names, records every step in the
+ * transcript, and hands payment tools to the engine, which is the only
+ * thing that can move an execution past `drafted`.
+ */
+import type { ProofBundle } from "./bundle.js";
+import type { ExecutionEngine } from "./engine.js";
+import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
+import { isReply } from "./providers/types.js";
+import type { Execution } from "./state-machine.js";
+import type { ToolsFile } from "./tools.js";
+import { allowedToolNames, toolSpecs } from "./tools.js";
+
+export interface ToolContext {
+  engine: ExecutionEngine;
+  /** Fires when a payment tool created an execution; the channel decides what to do with it (ask, or run). */
+  onExecution: (execution: Execution) => Promise<Execution>;
+}
+
+export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+
+export interface AgentLoopOptions {
+  runtime: AgentRuntime;
+  tools: ToolsFile;
+  handlers: Record<string, ToolHandler>;
+  system: string;
+  bundle: ProofBundle;
+  engine: ExecutionEngine;
+  onExecution: ToolContext["onExecution"];
+  /** A hard stop on tool round-trips per turn, so a looping model cannot run forever. */
+  maxSteps?: number;
+  clock?: () => Date;
+}
+
+export interface TurnResult {
+  reply: string;
+  tool_calls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+export class AgentLoop {
+  private readonly messages: ConversationMessage[] = [];
+  private readonly allowed: Set<string>;
+  private readonly specs: ToolSpec[];
+  private readonly clock: () => Date;
+
+  constructor(private readonly options: AgentLoopOptions) {
+    this.allowed = allowedToolNames(options.tools);
+    this.specs = toolSpecs(options.tools);
+    this.clock = options.clock ?? (() => new Date());
+  }
+
+  get history(): readonly ConversationMessage[] {
+    return this.messages;
+  }
+
+  async turn(userText: string): Promise<TurnResult> {
+    const { runtime, bundle } = this.options;
+    const maxSteps = this.options.maxSteps ?? 8;
+    const calls: TurnResult["tool_calls"] = [];
+    const executions: Execution[] = [];
+
+    this.messages.push({ role: "user", content: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+
+    for (let step = 0; step < maxSteps; step += 1) {
+      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      if (isReply(out)) {
+        this.messages.push({ role: "assistant", content: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant_step", reply: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant", text: out.text });
+        return { reply: out.text, tool_calls: calls, executions };
+      }
+
+      this.messages.push({ role: "assistant", content: "", tool_calls: out });
+      bundle.transcript({ at: this.now(), kind: "assistant_step", tool_calls: out });
+
+      for (const call of out) {
+        const result = await this.dispatch(call, executions);
+        calls.push({ name: call.name, refused: result.refused });
+        this.messages.push({ role: "tool", tool_call_id: call.id, name: call.name, content: JSON.stringify(result.content), ...(result.refused ? { is_error: true } : {}) });
+        bundle.transcript({ at: this.now(), kind: "tool_result", tool_call_id: call.id, name: call.name, refused: result.refused, content: result.content });
+      }
+    }
+
+    const text = "I stopped: too many tool steps in one turn. Nothing was paid beyond what the trail shows.";
+    this.messages.push({ role: "assistant", content: text });
+    bundle.transcript({ at: this.now(), kind: "assistant", text, truncated: true });
+    return { reply: text, tool_calls: calls, executions };
+  }
+
+  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+    const { bundle, handlers, engine, onExecution } = this.options;
+    bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
+
+    if (!this.allowed.has(call.name)) {
+      // Section 15, closed tools: a tool outside tools.json is refused, and the refusal is in the trail.
+      bundle.event({ at: this.now(), type: "tool.refused", tool: call.name, reason: "tool_not_allowed", actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_not_allowed", message: `${call.name} is not in this agent's tools.json` } };
+    }
+    const handler = handlers[call.name];
+    if (!handler) return { refused: true, content: { error: "tool_not_implemented", message: `${call.name} has no handler` } };
+
+    try {
+      const content = await handler(call.input, {
+        engine,
+        onExecution: async (execution) => {
+          const settledOrNot = await onExecution(execution);
+          executions.push(settledOrNot);
+          return settledOrNot;
+        },
+      });
+      return { refused: false, content };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      bundle.event({ at: this.now(), type: "tool.error", tool: call.name, message, actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_failed", message } };
+    }
+  }
+
+  private now(): string {
+    return this.clock().toISOString();
+  }
+}

package/templates/supplier-payments-agent/packages/agent-core/src/api/charge-rail.ts

@@ -0,0 +1,175 @@
+/**
+ * The CodeSpar receivable rail: the merchant COLLECTS. `pay()` issues a
+ * cobranca com vencimento through `POST /v1/charges` (the REST form of the
+ * `codespar_charge` meta-tool, action=create): `method: "boleto"` plus a
+ * `due_date` is what makes it ONE receivable the payer settles either by
+ * boleto or by Pix; `idempotency_key` is REQUIRED on that create and is our
+ * attempt id, so a retry returns the same charge instead of a second
+ * receivable the same debtor could pay twice. An immediate Pix
+ * (`method: "pix"`) is deliberately not used: the API does not replay its
+ * create on a key and does not read it back, so it cannot close a loop.
+ *
+ * `lookup()` is `GET /v1/charges/{id}`, which accepts our idempotency key as
+ * the id; the kit polls it to close the cycle when no webhook can reach a
+ * terminal. Branching is on `local_status` and the normalized `status`, never
+ * on prose. Amounts cross the wire in MAJOR units (`amount: 1080.5`), which
+ * is what `coerceMetaChargeArgs` reads; the answer's `amount_minor` is
+ * compared with what was asked and a mismatch is a failure, not a charge.
+ *
+ * There is no receipt object for a receivable; the paid charge as the API
+ * reports it is what the bundle keeps, marked `kind: "charge"` and unsealed.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { Actor, ChargeInstrument } from "../types.js";
+import { describeApiError, isUncertain } from "./client.js";
+
+/** The `/v1/charges` answer, as the SDK types it. */
+export interface ChargeView {
+  id: string | null;
+  status: string;
+  local_status: string;
+  status_conflict: boolean;
+  method: string;
+  currency: string;
+  amount: number;
+  amount_minor: number;
+  due_date: string | null;
+  payable: boolean;
+  boleto_bar_code: string | null;
+  boleto_bank_line: string | null;
+  pix_copy_paste: string | null;
+  credit_correlation_armed: boolean;
+  payment_in_flight: boolean;
+  settlement: "confirmed" | "pending" | "unconfirmable" | null;
+  issuance_unconfirmed: boolean;
+}
+
+export function instrumentOf(view: ChargeView): ChargeInstrument {
+  return {
+    payable: view.payable,
+    status: view.status,
+    pix_copy_paste: view.pix_copy_paste,
+    boleto_bank_line: view.boleto_bank_line,
+    boleto_bar_code: view.boleto_bar_code,
+    due_date: view.due_date,
+  };
+}
+
+/** What a charge view means for the attempt. The row's own status wins over the issuer's normalized one where they name a terminal state. */
+export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight" } {
+  if (view.issuance_unconfirmed || !view.id) return { status: "in_flight" };
+  const id = view.id;
+  if (view.local_status === "settled" || view.status === "CONFIRMED" || view.settlement === "confirmed") {
+    return { status: "settled", transaction_id: id, receipt_id: id, money_moved: false, sandbox: true, raw: view };
+  }
+  if (view.local_status === "expired" || view.status === "EXPIRED") {
+    return { status: "failed", code: "charge_expired", message: `charge ${id} reached its due date unpaid`, raw: view };
+  }
+  if (view.status === "CANCELLED" || view.local_status === "cancelled") {
+    return { status: "failed", code: "charge_cancelled", message: `charge ${id} was withdrawn`, raw: view };
+  }
+  return { status: "accepted", transaction_id: id, instrument: instrumentOf(view), sandbox: true, raw: view };
+}
+
+export class CodeSparChargeRail implements PaymentRail {
+  readonly name = "codespar-charge" as const;
+
+  constructor(private readonly api: ApiClient) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    if (!payment.due_date) return { status: "failed", code: "due_date_required", message: "a receivable needs a due_date; the immediate Pix charge cannot be read back or replayed" };
+    if (!payment.consumer_id) return { status: "failed", code: "consumer_id_required", message: "a receivable settles into the principal's account; the policy names no consumer_id" };
+    let view: ChargeView;
+    try {
+      view = (await this.api.post("/v1/charges", {
+        body: {
+          consumer_id: payment.consumer_id,
+          amount: payment.amount_minor / 100,
+          currency: payment.currency,
+          method: "boleto",
+          description: payment.description ?? payment.purpose,
+          buyer: { name: payment.beneficiary ?? payment.payee, document: payment.payee },
+          due_date: payment.due_date,
+          idempotency_key: payment.attempt_id,
+        },
+      })) as ChargeView;
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (isUncertain(failure) || failure.code === "issuance_unconfirmed") return { status: "uncertain", code: failure.code, message: failure.message };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: "issuance_unconfirmed", message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
+    if (view.amount_minor !== payment.amount_minor) {
+      // The API understood another amount than the one approved. The receivable exists; withdraw it rather than leave a debt nobody approved.
+      const withdrawn = await this.withdraw(view.id);
+      return { status: "failed", code: "amount_mismatch", message: `the API issued ${view.amount_minor} for a request of ${payment.amount_minor} (charge ${view.id}); ${withdrawn ? "withdrawn" : "withdrawal refused, an operator must cancel it"}` };
+    }
+    const outcome = outcomeOf(view);
+    // `in_flight` is excluded above (`issuance_unconfirmed` / no id); the create answers a state, never "still running".
+    return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
+  }
+
+  /**
+   * By the charge id when the create handed one back; by our idempotency key only when it did not (the create's answer was lost).
+   * The route's doc says the read accepts the caller's key as the id; on staging (2026-09-23) it answered `charge_not_found` for
+   * the key and the charge for the id, so the id comes first and the key is the fallback, not the other way round.
+   */
+  async lookup(attemptId: string, _payment: RailPayment, transactionId?: string): Promise<RailLookup> {
+    const byId = transactionId ? await this.read(transactionId) : { kind: "missing" as const };
+    if (byId.kind === "view") return outcomeOf(byId.view);
+    if (byId.kind === "in_flight") return { status: "in_flight" };
+    if (byId.kind === "uncertain") return byId.outcome;
+    const byKey = await this.read(attemptId);
+    if (byKey.kind === "view") return outcomeOf(byKey.view);
+    if (byKey.kind === "in_flight") return { status: "in_flight" };
+    if (byKey.kind === "uncertain") return byKey.outcome;
+    return undefined;
+  }
+
+  private async read(chargeRef: string): Promise<{ kind: "view"; view: ChargeView } | { kind: "missing" } | { kind: "in_flight" } | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> }> {
+    try {
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } })) as ChargeView;
+      return { kind: "view", view };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return { kind: "missing" };
+      if (failure.status === 409) return { kind: "in_flight" };
+      return { kind: "uncertain", outcome: { status: "uncertain", code: failure.code, message: failure.message } };
+    }
+  }
+
+  async receipt(chargeId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    try {
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } })) as ChargeView;
+      const raw = view as ChargeView & { settled_at?: string };
+      return {
+        receipt_id: chargeId,
+        kind: "charge",
+        state: view.local_status === "settled" ? "paid" : view.local_status,
+        mandate: { id: "n/a" },
+        // The read names no buyer, so the payee is not on this record; the execution's item names the debtor.
+        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: raw.settled_at ?? new Date().toISOString() },
+        chain: null,
+        receipt_sig: null,
+        receipt_sig_ed25519: null,
+        receipt_sig_kid: null,
+        actor,
+        raw: view,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  private async withdraw(chargeId: string): Promise<boolean> {
+    try {
+      await this.api.post("/v1/charges/{chargeId}/cancel", { path: { chargeId } });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}