@codespar/cli 0.14.0 → 0.16.0

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

@@ -8,14 +8,13 @@ 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";
+import { announceOutcome, createWebhookHandler, setup, verifySignature } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.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");
+  const s = setup(agent, { 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;
 }
 
@@ -96,5 +95,3 @@ describe("channels/webhook", () => {
     }
   });
 });
-
-void RUNS_DIR;

package/templates/collections-agent/agents/collections-agent/test/whatsapp-poll.test.ts

@@ -0,0 +1,271 @@
+/**
+ * The case the channel could not run before: agreed on Tuesday, paid on
+ * Friday.
+ *
+ * Every case that converses runs TWO processes over ONE state directory,
+ * because that is the shape in production — the run that agreed the terms has
+ * exited by the time the money lands, and what carries the cycle across is
+ * the record it left. Between them the CONVERSATION's clock moves
+ * (`POST /_sim/clock`), which is a different thing from the AGENT's clock
+ * (`--now`, #16): one is where the person's last message sits, the other is
+ * what the guardrails and the window comparison read.
+ *
+ * What is asserted is which CARRIER the confirmation went out on and that the
+ * cycle closed, never the wording. Read the template assertions precisely:
+ * the emulator prices the 24-hour window and does not enforce it
+ * (docs/OPEN_QUESTIONS.md §46a), so what passes here is OUR choice of
+ * carrier, made by the session window, and not the provider refusing the
+ * alternative.
+ *
+ * The conversing cases SKIP without the emulator, like the rest of the
+ * channel suite; `npm run whatsapp:gate` fails rather than skipping, so the
+ * thing that matters never hides behind one. The cases that need no
+ * conversation at all — the no-op, the flag that belongs to another channel —
+ * run everywhere.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, 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 BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+
+/** Tuesday, inside the collection hours the guardrails declare. */
+const TUESDAY = "2026-09-23T14:00:00-03:00";
+const ADVANCE_HOURS = 26;
+/** The same instant plus the advance: 16:00 in Sao Paulo, still inside 08:00-20:00. */
+const AFTER_WINDOW = new Date(new Date(TUESDAY).getTime() + ADVANCE_HOURS * 3600_000).toISOString();
+/**
+ * The recording where the charge is issued and NOBODY has paid yet. The
+ * shipped happy-path one closes with "quitado" because its payer paid inside
+ * the turn; here that would be a lie, and it is the lie this whole command
+ * exists to stop telling.
+ */
+const AGREED = "test/fixtures/agreed-1042-awaiting-payer.transcript.jsonl";
+
+interface ChannelLine {
+  direction: "in" | "out";
+  kind: string;
+  text?: string;
+  message_id: string;
+  provider_timestamp?: number;
+  refused?: { rule: string };
+}
+
+interface Polled {
+  id: string;
+  state: string;
+  reason: string | null;
+  timed_out: boolean;
+  session_open: boolean;
+  delivery: { told: boolean; carrier?: string; template?: string; reason?: string };
+}
+
+interface PollPayload {
+  polled: Polled[];
+  conversation: string;
+  channel: { backend: string; session_open: boolean; messages_out: number; refused: Array<{ rule: string }>; log: string } | null;
+}
+
+function scratch(label: string) {
+  const stateDir = mkdtempSync(join(tmpdir(), `collections-wa-poll-${label}-`));
+  return { COLLECTIONS_STATE_DIR: stateDir, COLLECTIONS_RUNS_DIR: join(stateDir, "runs") };
+}
+
+function agent(args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, [BIN, ...args], {
+    cwd: AGENT_DIR,
+    env: {
+      ...process.env,
+      ANTHROPIC_API_KEY: "",
+      CODESPAR_API_KEY: "",
+      // A developer's own Meta credentials must not change what this suite does.
+      WHATSAPP_PHONE_NUMBER_ID: "",
+      WHATSAPP_ACCESS_TOKEN: "",
+      WHATSAPP_VERIFY_TOKEN: "",
+      WHATSAPP_APP_SECRET: "",
+      ...env,
+    },
+    encoding: "utf8",
+    timeout: 90_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/** Tuesday: the debtor agrees, the bolepix is issued, and the fixture payer is told to sit on it. */
+function agree(env: Record<string, string>) {
+  return agent(
+    ["start", "--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--mode", "mandate", "--transcript", AGREED, "--now", TUESDAY, "--json"],
+    { ...env, COLLECTIONS_STUB_PAYER: "never" },
+  );
+}
+
+function poll(env: Record<string, string>, extra: string[] = []) {
+  const out = agent(["poll", "--channel", "whatsapp", "--conversation", "acordo-1042", "--json", ...extra], env);
+  const lines = out.stdout.split("\n").filter(Boolean);
+  expect(lines).toHaveLength(1);
+  return { ...out, payload: JSON.parse(lines[0]!) as PollPayload };
+}
+
+async function advanceConversationClock(hours: number) {
+  const response = await fetch(`${EMULATOR}/_sim/clock`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ advance_hours: hours }),
+    signal: AbortSignal.timeout(5000),
+  });
+  expect(response.ok).toBe(true);
+}
+
+function conversationOf(logPath: string): ChannelLine[] {
+  const path = isAbsolute(logPath) ? logPath : join(AGENT_DIR, logPath);
+  expect(existsSync(path)).toBe(true);
+  return readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as ChannelLine);
+}
+
+function countEvents(env: Record<string, string>, type: string): number {
+  const db = new DatabaseSync(join(env["COLLECTIONS_STATE_DIR"]!, "state.db"));
+  try {
+    return (db.prepare("SELECT COUNT(*) AS n FROM events WHERE type = ?").get(type) as { n: number }).n;
+  } finally {
+    db.close();
+  }
+}
+
+const emulatorUp = await (async () => {
+  try {
+    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+  } catch {
+    return false;
+  }
+})();
+if (!emulatorUp) process.stderr.write(`[whatsapp] no emulator at ${EMULATOR}; the poll's conversing cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
+
+describe.skipIf(!emulatorUp)("a charge paid after the 24-hour window closed", () => {
+  it("confirms by template, closes the cycle, and leaves one conversation rather than two", async () => {
+    const env = scratch("template");
+
+    const agreed = agree(env);
+    // Nobody has paid: the execution is still open and that is why the process exits 3.
+    expect(agreed.code).toBe(3);
+    const opened = JSON.parse(agreed.stdout.split("\n").filter(Boolean).pop()!) as { executions: Array<{ state: string; reason: string }>; channel: { log: string } };
+    expect(opened.executions[0]).toMatchObject({ state: "executing", reason: "awaiting_settlement" });
+    const before = conversationOf(opened.channel.log);
+    // The person's own message carries the provider's clock, which is the only
+    // thing the window can be counted from once this process is gone.
+    expect(before.filter((l) => l.direction === "in").every((l) => typeof l.provider_timestamp === "number")).toBe(true);
+    expect(before.some((l) => l.direction === "out" && /quitad/i.test(l.text ?? ""))).toBe(false);
+
+    await advanceConversationClock(ADVANCE_HOURS);
+
+    const polled = poll(env, ["--simulate-payer", "--now", AFTER_WINDOW]);
+    expect(polled.code).toBe(0);
+    expect(polled.payload.polled).toHaveLength(1);
+    expect(polled.payload.polled[0]).toMatchObject({
+      state: "settled",
+      timed_out: false,
+      session_open: false,
+      delivery: { told: true, carrier: "template", template: "acordo_quitado" },
+    });
+    expect(polled.payload.channel?.refused).toEqual([]);
+    // One message, and only one, went out with the window shut.
+    expect(polled.payload.channel?.messages_out).toBe(1);
+
+    // The confirmation was appended to the bundle of the run that opened the
+    // conversation, so it sits under the QR it confirms instead of in a second folder.
+    const after = conversationOf(polled.payload.channel!.log);
+    expect(after.slice(0, before.length)).toEqual(before);
+    const last = after[after.length - 1]!;
+    expect(last.kind).toBe("template");
+    expect(last.text).toContain("acordo_quitado");
+    expect(last.refused).toBeUndefined();
+    // It went through the provider's own surface, not around it.
+    expect(last.message_id).toMatch(/^wamid\./);
+
+    expect(countEvents(env, "message.debtor")).toBe(1);
+    expect(countEvents(env, "commerce.charge.paid")).toBe(1);
+    const runs = env["COLLECTIONS_RUNS_DIR"]!;
+    const receipts = readdirSync(runs).flatMap((d) => (existsSync(join(runs, d, "receipts")) ? readdirSync(join(runs, d, "receipts")) : []));
+    expect(receipts).toHaveLength(1);
+  });
+
+  it("polled twice, tells the person once: the cursor that says so is in state.db, not in the process", async () => {
+    const env = scratch("twice");
+    expect(agree(env).code).toBe(3);
+    await advanceConversationClock(ADVANCE_HOURS);
+
+    const first = poll(env, ["--simulate-payer", "--now", AFTER_WINDOW]);
+    expect(first.payload.polled[0]!.delivery.told).toBe(true);
+
+    // The execution is terminal, so there is nothing left waiting for a payer
+    // and the second poll never opens the channel at all.
+    const second = poll(env, ["--simulate-payer", "--now", AFTER_WINDOW]);
+    expect(second.code).toBe(0);
+    expect(second.payload.polled).toEqual([]);
+    expect(second.payload.channel).toBeNull();
+    expect(countEvents(env, "message.debtor")).toBe(1);
+  });
+
+  it("writes freely while the window is still open: the carrier follows the rule, not the command", async () => {
+    const env = scratch("open");
+    expect(agree(env).code).toBe(3);
+    // No clock move: the person wrote minutes ago.
+    const polled = poll(env, ["--simulate-payer", "--now", "2026-09-23T15:30:00-03:00"]);
+    expect(polled.code).toBe(0);
+    expect(polled.payload.polled[0]).toMatchObject({ state: "settled", session_open: true, delivery: { told: true, carrier: "text" } });
+    const last = conversationOf(polled.payload.channel!.log).at(-1)!;
+    expect(last.kind).toBe("text");
+    expect(last.text).toMatch(/quitad/i);
+  });
+
+  it("a charge that expired gets the expiry template and not the paid one", async () => {
+    const env = scratch("expired");
+    expect(agree(env).code).toBe(3);
+    await advanceConversationClock(ADVANCE_HOURS);
+
+    // No `--simulate-payer`: nobody paid, and that is the point. `--payer
+    // expires` rewrites the fate of the receivable this state already holds.
+    const polled = poll(env, ["--payer", "expires", "--now", AFTER_WINDOW]);
+    expect(polled.payload.polled[0]).toMatchObject({
+      state: "failed",
+      reason: "charge_expired",
+      session_open: false,
+      delivery: { told: true, carrier: "template", template: "acordo_cobranca_vencida" },
+    });
+    const last = conversationOf(polled.payload.channel!.log).at(-1)!;
+    expect(last.text).toContain("acordo_cobranca_vencida");
+    expect(last.text).not.toContain("acordo_quitado");
+    // Nothing was paid, so nothing was sealed.
+    const runs = env["COLLECTIONS_RUNS_DIR"]!;
+    expect(readdirSync(runs).flatMap((d) => (existsSync(join(runs, d, "receipts")) ? readdirSync(join(runs, d, "receipts")) : []))).toHaveLength(0);
+  });
+});
+
+describe("what the poll refuses to be asked, with no emulator in sight", () => {
+  it("nothing waiting for a payer is a clean no-op, not an error: a cron that fails on an empty queue gets turned off", () => {
+    const env = scratch("noop");
+    const out = poll(env, ["--now", TUESDAY]);
+    expect(out.code).toBe(0);
+    expect(out.payload).toEqual({ polled: [], conversation: "acordo-1042", channel: null });
+    // The channel was never opened, so a machine with no emulator running
+    // still gets a clean answer.
+    expect(out.stderr).not.toContain("emulator backend");
+  });
+
+  it("refuses --conversation on the terminal channel rather than quietly ignoring it", () => {
+    const out = agent(["poll", "--conversation", "acordo-1042", "--json"], scratch("flag"));
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("belong to --channel whatsapp");
+  });
+
+  it("refuses a flag it does not know, so a typo is not a silently different run", () => {
+    const out = agent(["poll", "--chanel", "whatsapp"], scratch("typo"));
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("unknown argument --chanel");
+  });
+});

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

