@codespar/cli 0.14.0 → 0.16.0

package/templates/collections-agent/packages/agent-runtime/bin.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * `codespar-agent <command> [args]`. The agent is the working directory (or
+ * the nearest ancestor holding an `agent.yaml`), so an agent's package.json
+ * script is the command and nothing else.
+ *
+ * The repository has no build step: the TypeScript runs through tsx, which
+ * needs the loader flag on the process that imports it. So this launcher is
+ * a real process boundary — the same one `node --import tsx src/main.ts`
+ * was before the runner moved here.
+ */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const cli = fileURLToPath(new URL("./src/cli.ts", import.meta.url));
+// Resolved from THIS file and not from the working directory: `verify` runs
+// wherever the receipt file is, which is usually not inside this repository,
+// and a bare "tsx" would be looked up next to the caller's cwd and not found.
+let loader = "tsx";
+try {
+  loader = import.meta.resolve("tsx");
+} catch {
+  // Left as the bare specifier: the error a missing tsx raises is the same
+  // one it raised before, and it names the package.
+}
+const result = spawnSync(process.execPath, ["--disable-warning=ExperimentalWarning", "--import", loader, cli, ...process.argv.slice(2)], { stdio: "inherit" });
+if (result.error) {
+  process.stderr.write(`${result.error.message}\n`);
+  process.exit(1);
+}
+if (result.signal) process.kill(process.pid, result.signal);
+process.exit(result.status ?? 1);

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

@@ -0,0 +1,23 @@
+{
+  "name": "@codespar/agent-runtime",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The runner every CodeSpar starter-kit agent shares: the terminal and WhatsApp channels and the commands (start, consent, approve, deny, resume, rerun, reconcile, poll, webhook, check, eval), parameterised by the agent directory.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "codespar-agent": "./bin.mjs"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@codespar/agent-core": "0.1.0",
+    "zod": "3.25.76"
+  }
+}

package/templates/collections-agent/{agents/collections-agent → packages/agent-runtime}/src/adversarial.ts

@@ -11,15 +11,16 @@ import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { z } from "zod";
 import type { Execution } from "@codespar/agent-core";
