@codespar/cli 0.14.0 → 0.16.0

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

@@ -0,0 +1,117 @@
+/**
+ * The CodeSpar sandbox rail. With the signed envelope the consent returned
+ * (`mandate.canonical` + `mandate.signature`) it spends through
+ * `POST /v1/consumer-payments/execute`; without it, by mandate id through
+ * `POST /v1/consumers/mandates/{id}/spend`. Both are idempotent on
+ * `attempt_id`. The by-id route answered `bad_signature` on staging for a
+ * mandate carrying `periodic_cap` (OPEN_QUESTIONS §14), which is why the
+ * envelope is preferred when it exists. Receipts come back from
+ * `GET /v1/consumers/receipts/{id}`.
+ *
+ * The API has no `actor` field on the wire today (OPEN_QUESTIONS §2). The
+ * spend carries `agent_id`, which the mandate binds; the full actor is
+ * stamped on the local receipt copy and on every event of the bundle.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import type { Mandate } from "../mandate.js";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+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;
+
+  constructor(
+    private readonly api: ApiClient,
+    private readonly envelope?: Pick<Mandate, "canonical" | "signature"> | undefined,
+  ) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    try {
+      const outcome =
+        this.envelope?.canonical && this.envelope.signature
+          ? await this.api.post("/v1/consumer-payments/execute", {
+              body: {
+                mandate: this.envelope.canonical,
+                signature: this.envelope.signature,
+                amount_minor: payment.amount_minor,
+                purpose: payment.purpose,
+                agent_id: payment.agent_id,
+                payee: payment.payee,
+                attempt_id: payment.attempt_id,
+              },
+            })
+          : await this.api.post("/v1/consumers/mandates/{id}/spend", {
+              path: { id: payment.mandate_id },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id },
+            });
+      return {
+        status: "settled",
+        transaction_id: outcome.payment.transactionId,
+        receipt_id: outcome.receipt?.id ?? null,
+        money_moved: outcome.payment.moneyMoved,
+        sandbox: !outcome.payment.moneyMoved,
+        raw: outcome,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+  }
+
+  /**
+   * There is no read route for an attempt. The documented way is to present
+   * the same `attempt_id` again: the lifecycle is idempotent on it and
+   * answers the state it reached. `psp_attempt_in_flight` means the first
+   * presentation is still running.
+   */
+  async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const outcome = await this.pay(payment);
+    if (outcome.status === "failed" && outcome.code === "psp_attempt_in_flight") return { status: "in_flight" };
+    return outcome;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    try {
+      const r = await this.api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
+      return {
+        receipt_id: r.receipt_id,
+        state: r.state,
+        mandate: { id: r.mandate.id },
+        payment: {
+          amount_minor: r.payment.amount_minor,
+          payee: r.quote?.payee ?? null,
+          attempt_id: r.payment.attempt_id,
+          money_moved: r.payment.money_moved,
+          sandbox: r.payment.sandbox === true,
+          at: r.payment.at,
+        },
+        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,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The sandbox PAYER: `POST /v1/test/charges/{chargeId}/pay` (alias
+ * `POST /v1/charges/{chargeId}/sandbox/pay`), test environment only. It
+ * plays the debtor: the charge goes through the same settlement path a
+ * provider `charge-in` webhook takes, `commerce.charge.paid` fans out to the
+ * 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. 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 { ApiClient } from "@codespar/sdk";
+import type { ApiFailure } from "./client.js";
+import { createCodeSparClient, describeApiError } from "./client.js";
+
+export interface SandboxPaidState {
+  charge_id: string;
+  status: "paid";
+  local_status: string;
+  currency: string;
+  quoted_minor: number;
+  paid_minor: number;
+  payment: "full" | "partial" | "over";
+  paid_via: string;
+  wallet_id: string;
+  ledger_entry_id: string | null;
+  event: { id: string; type: string } | null;
+  simulated: boolean;
+  settled_against: string | null;
+  money_moved: false;
+  idempotent_replay: boolean;
+}
+
+export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
+
+/** 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.post("/v1/test/charges/{chargeId}/pay", {
+      path: { chargeId: chargeRef },
+      body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
+    });
+    return { ok: true, state };
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Section 4.2: the approval artifact.
+ *
+ * STUB, on purpose: the artifact is signed with a LOCAL development key
+ * (`.codespar/approval.key`, generated on first use, never committed). The
+ * CodeSpar API does not sign approval lists; its HMAC is the mandate proof
+ * and the receipt seal. Until an API-side signature exists the artifact
+ * proves what was approved to whoever runs the agent, and to nobody else.
+ * See docs/OPEN_QUESTIONS.md.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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, ExecutionBatch } from "./types.js";
+import { newId } from "./ids.js";
+
+export const APPROVAL_KEY_ID = "local-dev-stub";
+export const DEFAULT_APPROVAL_TTL_MS = 15 * 60 * 1000;
+
+export interface ApprovalSigner {
+  keyId: string;
+  sign(payload: string): string;
+  verify(payload: string, signature: string): boolean;
+}
+
+export function loadOrCreateLocalApprovalKey(stateDir: string): ApprovalSigner {
+  const path = join(stateDir, "approval.key");
+  let key: Buffer;
+  if (existsSync(path)) {
+    key = Buffer.from(readFileSync(path, "utf8").trim(), "hex");
+  } else {
+    mkdirSync(dirname(path), { recursive: true });
+    key = randomBytes(32);
+    writeFileSync(path, key.toString("hex") + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+  }
+  return hmacSigner(APPROVAL_KEY_ID, key);
+}
+
+export function hmacSigner(keyId: string, key: Buffer): ApprovalSigner {
+  return {
+    keyId,
+    sign: (payload) => hmacSha256Hex(key, payload),
+    verify: (payload, signature) => hexEqual(hmacSha256Hex(key, payload), signature),
+  };
+}
+
+function unsignedPayload(artifact: Omit<ApprovalArtifact, "signature">): string {
+  return canonicalJson(artifact);
+}
+
+export interface CreateApprovalInput {
+  execution: Execution;
+  approver: ApprovalArtifact["approver"];
+  actor: Actor;
+  now: Date;
+  ttlMs?: number;
+  escalation?: { trigger: EscalationTrigger; detail: string };
+}
+
+export function createApprovalArtifact(signer: ApprovalSigner, input: CreateApprovalInput): ApprovalArtifact {
+  const { execution } = input;
+  const approvedAt = input.now.toISOString();
+  const expiresAt = new Date(input.now.getTime() + (input.ttlMs ?? DEFAULT_APPROVAL_TTL_MS)).toISOString();
+  const unsigned: Omit<ApprovalArtifact, "signature"> = {
+    approval_id: newId("apr"),
+    execution_id: execution.id,
+    mode: execution.mode,
+    approver: input.approver,
+    approved_at: approvedAt,
+    expires_at: expiresAt,
+    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,
+  };
+  return {
+    ...unsigned,
+    signature: { alg: "HMAC-SHA256", key_id: signer.keyId, value: signer.sign(unsignedPayload(unsigned)) },
+  };
+}
+
+export type ApprovalCheck =
+  | { ok: true }
+  | { 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
+ * hash of what is about to be executed and compare it with the artifact.
+ */
+export function checkApprovalArtifact(
+  signer: ApprovalSigner,
+  artifact: ApprovalArtifact,
+  execution: Execution,
+  now: Date,
+): ApprovalCheck {
+  const { signature, ...unsigned } = artifact;
+  if (!signer.verify(unsignedPayload(unsigned), signature.value)) return { ok: false, problem: "signature_invalid" };
+  if (artifact.execution_id !== execution.id) return { ok: false, problem: "wrong_execution" };
+  if (artifact.mandate.id !== execution.mandate.id || artifact.mandate.version !== execution.mandate.version) {
+    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/hello-agent/packages/agent-core/src/bundle.ts

@@ -0,0 +1,159 @@
+/**
+ * Section 11: the proof bundle, one folder per run under `runs/<run-id>/`.
+ * It answers "why could the agent pay this". It holds no key and no secret;
+ * payee keys are masked the way a bank statement masks them.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Mandate } from "./mandate.js";
+import type { RailReceipt } from "./rail.js";
+import type { ApprovalArtifact } from "./types.js";
+
+export interface TranscriptLine {
+  at: string;
+  kind: "user" | "assistant_step" | "tool_call" | "tool_result" | "assistant" | "system";
+  [key: string]: unknown;
+}
+
+export class ProofBundle {
+  readonly dir: string;
+
+  constructor(
+    runsDir: string,
+    readonly runId: string,
+  ) {
+    this.dir = join(runsDir, runId);
+    mkdirSync(join(this.dir, "receipts"), { recursive: true });
+  }
+
+  static open(runsDir: string, runId: string): ProofBundle | undefined {
+    return existsSync(join(runsDir, runId)) ? new ProofBundle(runsDir, runId) : undefined;
+  }
+
+  transcript(line: TranscriptLine): void {
+    appendFileSync(join(this.dir, "transcript.jsonl"), JSON.stringify(line) + "\n");
+  }
+
+  readTranscript(): TranscriptLine[] {
+    const path = join(this.dir, "transcript.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as TranscriptLine);
+  }
+
+  event(event: Record<string, unknown>): void {
+    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 [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
+  /** `approval.json` is the list of artifacts of this run, in approval order. */
+  approval(artifact: ApprovalArtifact): void {
+    const path = join(this.dir, "approval.json");
+    const current: ApprovalArtifact[] = existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as ApprovalArtifact[]) : [];
+    if (!current.some((a) => a.approval_id === artifact.approval_id)) current.push(artifact);
+    writeFileSync(path, JSON.stringify(current, null, 2) + "\n");
+  }
+
+  readApprovals(): ApprovalArtifact[] {
+    const path = join(this.dir, "approval.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as ApprovalArtifact[]) : [];
+  }
+
+  mandateSnapshot(mandate: Mandate): void {
+    const { signature: _signature, canonical: _canonical, ...safe } = mandate;
+    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 relative = join("receipts", `${receipt.receipt_id}.json`);
+    const { raw: _raw, ...safe } = receipt;
+    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[] {
+    const dir = join(this.dir, "receipts");
+    if (!existsSync(dir)) return [];
+    return readdirSorted(dir);
+  }
+
+  meta(meta: Record<string, unknown>): void {
+    writeFileSync(join(this.dir, "run.json"), JSON.stringify(meta, null, 2) + "\n");
+  }
+
+  readMeta(): Record<string, unknown> | undefined {
+    const path = join(this.dir, "run.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+}
+
+function readdirSorted(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .sort();
+}
+
+/** `escola@exemplo.com.br` -> `es***@exemplo.com.br`; `+5511999998888` -> `+55***8888`; a UUID keeps its first and last 4. */
+export function maskPayee(payee: string): string {
+  if (payee === "*") return payee;
+  const at = payee.indexOf("@");
+  if (at > 0) return `${payee.slice(0, Math.min(2, at))}***${payee.slice(at)}`;
+  if (payee.length <= 8) return `${payee.slice(0, 2)}***`;
+  return `${payee.slice(0, 4)}***${payee.slice(-4)}`;
+}

package/templates/hello-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;
+}