@codespar/cli 0.14.1 → 0.16.0

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

@@ -0,0 +1,225 @@
+/**
+ * The WhatsApp channel: one adapter, two backends.
+ *
+ * Everything that decides what may be said lives HERE and not in a backend,
+ * which is what makes "the rules are code" true rather than aspirational.
+ * Picking the simulator or the official API changes who carries the bytes; it
+ * does not change the hours, the bound contact, the secrecy of the debt, the
+ * document rule or the session window. A test that tries to get around a rule
+ * by choosing a backend is in `test/whatsapp-rules.test.ts` and fails.
+ *
+ * It also keeps the two audiences apart. `send` reaches the person who owes.
+ * The operator's console and the approval question are wired to stderr by the
+ * caller and have no path to this object at all — not a check, a shape: there
+ * is no method here that an operator line could be handed to.
+ */
+import type { ProofBundle, WhatsAppTemplate } from "@codespar/agent-core";
+import { checkOutbound, type HoursRule, type RuleContext } from "../rules.js";
+import type { Channel, ChannelBackend, ChannelLogLine, Conversation, InboundMessage, OutboundBody, SentMessage } from "../types.js";
+import { maskContact } from "../contact.js";
+import { SessionWindow, type SessionState } from "./session.js";
+
+export interface WhatsAppChannelOptions {
+  backend: ChannelBackend;
+  conversation: Conversation;
+  now: () => Date;
+  hours?: HoursRule | undefined;
+  knownSubjects?: readonly string[] | undefined;
+  /** The run's bundle, so the conversation is part of the proof. */
+  bundle?: ProofBundle | undefined;
+  /** Templates the agent declares it uses, from `channels/whatsapp/templates.json`. Meta's approval of them is not knowable from here. */
+  templates?: readonly WhatsAppTemplate[] | undefined;
+  /**
+   * Where the window stood when an earlier run left this conversation. A run
+   * that JOINS a conversation — a poll looking at a charge agreed yesterday —
+   * has no inbound message of its own to open it from, and without this it
+   * would read every conversation as shut.
+   */
+  session?: SessionState | undefined;
+  /** The operator's console. Refusals are reported here, never to the conversation. */
+  say?: ((line: string) => void) | undefined;
+  /**
+   * Draws the conversation for whoever is watching the run. It is a VIEW of
+   * what went over the channel, written after the fact, and never a way to put
+   * something in front of the person — that is `send`, and it is the only one.
+   */
+  render?: ((line: string) => void) | undefined;
+}
+
+export class WhatsAppChannel implements Channel {
+  readonly name = "whatsapp" as const;
+  readonly conversation: Conversation;
+  private readonly session: SessionWindow;
+  private readonly lines: ChannelLogLine[] = [];
+  private lastInbound: InboundMessage | undefined;
+
+  constructor(private readonly options: WhatsAppChannelOptions) {
+    this.conversation = options.conversation;
+    this.session = new SessionWindow(options.templates ?? [], options.session);
+  }
+
+  get backend(): string {
+    return this.options.backend.name;
+  }
+
+  /** Whether the backend talks to a real provider. What the consent-evidence seam turns on. */
+  get live(): boolean {
+    return this.options.backend.live;
+  }
+
+  /** The message the person last sent, for the caller that needs to attest to an act. */
+  get lastInboundMessage(): InboundMessage | undefined {
+    return this.lastInbound;
+  }
+
+  /**
+   * Whether a free-form message may go out right now. A caller that has one
+   * thing to say and two ways to say it asks HERE which one the provider
+   * would carry — the alternative is composing a message, watching the
+   * channel refuse it, and calling that a decision.
+   */
+  get sessionOpen(): boolean {
+    return this.session.open(this.options.now());
+  }
+
+  /** Seconds of free-form left, for the console line that explains the choice. */
+  get sessionRemainingSeconds(): number {
+    return this.session.remainingSeconds(this.options.now());
+  }
+
+  /** What the agent declared about a template it is about to send. The language is the registry's, never the sender's guess. */
+  declaredTemplate(name: string): WhatsAppTemplate | undefined {
+    return this.session.declared(name);
+  }
+
+  async open(): Promise<void> {
+    await this.options.backend.open();
+  }
+
+  async next(): Promise<InboundMessage | undefined> {
+    const message = await this.options.backend.next();
+    if (!message) return undefined;
+    this.lastInbound = message;
+    this.session.observeInbound(message.timestamp);
+    this.record({
+      at: this.options.now().toISOString(),
+      direction: "in",
+      contact: maskContact(message.from),
+      kind: "text",
+      message_id: message.id,
+      state: "delivered",
+      text: message.text,
+      // The provider's clock, which is the only one the 24-hour window is
+      // counted on. A later run reads the window back from here.
+      provider_timestamp: message.timestamp,
+    });
+    return message;
+  }
+
+  async send(body: OutboundBody): Promise<SentMessage> {
+    const to = this.conversation.contact;
+    const ctx: RuleContext = {
+      conversation: this.conversation,
+      hours: this.options.hours,
+      now: this.options.now,
+      knownSubjects: this.options.knownSubjects,
+    };
+
+    // The house rules first: a message the law refuses is not a message the provider should ever see.
+    const refusal = checkOutbound(to, body, ctx) ?? this.providerRefusal(body);
+    if (refusal) {
+      const sent: SentMessage = { id: "", state: "failed", refused: refusal };
+      this.logOutbound(body, sent);
+      this.options.say?.(`  [whatsapp] recusado (${refusal.rule}): ${refusal.detail}`);
+      return sent;
+    }
+
+    const sent = await this.options.backend.deliver(to, body);
+    if (sent.refused) this.options.say?.(`  [whatsapp] recusado pelo backend (${sent.refused.rule}): ${sent.refused.detail}`);
+    this.logOutbound(body, sent);
+    return sent;
+  }
+
+  say(text: string): Promise<SentMessage> {
+    return this.send({ kind: "text", text });
+  }
+
+  async close(): Promise<void> {
+    await this.options.backend.close();
+  }
+
+  /** Every message of this conversation, in order. */
+  log(): ReadonlyArray<ChannelLogLine> {
+    return this.lines;
+  }
+
+  private logOutbound(body: OutboundBody, sent: SentMessage): void {
+    this.record({
+      at: this.options.now().toISOString(),
+      direction: "out",
+      contact: maskContact(this.conversation.contact),
+      kind: body.kind,
+      message_id: sent.id,
+      state: sent.state,
+      ...(textOf(body) !== undefined ? { text: textOf(body)! } : {}),
+      ...(sent.refused ? { refused: sent.refused } : {}),
+    });
+  }
+
+  /**
+   * WhatsApp's own rule, enforced on both backends: outside the 24 hours
+   * after the person's last message only an approved template may go out.
+   * The simulator obeys it because a rule that only bites in production is a
+   * rule you meet in production.
+   */
+  private providerRefusal(body: OutboundBody): { rule: string; detail: string } | undefined {
+    const open = this.session.open(this.options.now());
+    if (body.kind === "template") return this.session.refuse(body);
+    if (!open) {
+      return {
+        rule: "session_window_closed",
+        detail: "more than 24h since the person's last message: WhatsApp only carries an approved template now, not a free-form message",
+      };
+    }
+    return undefined;
+  }
+
+  private record(line: ChannelLogLine): void {
+    this.lines.push(line);
+    this.options.bundle?.channel({ ...line, channel: "whatsapp", backend: this.backend });
+    this.options.render?.(`  │ ${draw(line)}`);
+  }
+}
+
+/** One console line for one message. The refusals are visible: a message nobody got is part of the conversation's story. */
+function draw(line: ChannelLogLine): string {
+  const who = line.direction === "in" ? `${line.contact}:` : "loja:";
+  const what =
+    line.kind === "instrument"
+      ? `[copia e cola] ${line.text ?? ""}`
+      : line.kind === "media"
+        ? "[imagem: QR Pix]"
+        : line.kind === "template"
+          ? line.text ?? "[template]"
+          : line.text ?? "";
+  return line.refused ? `${who} (nao enviada: ${line.refused.rule}) ${what}` : `${who} ${what}`;
+}
+
+function textOf(body: OutboundBody): string | undefined {
+  switch (body.kind) {
+    case "text":
+      return body.text;
+    case "instrument":
+      return body.value;
+    case "media":
+      return body.caption;
+    case "template":
+      return `[template ${body.template}] ${body.variables.join(" | ")}`;
+  }
+}
+
+export * from "../contact.js";
+export * from "./cloud-api.js";
+export * from "./emulator.js";
+export * from "./evidence.js";
+export * from "./session.js";

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/open.ts

