@codespar/cli 0.13.0 → 0.14.1

package/templates/collections-agent/agents/collections-agent/test/cli.test.ts

@@ -0,0 +1,172 @@
+/**
+ * The contracts that need a real process: `--json` on stdout and nothing
+ * else, the live-key refusal, the restart after the issuance followed by
+ * `resume` and `poll`, `rerun`, `approve`/`deny`, and `check`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const HAPPY = "oi, recebi a mensagem sobre o acordo do pedido 1042";
+
+function run(script: string, args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, ["--disable-warning=ExperimentalWarning", "--import", "tsx", script, ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+function scratch(label: string): Record<string, string> {
+  const stateDir = mkdtempSync(join(tmpdir(), `collections-${label}-`));
+  return { COLLECTIONS_STATE_DIR: stateDir, COLLECTIONS_RUNS_DIR: join(stateDir, "runs") };
+}
+
+describe("npm start -- --input ... --json", () => {
+  it("prints valid JSON on stdout and nothing else; the QR and the people go to stderr", () => {
+    const env = scratch("json");
+    // The recorded happy-path's first turn is a proposal, no execution: the second turn issues.
+    const out = run("src/main.ts", ["--input", HAPPY, "--json"], env);
+    expect(out.code).toBe(0);
+    const lines = out.stdout.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    const payload = JSON.parse(lines[0]!) as { run_id: string; mode: string; actor: { type: string }; executions: unknown[]; tool_calls: Array<{ name: string }> };
+    expect(payload.mode).toBe("human");
+    expect(payload.actor.type).toBe("agent");
+    expect(payload.executions).toEqual([]);
+    expect(payload.tool_calls.map((c) => c.name)).toEqual(["list_agreements"]);
+    expect(out.stderr).toContain("replay");
+  });
+
+  it("an accepted proposal, approved with the payer simulated, settles in one process and the QR never reaches stdout", () => {
+    const env = scratch("settle");
+    const out = run("src/main.ts", ["--input", "fechado, pago à vista", "--transcript", "test/fixtures/accept-1042.transcript.jsonl", "--approve", "--simulate-payer", "--json"], env);
+    expect(out.code).toBe(0);
+    const lines = out.stdout.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    const payload = JSON.parse(lines[0]!) as { executions: Array<{ state: string; charges: Array<{ charge_id: string; status: string }>; receipt_ids: string[] }>; receipts: string[] };
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(payload.executions[0]?.charges).toHaveLength(1);
+    expect(payload.receipts).toHaveLength(1);
+    expect(out.stderr).toContain("copia e cola");
+  });
+
+  it("refuses a key outside csk_test_ before anything else", () => {
+    const env = scratch("live");
+    const out = run("src/main.ts", ["--input", HAPPY, "--json"], { ...env, CODESPAR_API_KEY: ["csk", "live", "0000000000"].join("_") });
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("csk_test_");
+  });
+});
+
+describe("section 10: restart after the issuance, then resume and poll", () => {
+  it("one receivable, one settlement, never two", () => {
+    const env = scratch("restart");
+
+    const killed = run("src/main.ts", ["--input", "fechado, pago à vista", "--transcript", "test/fixtures/accept-1042.transcript.jsonl", "--approve", "--json"], { ...env, COLLECTIONS_KILL_AFTER_DISPATCH: "1" });
+    expect(killed.code).toBe(137);
+    expect(killed.stdout).toBe("");
+
+    const db = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+    expect(db.prepare("SELECT state FROM executions").all()).toEqual([{ state: "executing" }]);
+    expect((db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(1);
+    db.close();
+
+    // resume: the outbox is `sent`, so nothing is re-issued; the receivable is looked at and found registered, waiting for its payer.
+    const resumed = run("src/commands/resume.ts", ["--json"], env);
+    expect(resumed.code).toBe(0);
+    const r = JSON.parse(resumed.stdout.trim()) as { resumed: Array<{ state: string; reason: string | null; charge_ids: string[] }> };
+    expect(r.resumed).toHaveLength(1);
+    expect(r.resumed[0]).toMatchObject({ state: "executing", reason: "awaiting_settlement" });
+    expect(r.resumed[0]?.charge_ids[0]).toMatch(/^chg_stub_/);
+
+    // poll: the fixture payer pays on the next look; the record is fetched; the payer is told once.
+    const polled = run("src/commands/poll.ts", ["--json"], env);
+    expect(polled.code).toBe(0);
+    const p = JSON.parse(polled.stdout.trim()) as { polled: Array<{ state: string; timed_out: boolean }> };
+    expect(p.polled).toEqual([expect.objectContaining({ state: "settled", timed_out: false })]);
+
+    const db2 = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+    expect((db2.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(1);
+    expect((db2.prepare("SELECT COUNT(*) AS n FROM events WHERE type = 'commerce.charge.paid'").get() as { n: number }).n).toBe(1);
+    expect((db2.prepare("SELECT COUNT(*) AS n FROM events WHERE type = 'message.debtor'").get() as { n: number }).n).toBe(1);
+    expect(db2.prepare("SELECT state FROM executions").all()).toEqual([{ state: "settled" }]);
+    db2.close();
+
+    const runsDir = env["COLLECTIONS_RUNS_DIR"]!;
+    const receipts = readdirSync(runsDir).flatMap((d) => (existsSync(join(runsDir, d, "receipts")) ? readdirSync(join(runsDir, d, "receipts")) : []));
+    expect(receipts).toHaveLength(1);
+
+    const again = run("src/commands/poll.ts", ["--json"], env);
+    expect(JSON.parse(again.stdout.trim())).toEqual({ polled: [] });
+  });
+});
+
+describe("npm run rerun <run-id>", () => {
+  it("reproduces a recorded run without network, with the same state sequence, including an expired receivable", () => {
+    const env = scratch("rerun");
+    // No --simulate-payer: the fixture payer lets it expire at the second look; the recorded run is a failed one.
+    const first = run("src/main.ts", ["--input", "pode emitir", "--transcript", "test/fixtures/accept-1103.transcript.jsonl", "--approve", "--json"], { ...env, COLLECTIONS_STUB_PAYER: "expires" });
+    expect(first.code).toBe(0);
+    const payload = JSON.parse(first.stdout.trim()) as { run_id: string; executions: Array<{ state: string; reason: string | null }> };
+    expect(payload.executions[0]).toMatchObject({ state: "failed", reason: "charge_expired" });
+    const rerun = run("src/commands/rerun.ts", [payload.run_id, "--json"], env);
+    expect(rerun.code).toBe(0);
+    const r = JSON.parse(rerun.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[] };
+    expect(r.same_states).toBe(true);
+    expect(r.original).toEqual(["awaiting_approval", "approved", "executing", "failed"]);
+  });
+});
+
+describe("npm run check", () => {
+  it("is green for the shipped agent and prints JSON with --json", () => {
+    const out = run("src/commands/check.ts", ["--json"], {});
+    expect(out.code).toBe(0);
+    const report = JSON.parse(out.stdout.trim()) as { ok: boolean; agent: string; findings: unknown[] };
+    expect(report).toMatchObject({ ok: true, agent: "collections-agent" });
+  });
+});
+
+describe("npm run approve / deny <execution-id>", () => {
+  it("decides an execution left awaiting, produces the artifact, issues, and waits for the payer", () => {
+    const env = scratch("decide");
+    const left = run("src/main.ts", ["--input", "fechado, pago à vista", "--transcript", "test/fixtures/accept-1042.transcript.jsonl", "--json"], env);
+    expect(left.code).toBe(0);
+    const payload = JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string; state: string }> };
+    expect(payload.executions[0]?.state).toBe("awaiting_approval");
+    const id = payload.executions[0]!.id;
+
+    const approved = run("src/commands/approve.ts", [id, "--user", "usr_gerente", "--simulate-payer", "--json"], env);
+    expect(approved.code).toBe(0);
+    const out = JSON.parse(approved.stdout.trim()) as { state: string; approval_id: string | null; charge_ids: string[]; receipt_ids: string[]; bundle_dir: string };
+    expect(out.state).toBe("settled");
+    expect(out.approval_id).toMatch(/^apr_/);
+    expect(out.charge_ids).toHaveLength(1);
+    expect(out.receipt_ids).toHaveLength(1);
+    const artifacts = JSON.parse(readFileSync(join(AGENT_DIR, out.bundle_dir, "approval.json"), "utf8")) as Array<{ approver: { type: string; id: string } }>;
+    expect(artifacts[0]?.approver).toEqual({ type: "person", id: "usr_gerente", channel: "terminal" });
+
+    const again = run("src/commands/approve.ts", [id, "--json"], env);
+    expect(again.code).toBe(1);
+  });
+
+  it("deny leaves a terminal denied execution and issues nothing", () => {
+    const env = scratch("deny");
+    const left = run("src/main.ts", ["--input", "fechado, pago à vista", "--transcript", "test/fixtures/accept-1042.transcript.jsonl", "--json"], env);
+    const id = (JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string }> }).executions[0]!.id;
+    const denied = run("src/commands/deny.ts", [id, "--json"], env);
+    expect(denied.code).toBe(0);
+    expect(JSON.parse(denied.stdout.trim())).toMatchObject({ state: "denied", reason: "denied_by_approver", charge_ids: [] });
+    const db = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+    expect((db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(0);
+    db.close();
+  });
+});

package/templates/collections-agent/agents/collections-agent/test/envelope.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import type { ExecutionItem } from "@codespar/agent-core";
+import { AGREEMENTS } from "../src/agreements.js";
+import { checkEnvelope, floorMinor, type Envelope } from "../src/envelope.js";
+
+const envelope: Envelope = { max_discount_pct: 15, max_instalments: 3, due_date_window_days: 90, min_instalment_minor: 5000, collection_hours: "08:00-20:00" };
+const NOW = new Date("2026-09-23T18:00:00Z"); // 15:00 in Sao Paulo
+const TZ = "America/Sao_Paulo";
+const joana = AGREEMENTS[0]!;
+
+function items(list: Array<{ amount: number; due_date?: string; payee?: string }>): Pick<{ items: ExecutionItem[]; total: number }, "items" | "total"> {
+  const out = list.map((i) => ({ beneficiary: "x", payee: i.payee ?? joana.document, amount: i.amount, currency: "BRL", ...(i.due_date ? { due_date: i.due_date } : {}) }));
+  return { items: out, total: out.reduce((s, i) => s + i.amount, 0) };
+}
+
+describe("the negotiation envelope is deterministic code", () => {
+  it("the floor is the principal minus the maximum discount, rounded up", () => {
+    expect(floorMinor(joana, envelope)).toBe(102000);
+    expect(floorMinor({ ...joana, principal_minor: 100001 }, envelope)).toBe(85001);
+  });
+
+  it("inside: in full with the maximum discount, or three instalments inside the window", () => {
+    expect(checkEnvelope(items([{ amount: 102000, due_date: "2026-09-30" }]), envelope, NOW, TZ)).toBeUndefined();
+    expect(checkEnvelope(items([{ amount: 40000, due_date: "2026-09-30" }, { amount: 40000, due_date: "2026-10-30" }, { amount: 40000, due_date: "2026-11-30" }]), envelope, NOW, TZ)).toBeUndefined();
+  });
+
+  it("outside: discount above the ceiling, more than the principal, too many instalments, a tiny instalment", () => {
+    expect(checkEnvelope(items([{ amount: 101999, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.reason).toBe("outside_envelope");
+    expect(checkEnvelope(items([{ amount: 120001, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.detail).toContain("acima do principal");
+    expect(checkEnvelope(items([{ amount: 30000, due_date: "2026-09-30" }, { amount: 30000, due_date: "2026-10-30" }, { amount: 30000, due_date: "2026-11-30" }, { amount: 30000, due_date: "2026-12-15" }]), envelope, NOW, TZ)?.detail).toContain("parcelas");
+    expect(checkEnvelope(items([{ amount: 118000, due_date: "2026-09-30" }, { amount: 2000, due_date: "2026-10-30" }]), envelope, NOW, TZ)?.detail).toContain("minimo");
+  });
+
+  it("due dates: in the past, beyond the window, out of order, missing", () => {
+    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-09-22" }]), envelope, NOW, TZ)?.detail).toContain("ja passou");
+    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-12-23" }]), envelope, NOW, TZ)?.detail).toContain("fora da janela");
+    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-12-22" }]), envelope, NOW, TZ)).toBeUndefined();
+    expect(checkEnvelope(items([{ amount: 60000, due_date: "2026-10-30" }, { amount: 60000, due_date: "2026-09-30" }]), envelope, NOW, TZ)?.detail).toContain("antes da anterior");
+    expect(checkEnvelope(items([{ amount: 120000 }]), envelope, NOW, TZ)?.detail).toContain("sem vencimento");
+  });
+
+  it("collection hours are refused in both modes, whatever the proposal", () => {
+    const night = new Date("2026-09-24T01:00:00Z"); // 22:00 in Sao Paulo
+    const verdict = checkEnvelope(items([{ amount: 120000, due_date: "2026-09-30" }]), envelope, night, TZ);
+    expect(verdict?.reason).toBe("outside_hours");
+    const morning = new Date("2026-09-24T11:00:00Z"); // 08:00 in Sao Paulo, the window opens
+    expect(checkEnvelope(items([{ amount: 120000, due_date: "2026-09-30" }]), envelope, morning, TZ)).toBeUndefined();
+  });
+
+  it("one execution, one agreement", () => {
+    expect(checkEnvelope(items([{ amount: 60000, due_date: "2026-09-30" }, { amount: 60000, due_date: "2026-10-30", payee: AGREEMENTS[1]!.document }]), envelope, NOW, TZ)?.detail).toContain("more than one debtor");
+  });
+});

package/templates/collections-agent/agents/collections-agent/test/fixtures/accept-1042.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "create", "agreement": "acordo-1042", "instalments": [{"amount_minor": 108000, "due_date": "2026-09-30"}], "total_minor": 108000}}]}
+{"kind": "assistant_step", "reply": "Recebemos, acordo quitado. Obrigada, Joana!"}

package/templates/collections-agent/agents/collections-agent/test/fixtures/accept-1103.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind": "assistant_step", "tool_calls": [{"id": "tc_1", "name": "codespar_charge", "input": {"action": "create", "agreement": "acordo-1103", "instalments": [{"amount_minor": 40500, "due_date": "2026-09-25"}], "total_minor": 40500}}]}
+{"kind": "assistant_step", "reply": "A cobranca venceu sem pagamento. Se quiser, emito uma nova."}

package/templates/collections-agent/agents/collections-agent/test/scenarios.test.ts

@@ -0,0 +1,95 @@
+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 { AGREEMENTS } from "../src/agreements.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "../src/scenarios.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "collections-runs-"));
+const DOCUMENTS = AGREEMENTS.map((a) => a.document);
+
+describe("section 12: scenario packs, on the replay provider and the stub rail", () => {
+  const required = ["happy-path", "charge-expired", "prompt-injection", "cap-exceeded", "beneficiary-not-allowed", "escalated-above-threshold", "mandate-revoked", "instalments"];
+
+  it("ships every scenario the spec asks for, plus instalments", () => {
+    for (const name of required) expect(listScenarios()).toContain(name);
+  });
+
+  for (const name of required) {
+    const scenario = loadScenario(name);
+    for (const mode of scenario.modes) {
+      it(`${name} [${mode}] ends in the states the pack declares`, async () => {
+        const run = await runScenario(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; no event carries a debtor's document in the clear.
+        const raw = readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8");
+        const events = raw.split("\n").filter(Boolean).map((l) => JSON.parse(l) as { actor?: unknown; type: string });
+        expect(events.length).toBeGreaterThan(0);
+        for (const e of events) expect(e.actor).toBeDefined();
+        // Every record carries an actor and no raw document; the snapshot masks the book.
+        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; kind?: string; chain: string | null; payment: { payee: string | null; money_moved: boolean; sandbox: boolean } };
+          expect(receipt.actor).toBeDefined();
+          expect(receipt.kind).toBe("charge");
+          expect(receipt.chain).toBeNull();
+          expect(receipt.payment.money_moved).toBe(false);
+          expect(receipt.payment.sandbox).toBe(true);
+          expect(receipt.payment.payee ?? "").toContain("***");
+        }
+        const snapshot = readFileSync(join(run.bundle_dir, "mandate.snapshot.json"), "utf8");
+        for (const doc of DOCUMENTS) expect(snapshot).not.toContain(doc);
+      });
+    }
+  }
+
+  it("happy-path: the same records in human and in mandate; the person decided in human, the envelope in mandate", async () => {
+    const scenario = loadScenario("happy-path");
+    const human = await runScenario(scenario, { mode: "human", runsDir });
+    const mandate = await runScenario(scenario, { mode: "mandate", runsDir });
+    expect(normalizeReceipts(human)).toEqual(normalizeReceipts(mandate));
+    const approvals = (run: ScenarioRun) => JSON.parse(readFileSync(join(run.bundle_dir, "approval.json"), "utf8")) as Array<{ approver: { type: string }; items_hash: string; items: Array<{ due_date?: string }> }>;
+    expect(approvals(human)[0]?.approver.type).toBe("person");
+    expect(approvals(mandate)[0]?.approver.type).toBe("mandate");
+    expect(approvals(human)[0]?.items_hash).toBe(approvals(mandate)[0]?.items_hash);
+    expect(approvals(human)[0]?.items[0]?.due_date).toBe("2026-09-30");
+    // The payer saw the instrument once and was told once, in each mode.
+    for (const run of [human, mandate]) {
+      const events = readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; payload?: { payable?: boolean } });
+      expect(events.filter((e) => e.type === "charge.instrument" && e.payload?.payable === true)).toHaveLength(1);
+      expect(events.filter((e) => e.type === "message.debtor")).toHaveLength(1);
+      expect(events.filter((e) => e.type === "commerce.charge.paid")).toHaveLength(1);
+    }
+  });
+
+  it("nothing reaches executing without an approval artifact carrying its items_hash", async () => {
+    for (const name of required) {
+      const scenario = loadScenario(name);
+      for (const mode of scenario.modes) {
+        const run = await runScenario(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);
+        }
+      }
+    }
+  });
+
+  it("instalments: three receivables, three idempotency keys, one execution, one message", async () => {
+    const run = await runScenario(loadScenario("instalments"), { mode: "human", runsDir });
+    expect(run.executions).toHaveLength(1);
+    expect(new Set(run.executions[0]!.charge_ids).size).toBe(3);
+    expect(run.charges_issued).toBe(3);
+    expect(run.debtor_messages).toBe(1);
+  });
+});
+
+function normalizeReceipts(run: ScenarioRun): unknown[] {
+  return readdirSync(join(run.bundle_dir, "receipts"))
+    .map((f) => JSON.parse(readFileSync(join(run.bundle_dir, "receipts", f), "utf8")) as { state: string; kind?: string; payment: { amount_minor: number; payee: string | null; sandbox: boolean } })
+    .map((r) => ({ state: r.state, kind: r.kind, amount: r.payment.amount_minor, payee: r.payment.payee, sandbox: r.payment.sandbox }))
+    .sort((a, b) => a.amount - b.amount);
+}

package/templates/collections-agent/agents/collections-agent/test/webhook.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The webhook channel closes the cycle from a trigger delivery: signature
+ * verified when a secret is set, duplicates dropped, out-of-order ignored,
+ * the payer told once, the paid record fetched.
+ */
+import { createHmac } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { announceOutcome } from "../channels/terminal/index.js";
+import { createWebhookHandler, verifySignature } from "../channels/webhook/index.js";
+import { RUNS_DIR, setup } from "../src/setup.js";
+
+function issued(mode: "human" | "mandate" = "mandate") {
+  let clock = new Date("2026-09-23T18:00:00Z");
+  const s = setup({ mode, rail: "stub", provider: "replay", transcript: "unused", stateDir: mkdtempSync(join(tmpdir(), "collections-webhook-")), runsDir: mkdtempSync(join(tmpdir(), "collections-webhook-runs-")), now: () => (clock = new Date(clock.getTime() + 1000)), say: () => undefined });
+  s.payer.behave("never");
+  return s;
+}
+
+function delivery(id: string, type: string, chargeId: string): string {
+  return JSON.stringify({ id, type, source: "celcoin", occurred_at: "2026-09-23T18:00:30.000Z", data: { payment_id: chargeId, amount_minor: 108000, currency: "BRL", simulated: true, settled_against: "sandbox_fixture" } });
+}
+
+function sign(secret: string, body: string, t: number): string {
+  return `t=${t},v1=${createHmac("sha256", secret).update(`${t}.${body}`, "utf8").digest("hex")}`;
+}
+
+describe("channels/webhook", () => {
+  it("paid twice, created late, expired after paid: one settled, one message, one record", async () => {
+    const s = issued();
+    try {
+      const d = await s.engine.draft({ items: [{ payee: "acordo-1042", amount: 108000, due_date: "2026-09-30" }] });
+      if (!d.ok) throw new Error("refused");
+      const e = await s.engine.execute(d.execution.id);
+      expect(e.state).toBe("executing");
+      const chargeId = e.outcomes[0]!.transaction_id!;
+      const told: string[] = [];
+      const handle = createWebhookHandler({ engine: s.engine, onClosed: (x) => void announceOutcome(x, s, (l) => told.push(l)) });
+      expect(await handle({}, delivery("evt_1", "commerce.charge.paid", chargeId))).toEqual({ status: 200, body: { applied: true, reason: "settled" } });
+      expect(await handle({}, delivery("evt_1", "commerce.charge.paid", chargeId))).toEqual({ status: 200, body: { applied: false, reason: "duplicate event id" } });
+      expect(await handle({}, delivery("evt_2", "commerce.charge.created", chargeId))).toMatchObject({ status: 200, body: { applied: false } });
+      expect(await handle({}, delivery("evt_3", "commerce.charge.expired", chargeId))).toMatchObject({ status: 200, body: { applied: false, reason: "execution already settled" } });
+      expect(await handle({}, delivery("evt_4", "commerce.charge.paid", "chg_not_ours"))).toMatchObject({ status: 200, body: { applied: false, reason: "unknown attempt" } });
+      expect(await handle({}, "{not json")).toMatchObject({ status: 400 });
+      expect(s.engine.get(e.id)!.state).toBe("settled");
+      expect(told).toHaveLength(1);
+      expect(told[0]).toContain("acordo quitado");
+      expect(s.bundle.listReceipts()).toEqual([`${chargeId}.json`]);
+      expect(s.store.listEvents({ run_id: s.runId }).filter((ev) => ev.type === "message.debtor")).toHaveLength(1);
+    } finally {
+      s.close();
+    }
+  });
+
+  it("with a trigger secret: a missing, stale or wrong signature is 401 and moves nothing", async () => {
+    const s = issued();
+    try {
+      const d = await s.engine.draft({ items: [{ payee: "acordo-1042", amount: 108000, due_date: "2026-09-30" }] });
+      if (!d.ok) throw new Error("refused");
+      const e = await s.engine.execute(d.execution.id);
+      const chargeId = e.outcomes[0]!.transaction_id!;
+      const now = new Date("2026-09-23T18:01:00Z");
+      const handle = createWebhookHandler({ engine: s.engine, secret: "whsec_test", clock: () => now });
+      const body = delivery("evt_s1", "commerce.charge.paid", chargeId);
+      expect((await handle({}, body)).status).toBe(401);
+      expect((await handle({ "x-codespar-signature": sign("whsec_other", body, Math.floor(now.getTime() / 1000)) }, body)).status).toBe(401);
+      expect((await handle({ "x-codespar-signature": sign("whsec_test", body, Math.floor(now.getTime() / 1000) - 3600) }, body)).status).toBe(401);
+      expect(s.engine.get(e.id)!.state).toBe("executing");
+      expect(await handle({ "x-codespar-signature": sign("whsec_test", body, Math.floor(now.getTime() / 1000)) }, body)).toEqual({ status: 200, body: { applied: true, reason: "settled" } });
+      expect(verifySignature("whsec_test", "garbage", body, now, 300)).toMatchObject({ ok: false });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("expired by webhook closes failed with charge_expired and tells the payer once", async () => {
+    const s = issued("human");
+    try {
+      const d = await s.engine.draft({ items: [{ payee: "acordo-1103", amount: 40500, due_date: "2026-09-25" }] });
+      if (!d.ok) throw new Error("refused");
+      const approved = s.engine.approve(d.execution.id, { id: "usr_operator", channel: "terminal" });
+      const e = await s.engine.execute(approved.id);
+      const chargeId = e.outcomes[0]!.transaction_id!;
+      const told: string[] = [];
+      const handle = createWebhookHandler({ engine: s.engine, onClosed: (x) => void announceOutcome(x, s, (l) => told.push(l)) });
+      expect(await handle({}, delivery("evt_x1", "commerce.charge.expired", chargeId))).toEqual({ status: 200, body: { applied: true, reason: "failed" } });
+      expect(await handle({}, delivery("evt_x2", "commerce.charge.paid", chargeId))).toMatchObject({ body: { applied: false } });
+      expect(s.engine.get(e.id)).toMatchObject({ state: "failed", reason: "charge_expired" });
+      expect(told).toHaveLength(1);
+      expect(told[0]).toContain("venceu");
+      expect(s.bundle.listReceipts()).toEqual([]);
+    } finally {
+      s.close();
+    }
+  });
+});
+
+void RUNS_DIR;

package/templates/collections-agent/agents/collections-agent/tools.json

@@ -0,0 +1,40 @@
+{
+  "meta_tools": [
+    {
+      "name": "codespar_charge",
+      "effect": "charge",
+      "description": "Propose the receivable(s) of an agreement the payer accepted: one instalment per bolepix (cobranca com vencimento: the payer settles by Pix or by boleto). This does NOT issue anything: it creates an execution in `drafted` that the code checks against the collection policy and the negotiation envelope (discount ceiling, instalment count, due-date window, collection hours) and, depending on the approval mode, asks the operator or issues. The code builds the real call (`POST /v1/charges`, `method: boleto`, the debtor's name and document from the agreement, `idempotency_key` per instalment) and presents the QR and the copy-and-paste; you never see or pass a document. action=status reads back the state of a receivable this run issued.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["create", "status"], "description": "create (the default) proposes the receivables; status reads one back." },
+          "agreement": { "type": "string", "description": "The agreement alias from list_agreements (acordo-1042). Never a name, a document or a Pix key typed in the chat." },
+          "instalments": {
+            "type": "array",
+            "minItems": 1,
+            "description": "One entry per instalment, in order. A single entry is a payment in full.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "amount_minor": { "type": "integer", "minimum": 1, "description": "BRL cents." },
+                "due_date": { "type": "string", "description": "YYYY-MM-DD. Inside the envelope's window." }
+              },
+              "required": ["amount_minor", "due_date"]
+            }
+          },
+          "total_minor": { "type": "integer", "description": "Optional. What you believe the total is. The code recomputes it and yours is only recorded." },
+          "execution_id": { "type": "string", "description": "action=status: the execution to read." }
+        },
+        "required": ["action"]
+      }
+    }
+  ],
+  "local_tools": [
+    {
+      "name": "list_agreements",
+      "effect": "read",
+      "description": "The open agreements this merchant collects: alias, debtor's first name, principal in BRL cents, origin, and the envelope you may negotiate inside (maximum discount, maximum instalments, due-date window). Read-only. Documents are not returned.",
+      "input_schema": { "type": "object", "properties": {} }
+    }
+  ]
+}

package/templates/collections-agent/agents/collections-agent/tsconfig.json

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

package/templates/collections-agent/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "packages/agent-core",
+    "agents/collections-agent"
+  ],
+  "scripts": {
+    "start": "npm start --workspace=agents/collections-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 agents/collections-agent/tsconfig.json",
+    "approve": "npm run approve --workspace=agents/collections-agent --",
+    "deny": "npm run deny --workspace=agents/collections-agent --",
+    "eval": "npm run eval --workspace=agents/collections-agent --",
+    "poll": "npm run poll --workspace=agents/collections-agent --",
+    "reconcile": "npm run reconcile --workspace=agents/collections-agent --",
+    "rerun": "npm run rerun --workspace=agents/collections-agent --",
+    "resume": "npm run resume --workspace=agents/collections-agent --",
+    "webhook": "npm run webhook --workspace=agents/collections-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/collections-agent/packages/agent-core/README.md

@@ -0,0 +1,19 @@
+# @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.
+
+## 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/collections-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.4",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  }
+}