@@ -0,0 +1,213 @@
+/**
+ * The collections-agent on the channel it was written for.
+ *
+ * Every case here runs a real process: no key of either kind, and the
+ * WHATSAPP_* variables explicitly blanked, so a machine that happens to have
+ * Meta credentials in its shell runs the same test as the CI.
+ *
+ * The cases that actually converse need `dyvit-wa-sim` listening — the local
+ * Cloud API emulator the channel's `simulator` backend talks to — and SKIP
+ * when it is not, so `npm test` is green on a machine that never started it.
+ * The CI starts it, and `npm run whatsapp:gate` fails rather than skipping, so
+ * the thing that matters never hides behind a skip. The cases that check what
+ * the channel REFUSES to be asked need no emulator: those refusals happen
+ * before anything is opened, and they run everywhere.
+ *
+ * What is asserted is the final state and the shape of the conversation, never
+ * the wording — the copy-and-paste as its own message, the operator's question
+ * nowhere near the debtor, nothing at all outside the collection hours.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+interface ChannelLine {
+  direction: "in" | "out";
+  kind: string;
+  text?: string;
+  contact: string;
+  state: string;
+  message_id: string;
+  refused?: { rule: string };
+}
+
+interface Payload {
+  executions: Array<{ state: string; charges: Array<{ charge_id: string | null }> }>;
+  receipts: string[];
+  channel: { backend: string; conversation: string; turns: number; messages_in: number; messages_out: number; refused: Array<{ rule: string }>; log: string };
+}
+
+function run(args: string[], extra: Record<string, string> = {}) {
+  const stateDir = mkdtempSync(join(tmpdir(), "collections-wa-"));
+  const result = spawnSync(NODE, [BIN, "start", ...args], {
+    cwd: AGENT_DIR,
+    env: {
+      ...process.env,
+      ANTHROPIC_API_KEY: "",
+      CODESPAR_API_KEY: "",
+      // A developer's own Meta credentials must not change what this suite does.
+      WHATSAPP_PHONE_NUMBER_ID: "",
+      WHATSAPP_ACCESS_TOKEN: "",
+      WHATSAPP_VERIFY_TOKEN: "",
+      WHATSAPP_APP_SECRET: "",
+      COLLECTIONS_STATE_DIR: stateDir,
+      COLLECTIONS_RUNS_DIR: join(stateDir, "runs"),
+      ...extra,
+    },
+    encoding: "utf8",
+    timeout: 90_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+function payloadOf(stdout: string): Payload {
+  const lines = stdout.split("\n").filter(Boolean);
+  expect(lines).toHaveLength(1);
+  return JSON.parse(lines[0]!) as Payload;
+}
+
+function conversationOf(payload: Payload): ChannelLine[] {
+  const path = isAbsolute(payload.channel.log) ? payload.channel.log : join(AGENT_DIR, payload.channel.log);
+  expect(existsSync(path)).toBe(true);
+  return readFileSync(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as ChannelLine);
+}
+
+const EMULATOR = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+/** Probed at module level: `describe.skipIf` is read when the file is collected, before any hook runs. */
+const emulatorUp = await (async () => {
+  try {
+    return (await fetch(`${EMULATOR}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+  } catch {
+    return false;
+  }
+})();
+if (!emulatorUp) process.stderr.write(`[whatsapp] no emulator at ${EMULATOR}; the conversing cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
+
+const INSIDE_HOURS = ["--now", "2026-09-23T14:00:00-03:00"];
+const AFTER_HOURS = ["--now", "2026-09-23T22:30:00-03:00"];
+const SCRIPTED = ["--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--simulate-payer", "--json"];
+
+describe.skipIf(!emulatorUp)("the cycle closes over the WhatsApp channel", () => {
+  it("settles in mandate mode with nobody at a keyboard, and sends the QR with the copy-and-paste under it", () => {
+    const out = run([...SCRIPTED, "--mode", "mandate", ...INSIDE_HOURS]);
+    expect(out.code).toBe(0);
+    const payload = payloadOf(out.stdout);
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(payload.executions[0]!.charges).toHaveLength(1);
+    expect(payload.receipts).toHaveLength(1);
+    expect(payload.channel.backend).toBe("emulator");
+    // The one expected refusal: neither backend can upload the QR image.
+    expect(payload.channel.refused.map((r) => r.rule)).toEqual(["media_upload_unimplemented"]);
+
+    const conversation = conversationOf(payload);
+    const outbound = conversation.filter((l) => l.direction === "out");
+    const qr = outbound.findIndex((l) => l.kind === "media");
+    expect(qr).toBeGreaterThanOrEqual(0);
+    expect(outbound[qr + 1]!.kind).toBe("instrument");
+    expect(outbound[qr + 1]!.text).toMatch(/^00020126/);
+    expect(conversation.filter((l) => l.direction === "in")).toHaveLength(2);
+    // Every delivered message carries a provider id: it went through the Cloud API surface, not around it.
+    for (const line of outbound.filter((l) => !l.refused)) expect(line.message_id).toMatch(/^wamid\./);
+  });
+
+  it("settles in human mode too, and the operator's question never reaches the debtor", () => {
+    const out = run([...SCRIPTED, "--mode", "human", "--approve", ...INSIDE_HOURS]);
+    expect(out.code).toBe(0);
+    const payload = payloadOf(out.stdout);
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    // The question is the operator's and is on the console; nothing like it is in the conversation.
+    for (const line of conversationOf(payload)) expect(line.text ?? "").not.toMatch(/operador|Aprovar a emissao/i);
+  });
+
+  it("writes the conversation into the bundle with the contact masked", () => {
+    const out = run([...SCRIPTED, "--mode", "mandate", ...INSIDE_HOURS]);
+    const conversation = conversationOf(payloadOf(out.stdout));
+    expect(conversation.length).toBeGreaterThan(0);
+    for (const line of conversation) {
+      expect(line.contact).not.toContain("987654321");
+      expect(line.contact).toContain("****");
+    }
+  });
+
+  it("tells the person once when the charge expires, and writes no record", () => {
+    const out = run(["--channel", "whatsapp", "--conversation", "acordo-1103", "--scripted", "--mode", "mandate", "--payer", "expires", "--json", ...INSIDE_HOURS]);
+    const payload = payloadOf(out.stdout);
+    expect(payload.executions.map((e) => e.state)).toEqual(["failed"]);
+    expect(payload.receipts).toEqual([]);
+    expect(payload.channel.conversation).toBe("acordo-1103");
+    // The QR still went out: it was payable, nobody paid it.
+    const outbound = conversationOf(payload).filter((l) => l.direction === "out");
+    expect(outbound.some((l) => l.kind === "media")).toBe(true);
+    // The kit's one-per-outcome message, sent once however many looks carried the event.
+    // The model's own reply also says the charge expired, which is the terminal's behaviour too.
+    expect(outbound.filter((l) => String(l.text ?? "").startsWith("A cobranca venceu sem pagamento"))).toHaveLength(1);
+  });
+
+  it("refuses to say anything at all outside the collection hours, and issues nothing", () => {
+    const out = run([...SCRIPTED, "--mode", "mandate", ...AFTER_HOURS]);
+    const payload = payloadOf(out.stdout);
+    expect(payload.channel.messages_out).toBe(0);
+    // The emulator would have accepted every one of them: the collection hours are OUR rule, not WhatsApp's.
+    expect(payload.channel.refused.map((r) => r.rule)).toContain("collection_hours");
+    expect(payload.executions.flatMap((e) => e.charges)).toEqual([]);
+    expect(payload.receipts).toEqual([]);
+  });
+});
+
+describe("what the channel refuses to be asked", () => {
+  it("refuses the cloud-api backend by naming every credential this repo does not ship", () => {
+    const out = run(["--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--backend", "cloud-api", "--mode", "mandate", ...INSIDE_HOURS]);
+    expect(out.code).toBe(1);
+    for (const name of ["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN", "WHATSAPP_VERIFY_TOKEN", "WHATSAPP_APP_SECRET"]) {
+      expect(out.stderr).toContain(name);
+    }
+    expect(out.stderr).toContain("emulator");
+  });
+
+  it("refuses --input on a channel: a conversation takes its turns from the conversation", () => {
+    const out = run(["--channel", "whatsapp", "--input", "oi", "--json"]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--input");
+  });
+
+  it("refuses the channel flags on the terminal", () => {
+    expect(run(["--backend", "simulator", "--input", "oi"]).code).toBe(2);
+    expect(run(["--conversation", "acordo-1042", "--input", "oi"]).code).toBe(2);
+  });
+
+  it("refuses a scripted human-mode run rather than waiting on a keyboard nobody is at", () => {
+    const out = run(["--channel", "whatsapp", "--conversation", "acordo-1042", "--scripted", "--mode", "human", "--json", ...INSIDE_HOURS]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--approve");
+  });
+
+  it("asks which conversation when the agent ships more than one: which debtor is not a default", () => {
+    const out = run(["--channel", "whatsapp", "--scripted", "--json", ...INSIDE_HOURS]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--conversation is required");
+    expect(out.stderr).toContain("acordo-1103");
+  });
+
+  it("refuses a conversation the agent does not ship", () => {
+    const out = run(["--channel", "whatsapp", "--scripted", "--conversation", "acordo-9999", "--json", ...INSIDE_HOURS]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("acordo-1042");
+  });
+});
+
+describe("the terminal is untouched", () => {
+  it("still runs the same one-shot with no channel flag", () => {
+    const out = run(["--input", "fechado, pago à vista", "--transcript", "test/fixtures/accept-1042.transcript.jsonl", "--approve", "--simulate-payer", "--json", ...INSIDE_HOURS]);
+    expect(out.code).toBe(0);
+    const payload = JSON.parse(out.stdout.split("\n").filter(Boolean)[0]!) as Payload & { channel?: unknown };
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    // No channel key: a terminal run is not a channel run, and its JSON shape did not change.
+    expect(payload.channel).toBeUndefined();
+  });
+});

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

@@ -5,7 +5,6 @@
   },
   "include": [
     "src/**/*.ts",
-    "channels/**/*.ts",
     "test/**/*.ts"
   ]
 }

package/templates/collections-agent/package.json

@@ -7,16 +7,18 @@
   "type": "module",
   "workspaces": [
     "packages/agent-core",
+    "packages/agent-runtime",
     "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",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/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 --",
+    "inspect": "npm run inspect --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 --",

package/templates/collections-agent/packages/agent-core/README.md

@@ -2,6 +2,8 @@
 
 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.

package/templates/collections-agent/packages/agent-core/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.128.0",
-    "@codespar/sdk": "0.16.4",
+    "@codespar/sdk": "0.16.6",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   }

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

@@ -79,10 +79,12 @@ export class CodeSparChargeRail implements PaymentRail {
 
   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",
@@ -108,15 +110,32 @@ export class CodeSparChargeRail implements PaymentRail {
     return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
   }
 
-  async lookup(attemptId: string, _payment: RailPayment): Promise<RailLookup> {
+  /**
+   * 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: attemptId } })) as ChargeView;
-      return outcomeOf(view);
+      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 undefined;
-      if (failure.status === 409) return { status: "in_flight" };
-      return { status: "uncertain", code: failure.code, message: failure.message };
+      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 } };
     }
   }
 
@@ -133,6 +152,8 @@ export class CodeSparChargeRail implements PaymentRail {
         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,
       };

package/templates/collections-agent/packages/agent-core/src/api/rail.ts

@@ -18,6 +18,16 @@ import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } f
 import type { Actor } from "../types.js";
 import { describeApiError, isUncertain } from "./client.js";
 
+/** The asymmetric seal as the API serves it, or nulls when this deployment
+ *  does not serve one. Never throws on a shape it does not recognise: a
+ *  receipt is evidence of a payment that already happened, and refusing to
+ *  record it over an unexpected field would trade the record for the proof. */
+function readEd25519Seal(body: unknown): { receipt_sig_ed25519: string | null; receipt_sig_kid: string | null } {
+  const r = body as { receipt_sig_ed25519?: unknown; receipt_sig_kid?: unknown };
+  const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
+  return { receipt_sig_ed25519: str(r.receipt_sig_ed25519), receipt_sig_kid: str(r.receipt_sig_kid) };
+}
+
 export class CodeSparRail implements PaymentRail {
   readonly name = "codespar" as const;
 
@@ -89,6 +99,12 @@ export class CodeSparRail implements PaymentRail {
         },
         chain: r.chain,
         receipt_sig: r.receipt_sig,
+        // ent#1633 landed after `@codespar/sdk@0.16.6` was generated, so the
+        // typed response does not carry these two yet. Read off the body
+        // defensively rather than pinning a new SDK for two nullable strings:
+        // a deployment that predates the change answers null, which is the
+        // same answer the columns hold and reads as `unsigned`.
+        ...readEd25519Seal(r),
         actor,
         raw: r,
       };