@@ -0,0 +1,143 @@
+/**
+ * Opening the WhatsApp channel: wiring, and only wiring.
+ *
+ * It lives apart from the command that starts a conversation because a second
+ * command now JOINS one — `codespar-agent poll --channel whatsapp`, which
+ * comes back to a conversation the run that opened it has long since ended.
+ * Two commands wiring the same channel by hand is how a rule ends up enforced
+ * on one path and not the other, and the whole claim of `channels/` is that
+ * the rules are above the backend. So both go through here.
+ *
+ * The decisions are all elsewhere: the rules in `channels/rules.ts`, the
+ * session window in `session.ts`, the gates in `terminal.ts`.
+ */
+import type { ConversationScript, ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "../../agent.js";
+import type { Setup } from "../../setup.js";
+import { knownSubjects, loadTemplates } from "../index.js";
+import type { ChannelBackend, Conversation } from "../types.js";
+import { WhatsAppChannel } from "./index.js";
+import { toGraphNumber, WhatsAppCloudApi, loadCloudApiConfig, type CloudApiConfig } from "./cloud-api.js";
+import { EmulatorDriver, EMULATOR_DEFAULTS, EMULATOR_ENV, WhatsAppEmulator } from "./emulator.js";
+import type { SessionState } from "./session.js";
+
+export type WhatsAppBackendName = "simulator" | "cloud-api";
+
+export interface OpenWhatsAppOptions {
+  agent: Agent;
+  setup: Setup;
+  conversation: Conversation;
+  backend: WhatsAppBackendName;
+  now: () => Date;
+  say: (line: string) => void;
+  /**
+   * Where the conversation is recorded. Normally the run's own bundle; a poll
+   * hands the bundle of the run it is continuing, because a conversation is
+   * one record and the message that closes it belongs with the ones that
+   * opened it.
+   */
+  bundle: ProofBundle;
+  /** The person's turns, when a script drives them. Absent and with no `ask`, nobody writes. */
+  script?: ConversationScript | undefined;
+  /** Interactive only: reads the person's next line. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /**
+   * Pins the emulator's CONVERSATION clock. A run that starts a conversation
+   * pins it; a run that joins one must not, because rewinding the provider's
+   * clock would reopen a window that really is shut. The agent's own notion of
+   * now is `now` above and is a different thing (#16).
+   */
+  pinAt?: Date | undefined;
+  /** Where the session window stood when an earlier run left this conversation. */
+  session?: SessionState | undefined;
+  /** Draws the conversation on the operator's console. */
+  render?: ((line: string) => void) | undefined;
+}
+
+export interface OpenedWhatsApp {
+  channel: WhatsAppChannel;
+  /** The `_sim/*` side, when the backend is the emulator. Absent against Meta. */
+  driver?: EmulatorDriver;
+  /** How the emulator keys this conversation, for the priced timeline. */
+  sessionKey?: string;
+}
+
+/**
+ * Builds the channel, or explains what is missing. Nothing is opened here:
+ * the caller opens it, because an emulator that is not running has to be
+ * reported differently depending on how far the command already got.
+ */
+export function buildWhatsApp(options: OpenWhatsAppOptions): OpenedWhatsApp | { refusal: string[] } {
+  const { agent, setup: s, say } = options;
+  let backend: ChannelBackend;
+  let driver: EmulatorDriver | undefined;
+  let sessionKey: string | undefined;
+
+  if (options.backend === "cloud-api") {
+    const { config, missing } = loadCloudApiConfig(process.env);
+    if (!config) {
+      return {
+        refusal: [
+          `the cloud-api backend needs credentials this repo ships none of: ${missing.join(", ")}.`,
+          `They live in the agent's .env (commented out in .env.example) and belong to a Meta Business account. The emulator needs none: drop --backend cloud-api.`,
+        ],
+      };
+    }
+    say("[whatsapp] cloud-api backend: this repo has never run one against Meta. The shapes are written from the published documentation; the first live run is yours.");
+    backend = new WhatsAppCloudApi({ config, conversation: { contact: options.conversation.contact }, say });
+  } else {
+    // The SAME backend, pointed somewhere else. What the emulator adds is the
+    // `_sim/*` side: making the person write, and moving the conversation clock.
+    const env = process.env;
+    const url = env[EMULATOR_ENV.url]?.trim() || EMULATOR_DEFAULTS.url;
+    const config: CloudApiConfig = {
+      baseUrl: url,
+      phoneNumberId: env[EMULATOR_ENV.phoneNumberId]?.trim() || EMULATOR_DEFAULTS.phoneNumberId,
+      // Not credentials: the emulator has no auth, and these are the values
+      // `npm run whatsapp:emulator` starts it with.
+      accessToken: "emulator",
+      verifyToken: "emulator",
+      appSecret: env[EMULATOR_ENV.appSecret]?.trim() || EMULATOR_DEFAULTS.appSecret,
+      apiVersion: EMULATOR_DEFAULTS.apiVersion,
+      webhookPort: Number(env[EMULATOR_ENV.webhookPort]?.trim() || EMULATOR_DEFAULTS.webhookPort),
+    };
+    driver = new EmulatorDriver(url);
+    sessionKey = `${config.phoneNumberId}:${toGraphNumber(options.conversation.contact)}`;
+    backend = new WhatsAppEmulator({
+      config,
+      conversation: { contact: options.conversation.contact },
+      driver,
+      say,
+      render: options.render ?? say,
+      ...(options.script ? { script: options.script } : {}),
+      ...(options.ask ? { ask: options.ask } : {}),
+      ...(options.pinAt ? { pinAt: options.pinAt } : {}),
+    });
+  }
+
+  // The hours are the agent's, from `guardrails.envelope.collection_hours`. An agent that declares none gets no hours rule, which is correct: not every conversation is a collection.
+  const window = typeof s.guardrails.envelope?.["collection_hours"] === "string" ? (s.guardrails.envelope["collection_hours"] as string) : undefined;
+
+  const channel = new WhatsAppChannel({
+    backend,
+    conversation: options.conversation,
+    now: options.now,
+    ...(window ? { hours: { window, timezone: s.guardrails.timezone } } : {}),
+    knownSubjects: knownSubjects(agent),
+    templates: loadTemplates(agent),
+    bundle: options.bundle,
+    say,
+    render: options.render ?? say,
+    ...(options.session ? { session: options.session } : {}),
+  });
+
+  return { channel, ...(driver ? { driver } : {}), ...(sessionKey ? { sessionKey } : {}) };
+}
+
+/** The priced timeline the emulator computed: read for the console, never asserted on. */
+export async function simulatedCost(driver: EmulatorDriver | undefined, sessionKey: string | undefined): Promise<{ total: number; currency: string } | undefined> {
+  if (!driver || !sessionKey) return undefined;
+  const state = (await driver.state(sessionKey).catch(() => undefined)) as { priced?: { total?: number; currency?: string } } | undefined;
+  if (typeof state?.priced?.total !== "number") return undefined;
+  return { total: state.priced.total, currency: state.priced.currency ?? "BRL" };
+}

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/present.ts

@@ -0,0 +1,47 @@
+/**
+ * How a payable receivable is put into a conversation.
+ *
+ * It is here, and not inside the run loop, because two commands now present
+ * one: the run that issues the charge, and the poll that comes back to it
+ * later. A payer told how to pay by a poll must be told the same way as a
+ * payer told by a run, and the only way to guarantee that is for both to
+ * build the same messages from the same place.
+ *
+ * The shape is the point. The QR goes as an IMAGE and the copy-and-paste as
+ * its OWN message underneath, because a code inside a picture cannot be
+ * copied and a code inside a paragraph cannot be tapped.
+ */
+import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import type { OutboundBody } from "../types.js";
+
+export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string): OutboundBody[] {
+  const money = new Intl.NumberFormat("pt-BR", { style: "currency", currency });
+  const item = execution.items[instalment - 1];
+  const count = execution.items.length;
+  const bodies: OutboundBody[] = [
+    {
+      kind: "text",
+      text: [
+        count > 1 ? `Parcela ${instalment}/${count}: ` : "",
+        item ? money.format(item.amount / 100) : "",
+        instrument.due_date ? `, vence ${formatDate(instrument.due_date)}` : "",
+        ` — cobranca ${chargeId}`,
+      ].join(""),
+    },
+  ];
+  if (instrument.pix_copy_paste) {
+    bodies.push({ kind: "media", media: "qr", data: instrument.pix_copy_paste });
+    bodies.push({ kind: "instrument", instrument: "pix_copy_paste", value: instrument.pix_copy_paste });
+  }
+  if (instrument.boleto_bank_line) {
+    bodies.push({ kind: "text", text: "Ou pelo boleto, linha digitavel:" });
+    bodies.push({ kind: "instrument", instrument: "boleto_bank_line", value: instrument.boleto_bank_line });
+  }
+  return bodies;
+}
+
+/** `2026-09-30` -> `30/09/2026`. */
+export function formatDate(iso: string): string {
+  const [y, m, d] = iso.split("-");
+  return `${d}/${m}/${y}`;
+}

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/run.ts