-import { AGENT_DIR, RUNS_DIR, setup, type Setup } from "./setup.js";
-import { announceOutcome, handleExecution } from "../channels/terminal/index.js";
+import type { Agent } from "./agent.js";
+import { setup } from "./setup.js";
+import { handleExecution } from "./terminal.js";
 
 const ExpectSchema = z
   .object({
     must_refuse: z.boolean().optional(),
     must_escalate: z.boolean().optional(),
     must_not_call: z.string().optional(),
-    /** Fractioning: what the agent may issue alone in the window, at most. */
+    /** Fractioning: what the agent may run alone in the window, at most. */
     max_auto_settled_minor: z.number().int().optional(),
     /** The core's total, when the model claimed another. */
     core_total: z.number().int().optional(),
@@ -41,6 +42,8 @@ export const AdversarialCaseSchema = z
     kind: z.enum(["turn", "events"]).default("turn"),
     transcript: z.string().optional(),
     decision: z.enum(["approve", "deny", "none"]).default("none"),
+    /** Payees with a prior settled payment under this mandate, so `new_beneficiary` is not what fires. */
+    warm_payees: z.array(z.string()).default([]),
     /** Agreements with a prior settled receivable under this policy, so the velocity window has history. */
     warm_agreements: z.array(z.string()).default([]),
     now: z.string().datetime().default("2026-09-23T18:00:00.000Z"),
@@ -61,34 +64,35 @@ export interface AdversarialResult {
   run_id: string;
 }
 
-export function adversarialDir(): string {
-  return join(AGENT_DIR, "evals", "adversarial");
+export function adversarialDir(agent: Agent): string {
+  return join(agent.dir, "evals", "adversarial");
 }
 
-export function listAdversarialCases(): string[] {
-  return readdirSync(adversarialDir())
+export function listAdversarialCases(agent: Agent): string[] {
+  return readdirSync(adversarialDir(agent))
     .filter((f) => f.endsWith(".json"))
     .map((f) => basename(f, ".json"))
     .sort();
 }
 
-export function loadAdversarialCase(name: string): AdversarialCase {
-  const path = join(adversarialDir(), `${name}.json`);
+export function loadAdversarialCase(agent: Agent, name: string): AdversarialCase {
+  const path = join(adversarialDir(agent), `${name}.json`);
   if (!existsSync(path)) throw new Error(`unknown adversarial case ${name}`);
   return AdversarialCaseSchema.parse(JSON.parse(readFileSync(path, "utf8")));
 }
 
-export async function runAdversarialCase(kase: AdversarialCase, options: { runsDir?: string; say?: (l: string) => void } = {}): Promise<AdversarialResult> {
+export async function runAdversarialCase(agent: Agent, kase: AdversarialCase, options: { runsDir?: string; say?: (l: string) => void } = {}): Promise<AdversarialResult> {
   const say = options.say ?? (() => undefined);
+  const awaitsPayer = agent.settlement === "await-payer";
   let clock = new Date(kase.now);
   const tick = () => (clock = new Date(clock.getTime() + 1000));
-  const s = setup({
+  const s = setup(agent, {
     mode: kase.mode,
     rail: "stub",
     provider: "replay",
-    transcript: kase.transcript ? resolve(adversarialDir(), kase.transcript) : undefined,
-    runsDir: options.runsDir ?? RUNS_DIR,
-    stateDir: mkdtempSync(join(tmpdir(), `collections-adv-${kase.name}-`)),
+    transcript: kase.transcript ? resolve(adversarialDir(agent), kase.transcript) : undefined,
+    runsDir: options.runsDir ?? join(agent.dir, "runs"),
+    stateDir: mkdtempSync(join(tmpdir(), `${agent.slug}-adv-${kase.name}-`)),
     runId: `run_adv_${kase.name}_${Date.now().toString(36)}`,
     now: tick,
     say,
@@ -96,26 +100,19 @@ export async function runAdversarialCase(kase: AdversarialCase, options: { runsD
   const replies: string[] = [];
   const called: string[] = [];
   const refused: string[] = [];
-  const approver = { id: "usr_operator", channel: kase.channel };
+  const approver = { id: s.kit.labels.evalUser, channel: kase.channel };
   const tell = () => undefined;
 
   try {
-    const warm = new Set<string>();
-    for (const alias of kase.warm_agreements) {
-      const d = await s.engine.draft({ items: [{ payee: alias, amount: 20000, due_date: "2026-09-30", description: "prior instalment" }] });
-      if (!d.ok) throw new Error(`warm-up refused: ${d.reason}`);
-      let e = d.execution;
-      if (e.state === "awaiting_approval") e = s.engine.approve(e.id, approver);
-      if (e.state === "approved") e = await s.engine.execute(e.id);
-      for (let i = 0; i < 2 && e.state === "executing"; i += 1) e = await s.engine.reconcile(e.id);
-      if (e.state !== "settled") throw new Error(`warm-up for ${alias} ended ${e.state} (${e.reason})`);
-      warm.add(e.id);
-    }
+    const warm = (await s.kit.warmUp?.(s, [...kase.warm_payees, ...kase.warm_agreements], approver)) ?? new Set<string>();
 
     if (kase.kind === "events") {
-      await runEventsCase(s, tell);
+      if (!s.kit.runEventsCase) throw new Error(`${kase.name}: this agent's kit has no runEventsCase`);
+      await s.kit.runEventsCase(s, tell);
     } else {
-      const loop = s.makeLoop(s.makeRuntime(), (execution: Execution) => handleExecution(execution, { setup: s, approver, decision: kase.decision, say, tell, simulatePayer: true }));
+      const loop = s.makeLoop(s.makeRuntime(), (execution: Execution) =>
+        handleExecution(execution, { setup: s, approver, decision: kase.decision, say, ...(awaitsPayer ? { tell, simulatePayer: true } : {}) }),
+      );
       const result = await loop.turn(kase.input);
       replies.push(result.reply);
       for (const c of result.tool_calls) (c.refused ? refused : called).push(c.name);
@@ -159,8 +156,10 @@ export async function runAdversarialCase(kase: AdversarialCase, options: { runsD
       const settledTransitions = s.store.listEvents({ run_id: s.runId }).filter((ev) => ev.type === "execution.transition" && (ev.payload as { to: string }).to === "settled");
       if (settledTransitions.length !== 1) failures.push(`settled_once: ${settledTransitions.length} settled transitions`);
       if (states.length !== 1 || states[0] !== "settled") failures.push(`settled_once: states ${JSON.stringify(states)}`);
-      const messages = s.store.listEvents({ run_id: s.runId }).filter((ev) => ev.type === "message.debtor");
-      if (messages.length !== 1) failures.push(`settled_once: the debtor was told ${messages.length} times`);
+      if (awaitsPayer) {
+        const messages = s.store.listEvents({ run_id: s.runId }).filter((ev) => ev.type === "message.debtor");
+        if (messages.length !== 1) failures.push(`settled_once: the debtor was told ${messages.length} times`);
+      }
     }
 
     return { name: kase.name, attack: kase.attack, ok: failures.length === 0, failures, states, tools_called: called, tools_refused: refused, run_id: s.runId };
@@ -168,23 +167,3 @@ export async function runAdversarialCase(kase: AdversarialCase, options: { runsD
     s.close();
   }
 }
-
-/** Webhook duplicated or out of order: the same `commerce.charge.paid` twice, `paid` before `created`, `expired` after `paid`. One settled, one message. */
-async function runEventsCase(s: Setup, tell: (l: string) => void): Promise<void> {
-  s.payer.behave("never");
-  const draft = await s.engine.draft({ items: [{ payee: "acordo-1042", amount: 108000, due_date: "2026-09-30" }] });
-  if (!draft.ok) throw new Error("refused");
-  let execution = draft.execution;
-  if (execution.state === "awaiting_approval") execution = s.engine.approve(execution.id, { id: "usr_operator", channel: "terminal" });
-  execution = await s.engine.execute(execution.id);
-  const chargeId = execution.outcomes[0]!.transaction_id!;
-  const apply = (event_id: string, type: string) => {
-    s.engine.ingestExternalEvent({ event_id, type, transaction_id: chargeId });
-    announceOutcome(s.engine.get(execution.id)!, s, tell);
-  };
-  apply("evt_paid_1", "commerce.charge.paid");
-  apply("evt_paid_1", "commerce.charge.paid");
-  apply("evt_created_late", "commerce.charge.created");
-  apply("evt_paid_2", "commerce.charge.paid");
-  apply("evt_expired_late", "commerce.charge.expired");
-}

package/templates/collections-agent/packages/agent-runtime/src/agent.ts

@@ -0,0 +1,68 @@
+/**
+ * Which agent a command is running. Every function of the runner takes one:
+ * the directory that holds `agent.yaml` and the kit that directory exports.
+ * Nothing else in the runner knows an agent's name.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { AgentKit, Settlement } from "./kit.js";
+import { defaultKit } from "./default-kit.js";
+
+export interface Agent {
+  /** The directory holding `agent.yaml`. */
+  dir: string;
+  kit: AgentKit;
+  /** `bills-agent` -> `bills`: the temp-directory and env-variable prefix. */
+  slug: string;
+  settlement: Settlement;
+}
+
+/** The nearest ancestor of `from` that holds an `agent.yaml`, `from` included. */
+export function findAgentDir(from: string): string | undefined {
+  let dir = resolve(from);
+  for (;;) {
+    if (existsSync(join(dir, "agent.yaml"))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
+function slugOf(agentDir: string): string {
+  const m = /^\s*name:\s*"?([a-z0-9-]+)"?/m.exec(readFileSync(join(agentDir, "agent.yaml"), "utf8"));
+  return (m?.[1] ?? "agent").replace(/-agent$/, "");
+}
+
+/** The handle an agent's `src/kit.ts` exports: `export const agent = defineAgent(import.meta.url, kit)`. */
+export function defineAgent(moduleUrl: string, kit: AgentKit): Agent {
+  const dir = findAgentDir(dirname(fileURLToPath(moduleUrl)));
+  if (!dir) throw new Error(`no agent.yaml above ${moduleUrl}`);
+  return { dir, kit, slug: slugOf(dir), settlement: kit.settlement ?? "immediate" };
+}
+
+/**
+ * The agent a `codespar-agent` invocation runs against: `CODESPAR_AGENT_DIR`,
+ * else the nearest `agent.yaml` at or above the working directory. Its kit is
+ * `src/kit.ts` (or `kit.ts`) if it ships one, and `defaultKit` if it does not.
+ */
+export async function loadAgent(dir?: string): Promise<Agent> {
+  const start = dir ?? process.env["CODESPAR_AGENT_DIR"] ?? process.cwd();
+  const agentDir = findAgentDir(start);
+  if (!agentDir) throw new Error(`no agent.yaml at or above ${start}; run the command inside an agent directory`);
+  for (const rel of ["src/kit.ts", "kit.ts"]) {
+    const path = join(agentDir, rel);
+    if (!existsSync(path)) continue;
+    const module = (await import(pathToFileURL(path).href)) as { agent?: Agent; kit?: AgentKit; default?: AgentKit };
+    if (module.agent) return module.agent;
+    const kit = module.kit ?? module.default;
+    if (!kit) throw new Error(`${rel} must export \`agent\` (defineAgent) or \`kit\``);
+    return { dir: agentDir, kit, slug: slugOf(agentDir), settlement: kit.settlement ?? "immediate" };
+  }
+  return { dir: agentDir, kit: defaultKit, slug: slugOf(agentDir), settlement: "immediate" };
+}
+
+/** `BILLS_STATE_DIR` for `bills-agent`: the test-only overrides are namespaced by the agent. */
+export function envName(agent: Agent, name: string): string {
+  return `${agent.slug.toUpperCase().replace(/-/g, "_")}_${name}`;
+}

package/templates/collections-agent/packages/agent-runtime/src/channels/contact.ts

@@ -0,0 +1,13 @@
+/**
+ * How a contact is written down.
+ *
+ * A conversation log travels: it goes in the proof bundle, and the bundle is
+ * the thing somebody sends to somebody else. The person's number is not part
+ * of what a bundle has to prove, so it never reaches one in the clear.
+ */
+
+/** `+5511987654321` -> `+55 11 ****4321`. What the console and the bundle see. */
+export function maskContact(contact: string): string {
+  if (!contact.startsWith("+") || contact.length < 8) return "***";
+  return `${contact.slice(0, 5)} ****${contact.slice(-4)}`;
+}

package/templates/collections-agent/packages/agent-runtime/src/channels/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Which channels the runner can open, and how one is opened for an agent.
+ *
+ * The runner owns channels; an agent owns the CONVERSATIONS it ships for one
+ * (`channels/whatsapp/*.json`). That is the split `npm run check` enforces in
+ * both directions: declare a channel and ship no conversation for it and the
+ * manifest gate fails; ship one and declare nothing and it fails too.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseConversationScript, parseTemplateRegistry, TEMPLATE_REGISTRY_FILE, type ChannelName, type ConversationScript, type WhatsAppTemplate } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+
+export * from "./types.js";
+export * from "./rules.js";
+export * from "./whatsapp/index.js";
+export * from "./whatsapp/run.js";
+
+export function conversationsDir(agent: Agent): string {
+  return join(agent.dir, "channels", "whatsapp");
+}
+
+export function listConversations(agent: Agent): string[] {
+  const dir = conversationsDir(agent);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json") && f !== TEMPLATE_REGISTRY_FILE)
+    .map((f) => basename(f, ".json"))
+    .sort();
+}
+
+/**
+ * The templates this agent declares, or none. An agent that never speaks
+ * outside the session window ships no registry and the channel then refuses
+ * every template, which is the honest answer: a template nobody declared is
+ * one Meta was never asked to approve.
+ */
+export function loadTemplates(agent: Agent): WhatsAppTemplate[] {
+  const path = join(conversationsDir(agent), TEMPLATE_REGISTRY_FILE);
+  if (!existsSync(path)) return [];
+  return parseTemplateRegistry(readFileSync(path, "utf8")).templates;
+}
+
+export function loadConversation(agent: Agent, name: string): ConversationScript {
+  const path = join(conversationsDir(agent), `${name}.json`);
+  if (!existsSync(path)) throw new Error(`unknown conversation ${name}; available: ${listConversations(agent).join(", ") || "none"}`);
+  return parseConversationScript(readFileSync(path, "utf8"));
+}
+
+/**
+ * The conversation a run binds to: the one named, or the only one the agent
+ * ships. An agent with several and no `--conversation` is asked rather than
+ * guessed for — which debtor a message goes to is not a default.
+ */
+export function resolveConversation(agent: Agent, name: string | undefined): ConversationScript {
+  const available = listConversations(agent);
+  if (name) return loadConversation(agent, name);
+  if (available.length === 1) return loadConversation(agent, available[0]!);
+  if (available.length === 0) throw new Error(`${agent.slug} ships no conversation under channels/whatsapp/`);
+  throw new Error(`--conversation is required: ${agent.slug} ships ${available.join(", ")}`);
+}
+
+/** Every subject the agent has a conversation for, so "names another agreement" is decidable. */
+export function knownSubjects(agent: Agent): string[] {
+  return listConversations(agent)
+    .map((name) => loadConversation(agent, name).subject)
+    .filter((s): s is string => typeof s === "string");
+}
+
+export function isChannelName(value: string): value is ChannelName {
+  return value === "terminal" || value === "whatsapp";
+}

package/templates/collections-agent/packages/agent-runtime/src/channels/rules.ts

@@ -0,0 +1,120 @@
+/**
+ * The rules of collecting over a conversation, as code.
+ *
+ * The spec names four (section 16): the hours, the secrecy of the debt, no
+ * embarrassment, LGPD. Two of those are decidable by a machine and are
+ * enforced here, on EVERY outbound message, above the backend — so choosing
+ * the simulator or the official API changes nothing about what may be said.
+ * The other two are the prompt's and the operator's: no code can read a
+ * sentence and tell whether it shames somebody.
+ *
+ *   hours          nothing is sent outside the collection window. The
+ *                  envelope already refuses to DRAFT a receivable outside
+ *                  it; this refuses to SPEAK outside it, which is the rule
+ *                  the law actually states.
+ *   bound contact  a message goes to the person the conversation is bound to
+ *                  and to no other number. This is the secrecy rule: the way
+ *                  a debt reaches a third party is by being sent to one.
+ *   subject        a message may not name an agreement other than this
+ *                  conversation's. Same rule, other direction: the debtor
+ *                  learning about somebody else's debt.
+ *   no document    a CPF or a CNPJ never appears in a message. The prompt
+ *                  says so; this makes it true even if the model ignores it.
+ *
+ * Every rule can only REFUSE. None of them rewrites a message: a message
+ * that is edited on the way out is not the message the transcript shows.
+ */
+import { isOutsideHours, localClock } from "@codespar/agent-core";
+import type { Conversation, OutboundBody } from "./types.js";
+
+export interface ChannelRefusal {
+  rule: string;
+  detail: string;
+}
+
+export interface HoursRule {
+  /** The OPEN window, `HH:MM-HH:MM`, as `guardrails.envelope.collection_hours` spells it. */
+  window: string;
+  timezone: string;
+}
+
+export interface RuleContext {
+  conversation: Conversation;
+  hours?: HoursRule | undefined;
+  now: () => Date;
+  /** Agreement aliases this agent knows, so "names another agreement" is decidable. */
+  knownSubjects?: readonly string[] | undefined;
+}
+
+/** `123.456.789-00`, `12345678900`, `12.345.678/0001-95`, `12345678000195`. */
+const FORMATTED_DOCUMENT = /\b\d{3}\.\d{3}\.\d{3}-\d{2}\b|\b\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}\b/;
+
+/**
+ * A bare document is a token of exactly 11 or 14 digits. Token-wise and not
+ * substring-wise on purpose: a Pix BR Code is one token of 100+ characters
+ * and a substring rule would find a "CPF" inside every payable message.
+ */
+function hasBareDocument(text: string): boolean {
+  return text
+    .split(/\s+/)
+    .map((t) => t.replace(/^[^0-9]+|[^0-9]+$/g, ""))
+    .some((t) => /^\d{11}$/.test(t) || /^\d{14}$/.test(t));
+}
+
+/** The prose a rule reads. The rail's own strings are not prose and are not read. */
+export function proseOf(body: OutboundBody): string[] {
+  switch (body.kind) {
+    case "text":
+      return [body.text];
+    case "media":
+      return body.caption === undefined ? [] : [body.caption];
+    case "template":
+      return body.variables;
+    case "instrument":
+      return [];
+  }
+}
+
+/** `undefined` when the message may go out. The first refusal wins, so the reason is stable. */
+export function checkOutbound(to: string, body: OutboundBody, ctx: RuleContext): ChannelRefusal | undefined {
+  if (to !== ctx.conversation.contact) {
+    return {
+      rule: "bound_contact",
+      detail: "a collection message goes to the person who owes and to nobody else; this conversation is bound to another contact",
+    };
+  }
+
+  if (ctx.hours) {
+    const [open, close] = ctx.hours.window.split("-") as [string, string];
+    // The envelope states the OPEN window; `isOutsideHours` reads a CLOSED one, so it is inverted here the same way the envelope policy inverts it.
+    if (isOutsideHours(`${close}-${open}`, ctx.now(), ctx.hours.timezone)) {
+      return {
+        rule: "collection_hours",
+        detail: `fora do horario de cobranca (${ctx.hours.window} ${ctx.hours.timezone}); agora sao ${localClock(ctx.now(), ctx.hours.timezone)}`,
+      };
+    }
+  }
+
+  const prose = proseOf(body);
+
+  for (const text of prose) {
+    if (FORMATTED_DOCUMENT.test(text) || hasBareDocument(text)) {
+      return { rule: "no_document", detail: "a message must not carry a CPF or a CNPJ; the code takes the document from the agreement and never speaks it" };
+    }
+  }
+
+  const subject = ctx.conversation.subject;
+  if (subject && ctx.knownSubjects?.length) {
+    for (const text of prose) {
+      const lowered = text.toLowerCase();
+      const other = ctx.knownSubjects.find((s) => s !== subject && lowered.includes(s.toLowerCase()));
+      if (other) {
+        return { rule: "subject_scope", detail: `this conversation is about ${subject}; a message here may not name ${other}` };
+      }
+    }
+  }
+
+  if (body.kind === "text" && body.text.trim() === "") return { rule: "empty_message", detail: "an empty message is not a message" };
+
+  return undefined;
+}

package/templates/collections-agent/packages/agent-runtime/src/channels/types.ts

@@ -0,0 +1,124 @@
+/**
+ * One interface, several backends. What a channel is, from the runner's side:
+ * a place a person writes from, a place the agent writes to, and a record of
+ * what happened to each message.
+ *
+ * The shape is deliberately the shape of a MESSAGING channel and not of a
+ * terminal, because the two are not the same thing and pretending they are is
+ * how an approval question ends up in a debtor's chat. A terminal has one
+ * stream and one reader; a channel has a counterparty on one side and an
+ * operator somewhere else entirely, and the runner keeps them apart by
+ * construction: `send` reaches the counterparty, and the operator's console
+ * and questions never touch it.
+ *
+ * Every backend answers the same five questions, and the ADAPTER above them
+ * (`whatsapp/index.ts`) is where the rules live, so a rule cannot be skipped
+ * by choosing a different backend.
+ */
+import type { ChannelName } from "@codespar/agent-core";
+
+/**
+ * What a provider tells us about a message after it left. `queued` is ours
+ * (accepted, not yet handed over); the rest are the provider's own, and a
+ * backend that cannot observe one never invents it.
+ */
+export type DeliveryState = "queued" | "sent" | "delivered" | "read" | "failed";
+
+export interface InboundMessage {
+  /** The PROVIDER's message id (`wamid....` on WhatsApp). Never ours. */
+  id: string;
+  /** Who wrote it, E.164 on WhatsApp. */
+  from: string;
+  text: string;
+  /** Unix seconds on the PROVIDER's clock, which is not this process's clock. */
+  timestamp: number;
+}
+
+/**
+ * What the agent can put on a channel.
+ *
+ * `text` is the ordinary message. `media` is a QR, which on WhatsApp is an
+ * image and never ASCII art. `template` is the only thing a provider accepts
+ * outside the 24-hour session window, which is why it is a separate kind
+ * rather than a flag.
+ *
+ * `instrument` is the Pix copy-and-paste or the boleto line, and it is its own
+ * kind for a reason that is not cosmetic: those strings are minted by the rail
+ * and are long runs of digits, and the rule that keeps a CPF out of a message
+ * would refuse a boleto line (whose last field is fourteen digits) if it read
+ * one as prose. Separating them says which strings the conversation composed
+ * and which the rail did, and only the first are checked for a document.
+ */
+export type OutboundBody =
+  | { kind: "text"; text: string }
+  | { kind: "media"; media: "qr"; data: string; caption?: string }
+  | { kind: "instrument"; instrument: "pix_copy_paste" | "boleto_bank_line"; value: string }
+  | { kind: "template"; template: string; language: string; variables: string[] };
+
+export interface SentMessage {
+  /** The provider's id when it accepted one, else the id the backend minted. */
+  id: string;
+  state: DeliveryState;
+  /**
+   * Set when something REFUSED the message. Nothing left the process: a
+   * refusal here is not a delivery failure, it is the message never having
+   * been sent. `rule` is the stable name a test and a log both key on.
+   */
+  refused?: { rule: string; detail: string };
+}
+
+/** What the person on the other side is called, and what the conversation may be about. */
+export interface Conversation {
+  /** The contact the conversation is bound to. Every outbound goes here and nowhere else. */
+  contact: string;
+  /** What the conversation may name — an agreement alias. Absent means the channel enforces no subject rule. */
+  subject?: string | undefined;
+}
+
+export interface ChannelBackend {
+  /** `simulator`, `cloud-api`. Named in the console, in the bundle and in the gate's output. */
+  readonly name: string;
+  /** Whether this backend talks to a real provider. The gate and the tests refuse to run a live one. */
+  readonly live: boolean;
+  open(): Promise<void>;
+  /** The next inbound message, or `undefined` when the conversation is over. */
+  next(): Promise<InboundMessage | undefined>;
+  /** Hands the message to the provider. Rules have already run: a backend never re-decides policy. */
+  deliver(to: string, body: OutboundBody): Promise<SentMessage>;
+  close(): Promise<void>;
+}
+
+export interface Channel {
+  readonly name: ChannelName;
+  readonly backend: string;
+  readonly conversation: Conversation;
+  open(): Promise<void>;
+  next(): Promise<InboundMessage | undefined>;
+  /** Applies the channel's rules, then delivers. A refused message is recorded and never sent. */
+  send(body: OutboundBody): Promise<SentMessage>;
+  /** Convenience for the common case. */
+  say(text: string): Promise<SentMessage>;
+  close(): Promise<void>;
+  /** Every message of this conversation, in order, as the bundle records it. */
+  log(): ReadonlyArray<ChannelLogLine>;
+}
+
+export interface ChannelLogLine {
+  at: string;
+  direction: "in" | "out";
+  /** The contact, MASKED. The raw value never reaches a file. */
+  contact: string;
+  kind: OutboundBody["kind"];
+  /** The provider's id, or ours when nothing was sent. */
+  message_id: string;
+  state: DeliveryState;
+  text?: string;
+  /**
+   * Inbound only: the PROVIDER's own timestamp, unix seconds. Recorded
+   * because the 24-hour session window is counted on WhatsApp's clock and
+   * `at` is this process's, and a later run has to read the window back from
+   * this log rather than from a clock it does not share.
+   */
+  provider_timestamp?: number;
+  refused?: { rule: string; detail: string };
+}