@codespar/cli 0.14.0 → 0.16.0

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

@@ -2,7 +2,8 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "../src/scenarios.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
 
 const runsDir = mkdtempSync(join(tmpdir(), "bills-runs-"));
 
@@ -10,14 +11,14 @@ describe("section 12: scenario packs, on the replay provider", () => {
   const required = ["happy-path", "cap-exceeded", "beneficiary-not-allowed", "prompt-injection", "escalated-above-threshold", "mandate-revoked"];
 
   it("ships every scenario the spec asks for", () => {
-    for (const name of required) expect(listScenarios()).toContain(name);
+    for (const name of required) expect(listScenarios(agent)).toContain(name);
   });
 
   for (const name of required) {
-    const scenario = loadScenario(name);
+    const scenario = loadScenario(agent, name);
     for (const mode of scenario.modes) {
       it(`${name} [${mode}] ends in the states the pack declares`, async () => {
-        const run = await runScenario(scenario, { mode, runsDir });
+        const run = await runScenario(agent, scenario, { mode, runsDir });
         const check = checkScenario(scenario, run);
         expect(check.failures).toEqual([]);
         expect(check.ok).toBe(true);
@@ -36,9 +37,9 @@ describe("section 12: scenario packs, on the replay provider", () => {
   }
 
   it("happy-path: the same trail and the same receipts in human and in mandate", async () => {
-    const scenario = loadScenario("happy-path");
-    const human = await runScenario(scenario, { mode: "human", runsDir });
-    const mandate = await runScenario(scenario, { mode: "mandate", runsDir });
+    const scenario = loadScenario(agent, "happy-path");
+    const human = await runScenario(agent, scenario, { mode: "human", runsDir });
+    const mandate = await runScenario(agent, scenario, { mode: "mandate", runsDir });
     expect(human.executions.map((e) => e.trail)).toEqual(mandate.executions.map((e) => e.trail));
     expect(normalizeReceipts(human)).toEqual(normalizeReceipts(mandate));
     // In human, the artifact is a person's; in mandate the person still decided because the amount escalated.
@@ -51,9 +52,9 @@ describe("section 12: scenario packs, on the replay provider", () => {
 
   it("nothing reaches executing without an approval artifact carrying its items_hash", async () => {
     for (const name of required) {
-      const scenario = loadScenario(name);
+      const scenario = loadScenario(agent, name);
       for (const mode of scenario.modes) {
-        const run = await runScenario(scenario, { mode, runsDir });
+        const run = await runScenario(agent, scenario, { mode, runsDir });
         const approvalPath = join(run.bundle_dir, "approval.json");
         const artifacts = existsSync(approvalPath) ? (JSON.parse(readFileSync(approvalPath, "utf8")) as Array<{ execution_id: string; items_hash: string }>) : [];
         for (const e of run.executions) {

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

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

package/templates/bills-agent/package.json

@@ -7,20 +7,23 @@
   "type": "module",
   "workspaces": [
     "packages/agent-core",
+    "packages/agent-runtime",
     "agents/bills-agent"
   ],
   "scripts": {
     "start": "npm start --workspace=agents/bills-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/bills-agent/tsconfig.json",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/tsconfig.json && tsc --noEmit -p agents/bills-agent/tsconfig.json",
     "approve": "npm run approve --workspace=agents/bills-agent --",
     "consent": "npm run consent --workspace=agents/bills-agent --",
     "deny": "npm run deny --workspace=agents/bills-agent --",
     "eval": "npm run eval --workspace=agents/bills-agent --",
+    "inspect": "npm run inspect --workspace=agents/bills-agent --",
     "reconcile": "npm run reconcile --workspace=agents/bills-agent --",
     "rerun": "npm run rerun --workspace=agents/bills-agent --",
-    "resume": "npm run resume --workspace=agents/bills-agent --"
+    "resume": "npm run resume --workspace=agents/bills-agent --",
+    "verify": "npm run verify --workspace=agents/bills-agent --"
   },
   "devDependencies": {
     "@types/node": "22.20.4",

package/templates/bills-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/bills-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/bills-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/bills-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,
       };

package/templates/bills-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -6,11 +6,15 @@
  * project's triggers, and every record it leaves carries `simulated: true`
  * plus `settled_against: "sandbox_fixture"`. No money moves anywhere. A
  * live-environment key is refused with `sandbox_pay_not_permitted` before
- * anything is read. The route is not in the SDK's typed operations yet
- * (merged 2026-09-23), so it is called by path.
+ * anything is read. Since `@codespar/sdk@0.16.5` the route is in the SDK's
+ * OpenAPI document, so this is the client's own typed call (same base URL,
+ * key and project header as every other call); until 0.16.4 it was a plain
+ * `fetch`, see docs/OPEN_QUESTIONS.md section 31c. The key is checked for
+ * the `csk_test_` prefix before a client exists, like every other call.
  */
-import type { ApiClient } from "@codespar/sdk";
-import { describeApiError, type ApiFailure } from "./client.js";
+import { ApiClient } from "@codespar/sdk";
+import type { ApiFailure } from "./client.js";
+import { createCodeSparClient, describeApiError } from "./client.js";
 
 export interface SandboxPaidState {
   charge_id: string;
@@ -32,12 +36,21 @@ export interface SandboxPaidState {
 
 export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
 
-export async function paySandboxCharge(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+/** Where the payer route lives when no client exists yet: the same three things `createCodeSparClient` takes. */
+export interface SandboxPayerTarget {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+  const api = target instanceof ApiClient ? target : createCodeSparClient(target);
   try {
-    const state = (await api.request("post", "/v1/test/charges/{chargeId}/pay" as never, {
+    const state = await api.post("/v1/test/charges/{chargeId}/pay", {
       path: { chargeId: chargeRef },
       body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
-    } as never)) as SandboxPaidState;
+    });
     return { ok: true, state };
   } catch (err) {
     return { ok: false, failure: describeApiError(err) };

package/templates/bills-agent/packages/agent-core/src/approval.ts

@@ -13,7 +13,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { dirname, join } from "node:path";
 import { canonicalJson, hexEqual, hmacSha256Hex, itemsHash } from "./hash.js";
 import type { Execution } from "./state-machine.js";
-import type { Actor, ApprovalArtifact, EscalationTrigger } from "./types.js";
+import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch } from "./types.js";
 import { newId } from "./ids.js";
 
 export const APPROVAL_KEY_ID = "local-dev-stub";
@@ -74,6 +74,10 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
     mandate: execution.mandate,
     items: execution.items,
     items_hash: itemsHash(execution.items),
+    // The SET this line belongs to, when it belongs to one. Omitted — never
+    // null — on an execution that is not part of a batch, so the payload a
+    // bills-agent artifact signs is unchanged by this field existing.
+    ...(execution.batch ? { batch: execution.batch } : {}),
     ...(input.escalation ? { escalation: input.escalation } : {}),
     actor: input.actor,
   };
@@ -85,7 +89,13 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
 
 export type ApprovalCheck =
   | { ok: true }
-  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" };
+  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" };
+
+/** Two batch bindings are the same binding, or one is absent and so is the other. */
+function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.batch_hash === b.batch_hash && a.index === b.index && a.count === b.count;
+}
 
 /**
  * The rule that makes the artifact proof: before `executing`, recompute the
@@ -104,6 +114,10 @@ export function checkApprovalArtifact(
     return { ok: false, problem: "wrong_mandate" };
   }
   if (itemsHash(execution.items) !== artifact.items_hash) return { ok: false, problem: "items_hash_mismatch" };
+  // The line's own list is attested by the hash above; this is the list the
+  // line was one OF. An execution that gained, lost or moved its place in a
+  // batch after approval is not the one that was approved.
+  if (!sameBatch(artifact.batch, execution.batch)) return { ok: false, problem: "batch_mismatch" };
   if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
   return { ok: true };
 }

package/templates/bills-agent/packages/agent-core/src/bundle.ts

@@ -4,7 +4,7 @@
  * payee keys are masked the way a bank statement masks them.
  */
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { Mandate } from "./mandate.js";
 import type { RailReceipt } from "./rail.js";
 import type { ApprovalArtifact } from "./types.js";
@@ -47,6 +47,29 @@ export class ProofBundle {
     appendFileSync(join(this.dir, "events.jsonl"), JSON.stringify(event) + "\n");
   }
 
+  /**
+   * The conversation, when the run had one: every message in and out of a
+   * channel, in order, with what the channel did with it. Separate from the
+   * transcript, which is the MODEL's side, because on a channel the two are
+   * not the same thing — a message the channel refused never reached the
+   * person, and the QR and the copy-and-paste were sent by the runner.
+   *
+   * It carries no contact in the clear: the channel masks it before it gets
+   * here, because the bundle travels.
+   */
+  channel(line: Record<string, unknown>): void {
+    appendFileSync(join(this.dir, "channel.jsonl"), JSON.stringify(line) + "\n");
+  }
+
+  readChannel(): Record<string, unknown>[] {
+    const path = join(this.dir, "channel.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
   readEvents(): Record<string, unknown>[] {
     const path = join(this.dir, "events.jsonl");
     if (!existsSync(path)) return [];
@@ -74,11 +97,34 @@ export class ProofBundle {
     writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
   }
 
+  /** Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it. */
   receipt(receipt: RailReceipt): string {
-    const path = join(this.dir, "receipts", `${receipt.receipt_id}.json`);
+    const relative = join("receipts", `${receipt.receipt_id}.json`);
     const { raw: _raw, ...safe } = receipt;
-    writeFileSync(path, JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
-    return path;
+    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
+    return relative;
+  }
+
+  /** The masked mandate as it stood when the run started. Absent on a bundle whose run never got that far. */
+  readMandateSnapshot(): Record<string, unknown> | undefined {
+    const path = join(this.dir, "mandate.snapshot.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /** One receipt by its file name, as `listReceipts()` returns it. */
+  readReceipt(file: string): Record<string, unknown> | undefined {
+    const path = join(this.dir, "receipts", basename(file));
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /**
+   * Section 11: `verify.json` is the output of `codespar audit replay`, which
+   * is not a registered command of the CLI, so nothing here writes it and
+   * nothing here reimplements the hash-chain check. The reader exists so a
+   * bundle that gains one later is noticed rather than ignored.
+   */
+  hasVerify(): boolean {
+    return existsSync(join(this.dir, "verify.json"));
   }
 
   listReceipts(): string[] {

package/templates/bills-agent/packages/agent-core/src/channels.ts

@@ -0,0 +1,140 @@
+/**
+ * The channels an agent can be reached on, and the one artifact an agent
+ * ships per channel.
+ *
+ * The NAMES live here because `agent.yaml` declares them and `npm run check`
+ * has to confirm the declaration against what the agent ships; the BEHAVIOUR
+ * lives in `@codespar/agent-runtime`, which owns the runner. That split is
+ * the same one `tools.json` and `guardrails.json` already have: the core
+ * owns the shape, the runtime owns what happens.
+ *
+ * `terminal` is every agent's: `npm start` opens it and needs no account.
+ * `whatsapp` is the second channel, and an agent that declares it ships the
+ * conversations the local Cloud API emulator drives, under
+ * `channels/whatsapp/`.
+ */
+import { z } from "zod";
+
+export const CHANNELS = ["terminal", "whatsapp"] as const;
+export type ChannelName = (typeof CHANNELS)[number];
+
+/** E.164, the only contact shape WhatsApp addresses. */
+export const E164 = /^\+[1-9]\d{6,14}$/;
+
+/**
+ * A scripted conversation, which is what an agent ships for a channel whose
+ * other side is a person rather than a keyboard.
+ *
+ * It exists for two readers. A local emulator of the Cloud API drives it with
+ * no Meta account, which is what makes the WhatsApp gate runnable in the CI;
+ * and `npm run check` parses it, so a conversation that no longer names a
+ * contact or an agreement fails the manifest gate instead of failing a run.
+ *
+ * It scripts ONE side. What the agent answers comes from the model or from a
+ * recorded transcript, never from here, for the same reason a scenario pack
+ * asserts a final state and not a wording.
+ */
+export const ConversationScriptSchema = z
+  .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string().min(1),
+    channel: z.literal("whatsapp"),
+    /** The contact the conversation is bound to: the person who owes, and nobody else. */
+    contact: z.string().regex(E164, "contact must be E.164, e.g. +5511987654321"),
+    /**
+     * What this conversation is allowed to be about — an agreement alias for a
+     * collections agent. The channel refuses an outbound message that names a
+     * different one, which is the secrecy rule as code rather than as prose.
+     */
+    subject: z.string().min(1).optional(),
+    /** The person's turns, in order. */
+    turns: z
+      .array(
+        z
+          .object({
+            text: z.string().min(1),
+            /** Seconds after the previous inbound turn, on the run's clock. Keeps a scripted run deterministic. */
+            after_seconds: z.number().int().nonnegative().default(0),
+          })
+          .strict(),
+      )
+      .nonempty(),
+  })
+  .strict();
+
+export type ConversationScript = z.infer<typeof ConversationScriptSchema>;
+
+export function parseConversationScript(text: string): ConversationScript {
+  return ConversationScriptSchema.parse(JSON.parse(text));
+}
+
+/**
+ * The reserved file name inside `channels/whatsapp/`: the template registry,
+ * which is not a conversation. Everything else in that directory is one, so
+ * a conversation may not be called `templates`.
+ */
+export const TEMPLATE_REGISTRY_FILE = "templates.json";
+
+/**
+ * One template the agent declares it sends.
+ *
+ * `body` is here for a reader, not for a sender: it is the text AS SUBMITTED
+ * to Meta, and it is the only way somebody opening this repository can tell
+ * what `{{1}}` means. Nothing composes a message from it — Meta holds the
+ * approved copy and renders it — but the number of placeholders in it IS
+ * checked against the variables a send carries, because a count that does not
+ * match is a `132000` from the Cloud API and there is no reason to learn that
+ * in production.
+ */
+export const WhatsAppTemplateSchema = z
+  .object({
+    /** Meta's own naming rule for a template. */
+    name: z.string().regex(/^[a-z0-9_]+$/, "a template name is lower-case letters, digits and underscores"),
+    /** Meta's language code, e.g. `pt_BR`. A template approved in one language does not exist in another. */
+    language: z.string().regex(/^[a-z]{2}(_[A-Z]{2})?$/, 'expected a language code, e.g. "pt_BR"'),
+    description: z.string().min(1),
+    body: z.string().min(1),
+  })
+  .strict();
+
+export type WhatsAppTemplate = z.infer<typeof WhatsAppTemplateSchema>;
+
+/**
+ * `channels/whatsapp/templates.json`: the LOCAL registry of the templates an
+ * agent uses.
+ *
+ * Outside the 24 hours that follow the person's last message WhatsApp carries
+ * an approved template and nothing else, so an agent that ever speaks after
+ * that has to own one. Whether META approved it is NOT knowable from here —
+ * it is a status inside a Business account, and this repository has none — so
+ * what this file proves is narrower and worth stating exactly: the agent
+ * declared the name, so a send of a name nobody declared is refused here
+ * instead of 400-ing at Meta. Registering the template and getting it approved
+ * stays the developer's, and the README says so.
+ */
+export const TemplateRegistrySchema = z
+  .object({
+    channel: z.literal("whatsapp"),
+    templates: z.array(WhatsAppTemplateSchema).nonempty(),
+  })
+  .strict()
+  .superRefine((registry, ctx) => {
+    const seen = new Set<string>();
+    for (const [i, template] of registry.templates.entries()) {
+      if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
+      seen.add(template.name);
+    }
+  });
+
+export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;
+
+export function parseTemplateRegistry(text: string): TemplateRegistry {
+  return TemplateRegistrySchema.parse(JSON.parse(text));
+}
+
+/** The highest `{{n}}` in a template body, which is how many variables a send of it must carry. */
+export function templateArity(body: string): number {
+  let highest = 0;
+  for (const match of body.matchAll(/\{\{\s*(\d+)\s*\}\}/g)) highest = Math.max(highest, Number(match[1]));
+  return highest;
+}