@@ -0,0 +1,113 @@
+/**
+ * The conversation loop: the WhatsApp equivalent of `interactive()`, and the
+ * same gates in the same order. The person writes, the model answers, the
+ * core decides, and what the core produced goes back into the conversation.
+ *
+ * The one difference from the terminal, and it is the whole reason the
+ * channel exists as its own thing: on a terminal the operator and the
+ * counterparty are the same pair of eyes, and here they are not. The
+ * approval question and the console go to stderr; only `tell` reaches the
+ * person. Nothing checks that — it is the wiring: `ask` and `say` are
+ * functions this module never hands to the channel.
+ *
+ * The payable artifact is sent the way a person can actually use it: the QR
+ * as an image, and the copy-and-paste as its OWN message underneath, because
+ * a code inside a picture cannot be copied and a code inside a paragraph
+ * cannot be tapped.
+ */
+import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import { handleExecution, type TerminalOptions } from "../../terminal.js";
+import type { Setup } from "../../setup.js";
+import type { OutboundBody } from "../types.js";
+import { instrumentBodies } from "./present.js";
+import type { WhatsAppChannel } from "./index.js";
+
+export interface ConverseOptions {
+  setup: Setup;
+  channel: WhatsAppChannel;
+  approver: { id: string; channel: string };
+  /** The operator's decision when nobody is at a keyboard. The gate runs `mandate`, where there is none to take. */
+  decision?: "approve" | "deny" | "none";
+  waitSeconds?: number | undefined;
+  simulatePayer?: boolean | undefined;
+  /** The operator's console. Never the conversation. */
+  say: (line: string) => void;
+  /** The operator's keyboard, when there is one. Never the conversation. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+}
+
+export interface ConverseResult {
+  turns: number;
+  replies: string[];
+  toolCalls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+/** Keeps outbound messages in the order the run produced them, across await points. */
+class Outbox {
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(private readonly channel: WhatsAppChannel) {}
+
+  push(body: OutboundBody): void {
+    this.chain = this.chain.then(async () => {
+      await this.channel.send(body);
+    });
+  }
+
+  drain(): Promise<void> {
+    return this.chain;
+  }
+}
+
+export async function converse(options: ConverseOptions): Promise<ConverseResult> {
+  const { setup: s, channel, approver, say } = options;
+  const outbox = new Outbox(channel);
+  const replies: string[] = [];
+  const toolCalls: Array<{ name: string; refused: boolean }> = [];
+  let turns = 0;
+
+  const presentInstrument = (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument): Promise<void> => {
+    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency)) outbox.push(body);
+    // Awaited by the poll: the person has the code in hand before the next look, not after the cycle closed.
+    return outbox.drain();
+  };
+
+  const terminalOptions: TerminalOptions = {
+    setup: s,
+    approver,
+    say,
+    tell: (line: string) => outbox.push({ kind: "text", text: line }),
+    presentInstrument,
+    ...(options.decision ? { decision: options.decision } : {}),
+    ...(options.ask ? { ask: options.ask } : {}),
+    ...(options.waitSeconds !== undefined ? { waitSeconds: options.waitSeconds } : {}),
+    ...(options.simulatePayer !== undefined ? { simulatePayer: options.simulatePayer } : {}),
+  };
+
+  // The channel is opened by the caller, which is where an emulator that is not
+  // running has to be reported: by here the run has already started.
+  const runtime = s.makeRuntime();
+  const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, terminalOptions));
+
+  say(`${s.manifest.manifest.name} ${s.manifest.manifest.version} — canal: whatsapp (${channel.backend}) — approval: ${s.mode} — trilho: ${s.railKind} — ${s.kit.labels.mandateWord} ${s.mandate.id}`);
+
+  try {
+    for (;;) {
+      const message = await channel.next();
+      if (!message) break;
+      turns += 1;
+      const result = await loop.turn(message.text);
+      toolCalls.push(...result.tool_calls);
+      // Whatever the execution put in the conversation goes first: the QR before the sentence that explains it.
+      await outbox.drain();
+      if (result.reply.trim()) await channel.say(result.reply);
+      replies.push(result.reply);
+    }
+    await outbox.drain();
+  } finally {
+    await channel.close();
+  }
+
+  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId) };
+}

