@codespar/cli 0.13.0 → 0.14.0

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

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

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

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

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

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

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

@@ -0,0 +1,103 @@
+/**
+ * Module `bolepix-receivables`, the envelope: what the agent may agree on
+ * its own, applied by deterministic code at every gate of the core. The
+ * model negotiates inside it; the code confers before the proposal leaves
+ * (section 7, step 2). The policy of the receiving side is not signed by
+ * the API today (section 16), so it lives in `guardrails.json` under
+ * `envelope` and the core runs it as its `policyExtension`.
+ *
+ * Every rule here can only refuse. None of them widens the collection
+ * policy (the debtors' book, the cap per receivable, the window cap).
+ */
+import { z } from "zod";
+import { isOutsideHours, localClock, type Execution, type ExecutionReason, type Guardrails, type PolicyExtension } from "@codespar/agent-core";
+import { agreementByDocument, type Agreement } from "./agreements.js";
+
+export const EnvelopeSchema = z
+  .object({
+    /** The largest discount over the principal, in percent. */
+    max_discount_pct: z.number().min(0).max(100),
+    max_instalments: z.number().int().positive(),
+    /** A due date may be at most this many days from today. */
+    due_date_window_days: z.number().int().positive(),
+    min_instalment_minor: z.number().int().positive(),
+    /** The hours a debtor may be contacted, `HH:MM-HH:MM` in `guardrails.timezone`. Outside them nothing is proposed or issued. */
+    collection_hours: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/),
+  })
+  .strict();
+
+export type Envelope = z.infer<typeof EnvelopeSchema>;
+
+export function loadEnvelope(guardrails: Guardrails): Envelope {
+  if (!guardrails.envelope) throw new Error("guardrails.json has no `envelope`; the collections-agent needs one");
+  return EnvelopeSchema.parse(guardrails.envelope);
+}
+
+/** The floor of an agreement: the principal minus the maximum discount, rounded up so the discount never exceeds the ceiling by a cent. */
+export function floorMinor(agreement: Agreement, envelope: Envelope): number {
+  return Math.ceil((agreement.principal_minor * (100 - envelope.max_discount_pct)) / 100);
+}
+
+/** `YYYY-MM-DD` of `now` in the zone. */
+export function localDate(now: Date, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(now);
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+function addDays(iso: string, days: number): string {
+  const d = new Date(`${iso}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+export interface EnvelopeVerdict {
+  reason: ExecutionReason;
+  detail: string;
+}
+
+/** The pure check, for tests and for the tool handler's early answer. `undefined` means inside the envelope. */
+export function checkEnvelope(execution: Pick<Execution, "items" | "total">, envelope: Envelope, now: Date, timezone: string): EnvelopeVerdict | undefined {
+  // Collection hours are the law's, not the merchant's: the window in which a debtor may be contacted at all.
+  const [open, close] = envelope.collection_hours.split("-") as [string, string];
+  if (isOutsideHours(`${close}-${open}`, now, timezone)) {
+    return { reason: "outside_hours", detail: `fora do horario de cobranca (${envelope.collection_hours} ${timezone}); agora sao ${localClock(now, timezone)}` };
+  }
+
+  const documents = new Set(execution.items.map((i) => i.payee));
+  if (documents.size !== 1) return { reason: "outside_envelope", detail: "one execution covers one agreement; the items name more than one debtor" };
+  const document = execution.items[0]!.payee;
+  const agreement = agreementByDocument(document);
+  // A debtor the allowlist does not name is refused by the core before this runs; a named one without a book entry is a fixture defect.
+  if (!agreement) return { reason: "outside_envelope", detail: "no open agreement for this debtor" };
+
+  if (execution.items.length > envelope.max_instalments) {
+    return { reason: "outside_envelope", detail: `${execution.items.length} parcelas; o envelope permite ate ${envelope.max_instalments}` };
+  }
+  const floor = floorMinor(agreement, envelope);
+  if (execution.total < floor) {
+    const pct = Math.round((1 - execution.total / agreement.principal_minor) * 1000) / 10;
+    return { reason: "outside_envelope", detail: `total ${execution.total} e ${pct}% abaixo do principal ${agreement.principal_minor}; o desconto maximo e ${envelope.max_discount_pct}% (piso ${floor})` };
+  }
+  if (execution.total > agreement.principal_minor) {
+    return { reason: "outside_envelope", detail: `total ${execution.total} acima do principal ${agreement.principal_minor}; nao se cobra mais do que se deve` };
+  }
+  const small = execution.items.find((i) => i.amount < envelope.min_instalment_minor);
+  if (small) return { reason: "outside_envelope", detail: `parcela de ${small.amount} abaixo do minimo ${envelope.min_instalment_minor}` };
+
+  const today = localDate(now, timezone);
+  const last = addDays(today, envelope.due_date_window_days);
+  let previous = "";
+  for (const [i, item] of execution.items.entries()) {
+    if (!item.due_date) return { reason: "outside_envelope", detail: `parcela ${i + 1} sem vencimento` };
+    if (item.due_date < today) return { reason: "outside_envelope", detail: `vencimento ${item.due_date} da parcela ${i + 1} ja passou (hoje e ${today})` };
+    if (item.due_date > last) return { reason: "outside_envelope", detail: `vencimento ${item.due_date} da parcela ${i + 1} fora da janela de ${envelope.due_date_window_days} dias (ate ${last})` };
+    if (item.due_date < previous) return { reason: "outside_envelope", detail: `parcela ${i + 1} vence antes da anterior` };
+    previous = item.due_date;
+  }
+  return undefined;
+}
+
+export function envelopePolicy(envelope: Envelope): PolicyExtension {
+  return (execution, ctx) => checkEnvelope(execution, envelope, ctx.now, ctx.guardrails.timezone);
+}

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

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

package/templates/collections-agent/agents/collections-agent/src/modules/bolepix-receivables.ts

@@ -0,0 +1,105 @@
+/**
+ * Module `bolepix-receivables`: the tool handlers the model can reach.
+ * `codespar_charge` hands the proposal to the engine and gets an execution in
+ * `drafted` (then whatever the core decided); it cannot issue anything.
+ * `list_agreements` is a read. The real call (`POST /v1/charges`, one
+ * cobranca com vencimento per instalment, `idempotency_key` per attempt) is
+ * built by the rail from the execution the core approved.
+ */
+import type { ToolHandler } from "@codespar/agent-core";
+import { AGREEMENTS, agreementByAlias, formatBRL, formatDate } from "../agreements.js";
+import type { Envelope } from "../envelope.js";
+
+interface ChargeInput {
+  action?: unknown;
+  agreement?: unknown;
+  instalments?: unknown;
+  total_minor?: unknown;
+  execution_id?: unknown;
+}
+
+export function makeHandlers(envelope: Envelope): Record<string, ToolHandler> {
+  const listAgreements: ToolHandler = async (_input, ctx) => {
+    const settled = ctx.engine.list({ state: "settled" });
+    const open = ctx.engine.list({ state: "executing" });
+    const settledAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
+    const issuedAliases = new Set(open.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
+    return {
+      agreements: AGREEMENTS.map((a) => ({
+        alias: a.alias,
+        debtor_first_name: a.first_name,
+        principal_minor: a.principal_minor,
+        principal: formatBRL(a.principal_minor),
+        origin: a.origin,
+        opened_at: a.opened_at,
+        status: settledAliases.has(a.alias) ? "quitado" : issuedAliases.has(a.alias) ? "cobranca emitida, aguardando pagamento" : "em aberto",
+      })),
+      envelope: {
+        max_discount_pct: envelope.max_discount_pct,
+        max_instalments: envelope.max_instalments,
+        due_date_window_days: envelope.due_date_window_days,
+        min_instalment_minor: envelope.min_instalment_minor,
+        collection_hours: envelope.collection_hours,
+      },
+    };
+  };
+
+  const codesparCharge: ToolHandler = async (raw, ctx) => {
+    const input = raw as ChargeInput;
+    const action = input.action ?? "create";
+    if (action === "status") {
+      if (typeof input.execution_id !== "string") throw new Error("codespar_charge: execution_id is required for action=status");
+      const execution = ctx.engine.get(input.execution_id);
+      if (!execution) return { found: false, message: "no execution with that id in this run" };
+      return { found: true, ...describe(execution) };
+    }
+    if (action !== "create") throw new Error(`codespar_charge: unsupported action ${String(action)}; this agent only creates and reads receivables`);
+    if (typeof input.agreement !== "string" || !input.agreement.trim()) throw new Error("codespar_charge: agreement must be an agreement alias from list_agreements");
+    if (!Array.isArray(input.instalments) || input.instalments.length === 0) throw new Error("codespar_charge: instalments must be a non-empty array");
+    const alias = input.agreement.trim().toLowerCase();
+    const agreement = agreementByAlias(alias);
+    const count = input.instalments.length;
+    const items = input.instalments.map((entry, i) => {
+      const it = entry as { amount_minor?: unknown; due_date?: unknown };
+      if (typeof it.amount_minor !== "number" || !Number.isInteger(it.amount_minor) || it.amount_minor <= 0) throw new Error(`codespar_charge: instalments[${i}].amount_minor must be a positive integer`);
+      if (typeof it.due_date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(it.due_date)) throw new Error(`codespar_charge: instalments[${i}].due_date must be YYYY-MM-DD`);
+      return {
+        payee: alias,
+        amount: it.amount_minor,
+        due_date: it.due_date,
+        description: `${agreement ? `Acordo ${agreement.alias.replace("acordo-", "#")}` : `Acordo ${alias}`} - parcela ${i + 1}/${count}`,
+      };
+    });
+    const claimed = typeof input.total_minor === "number" ? { claimed_total: input.total_minor } : {};
+
+    const draft = await ctx.engine.draft({ items, ...claimed });
+    if (!draft.ok) return { status: "refused", reason: draft.reason, message: draft.message, issued: false, paid: false };
+    const execution = await ctx.onExecution(draft.execution);
+    return describe(execution);
+  };
+
+  return { codespar_charge: codesparCharge, list_agreements: listAgreements };
+}
+
+function describe(execution: import("@codespar/agent-core").Execution) {
+  const charges = execution.outcomes.map((o) => ({
+    instalment: o.index + 1,
+    charge_id: o.transaction_id ?? null,
+    status: o.status,
+    ...(o.instrument ? { payable: o.instrument.payable, pix_copy_paste: o.instrument.pix_copy_paste, boleto_bank_line: o.instrument.boleto_bank_line, due_date: o.instrument.due_date } : {}),
+    ...(o.code ? { code: o.code } : {}),
+  }));
+  return {
+    status: execution.state,
+    execution_id: execution.id,
+    total_minor: execution.total,
+    total: formatBRL(execution.total),
+    instalments: execution.items.map((i, n) => ({ instalment: n + 1, amount: formatBRL(i.amount), due_date: i.due_date ? formatDate(i.due_date) : null })),
+    ...(execution.reason ? { reason: execution.reason, detail: execution.detail } : {}),
+    ...(execution.escalation ? { escalated_by: execution.escalation.trigger } : {}),
+    charges,
+    issued: charges.length > 0 && charges.every((c) => c.status !== "failed"),
+    paid: execution.state === "settled",
+    expired: execution.state === "failed" && execution.reason === "charge_expired",
+  };
+}

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

@@ -0,0 +1,94 @@
+/**
+ * How the cycle closes without a webhook: the kit LOOKS at the receivable
+ * (`GET /v1/charges/{id}` through the rail's `lookup`, the stub's fixture
+ * offline) until the payer acted or the wait ran out. Each look is a
+ * `reconcile`, which is read-only on the rail and never re-issues. The
+ * instrument (QR, copy-and-paste, bank line) is presented the first time a
+ * look finds it payable; the debtor is told the outcome once, whatever the
+ * number of looks or events that carried it.
+ */
+import type { ChargeInstrument, Execution, ExecutionEngine } from "@codespar/agent-core";
+import type { SandboxPayer } from "./setup.js";
+
+export interface PollHooks {
+  /** A receivable became payable: show the payer how to pay. Called once per instalment. */
+  onInstrument?: (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument) => void;
+  /** The execution reached a terminal state. Called once. */
+  onClosed?: (execution: Execution) => void;
+  /** Called before each look after the first. */
+  onWait?: (execution: Execution, round: number) => void;
+}
+
+export interface PollOptions extends PollHooks {
+  intervalMs: number;
+  /** Wall-clock budget for the wait. */
+  timeoutMs: number;
+  /** Cap on looks, for a zero-interval (stub) loop: the fixture payer acts within two looks; a third proves nothing changes. */
+  maxRounds?: number;
+  /** When set, the payer plays as soon as every instalment is payable (a scenario, `--simulate-payer`). */
+  payer?: SandboxPayer | undefined;
+  clock?: () => Date;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface PollResult {
+  execution: Execution;
+  rounds: number;
+  /** Seconds from the first look to the terminal state, or to the end of the wait. */
+  seconds: number;
+  timed_out: boolean;
+  payer_calls: string[];
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * Presents each instalment once, records `message.debtor` once per outcome,
+ * and returns when the execution is terminal or the wait is over. Safe to
+ * call again on the same execution (a restart): what was already shown is
+ * remembered in the state.db cursor table, not in memory.
+ */
+export async function pollUntilClosed(engine: ExecutionEngine, executionId: string, options: PollOptions): Promise<PollResult> {
+  const clock = options.clock ?? (() => new Date());
+  const sleep = options.sleep ?? defaultSleep;
+  const startedWall = Date.now();
+  const started = clock().getTime();
+  const maxRounds = options.maxRounds ?? (options.intervalMs === 0 ? 3 : Number.POSITIVE_INFINITY);
+  const payerCalls: string[] = [];
+  let execution = engine.get(executionId);
+  if (!execution) throw new Error(`unknown execution ${executionId}`);
+  let rounds = 0;
+  let paidRequested = false;
+
+  const present = (e: Execution) => {
+    for (const outcome of e.outcomes) {
+      if (outcome.status !== "accepted" || !outcome.instrument?.payable || !outcome.transaction_id) continue;
+      if (!engine.markShown(e.id, outcome.attempt_id)) continue;
+      options.onInstrument?.(e, outcome.index + 1, outcome.transaction_id, outcome.instrument);
+    }
+  };
+
+  present(execution);
+  while (execution.state === "executing") {
+    if (rounds > 0) {
+      // A zero-interval loop (the stub) is bounded by looks; a real one by the wall clock.
+      if (rounds >= maxRounds || (options.intervalMs > 0 && Date.now() - startedWall >= options.timeoutMs)) break;
+      options.onWait?.(execution, rounds);
+      if (options.intervalMs > 0) await sleep(options.intervalMs);
+    }
+    rounds += 1;
+    execution = await engine.reconcile(execution.id);
+    present(execution);
+    const payable = execution.outcomes.filter((o) => o.status === "accepted" && o.instrument?.payable && o.transaction_id);
+    if (options.payer && !paidRequested && execution.state === "executing" && payable.length > 0 && payable.length === execution.outcomes.filter((o) => o.status === "accepted").length) {
+      paidRequested = true;
+      for (const outcome of payable) {
+        const result = await options.payer.pay(outcome.transaction_id!, outcome.attempt_id);
+        payerCalls.push(result.detail);
+        engine.note("sandbox_payer", execution.id, { charge_id: outcome.transaction_id, ok: result.ok, detail: result.detail });
+      }
+    }
+  }
+  if (execution.state !== "executing") options.onClosed?.(execution);
+  return { execution, rounds, seconds: Math.round(((clock().getTime() - started) / 1000) * 10) / 10, timed_out: execution.state === "executing", payer_calls: payerCalls };
+}