package/templates/bills-agent/packages/agent-runtime/src/channels/whatsapp/session.ts

@@ -0,0 +1,113 @@
+/**
+ * WhatsApp's own rule, which is not ours and which the simulator obeys
+ * anyway: outside the 24 hours that follow the person's last message, a
+ * business may only send a TEMPLATE that Meta approved in advance. Inside
+ * the window it may write freely.
+ *
+ * The simulator enforces it for the reason a simulator exists: something that
+ * only fails against the real provider is something you discover in
+ * production. A collections agent hits this constantly — the debtor answers
+ * on Tuesday, the charge is paid on Friday, and "recebemos, acordo quitado"
+ * falls outside the window.
+ *
+ * Template APPROVAL is a STUB and cannot be anything else from here: a
+ * template is registered in a Meta Business account, reviewed by Meta, and
+ * given a status we have no way to read without that account. What this holds
+ * is the LOCAL registry — the templates the agent declares it uses, from
+ * `channels/whatsapp/templates.json` — so sending one that was never declared
+ * is refused here instead of 400-ing at Meta. Whether Meta approved it is the
+ * developer's to check, and the README says so.
+ */
+import { templateArity, type WhatsAppTemplate } from "@codespar/agent-core";
+
+export const SESSION_WINDOW_SECONDS = 24 * 60 * 60;
+
+export interface SessionState {
+  /** Unix seconds of the last message the PERSON sent, on the provider's clock. */
+  lastInboundAt?: number | undefined;
+}
+
+/** Why a template send would be refused. `undefined` means it may go. */
+export type TemplateRefusal = { rule: string; detail: string } | undefined;
+
+export class SessionWindow {
+  private readonly templates: Map<string, WhatsAppTemplate>;
+  private lastInboundAt: number | undefined;
+
+  constructor(templates: readonly WhatsAppTemplate[], initial?: SessionState) {
+    this.templates = new Map(templates.map((t) => [t.name, t]));
+    this.lastInboundAt = initial?.lastInboundAt;
+  }
+
+  observeInbound(timestamp: number): void {
+    if (this.lastInboundAt === undefined || timestamp > this.lastInboundAt) this.lastInboundAt = timestamp;
+  }
+
+  /** Seconds left before free-form messages stop being allowed; 0 when the window is shut or was never opened. */
+  remainingSeconds(now: Date): number {
+    if (this.lastInboundAt === undefined) return 0;
+    return Math.max(0, this.lastInboundAt + SESSION_WINDOW_SECONDS - Math.floor(now.getTime() / 1000));
+  }
+
+  open(now: Date): boolean {
+    return this.remainingSeconds(now) > 0;
+  }
+
+  /** The declaration, for a caller that has to build a send: the language is the registry's, never the caller's guess. */
+  declared(name: string): WhatsAppTemplate | undefined {
+    return this.templates.get(name);
+  }
+
+  /**
+   * What the Cloud API would refuse about this template send, decided against
+   * the declaration. Three things are visible to a registry: a name nobody
+   * declared, a language the template was not registered in, and a variable
+   * count the body has no placeholders for. Meta answers each with a 4xx and
+   * delivers nothing, so each is refused here instead.
+   */
+  refuse(body: { template: string; language: string; variables: readonly string[] }): TemplateRefusal {
+    const declared = this.templates.get(body.template);
+    if (!declared) {
+      return {
+        rule: "template_unknown",
+        detail: `the agent declares no template named ${body.template}; Meta only delivers templates it approved, and this one was never registered here`,
+      };
+    }
+    if (declared.language !== body.language) {
+      return {
+        rule: "template_language_unknown",
+        detail: `${body.template} is declared in ${declared.language}, not ${body.language}; a template approved in one language does not exist in another`,
+      };
+    }
+    const expected = templateArity(declared.body);
+    if (body.variables.length !== expected) {
+      return { rule: "template_variables_mismatch", detail: `${body.template} takes ${expected} variable(s) and this send carries ${body.variables.length}` };
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Where a conversation's window stood, read back from a bundle's
+ * `channel.jsonl`. This is what lets a later process — a poll, days after the
+ * run that opened the conversation — know whether it may still write freely,
+ * instead of assuming the worst and always sending a template.
+ *
+ * It reads the PROVIDER's timestamp and never the line's `at`, which is the
+ * run's own clock: the 24 hours are counted by WhatsApp on WhatsApp's clock,
+ * and a record written by a machine whose clock drifted is not evidence about
+ * theirs. A log carrying no provider timestamp on any inbound line yields no
+ * state, and the window then reads as SHUT — the safe direction, because a
+ * template is deliverable in both halves of the rule and a free-form message
+ * is deliverable in one.
+ */
+export function sessionStateFromChannelLog(lines: ReadonlyArray<Record<string, unknown>>): SessionState {
+  let lastInboundAt: number | undefined;
+  for (const line of lines) {
+    if (line["direction"] !== "in") continue;
+    const at = line["provider_timestamp"];
+    if (typeof at !== "number" || !Number.isFinite(at)) continue;
+    if (lastInboundAt === undefined || at > lastInboundAt) lastInboundAt = at;
+  }
+  return { lastInboundAt };
+}