@codespar/cli 0.16.0 → 0.18.0

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

@@ -0,0 +1,180 @@
+/**
+ * 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, ChannelLogLine, Conversation } from "../types.js";
+import { WhatsAppChannel } from "./index.js";
+import { 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;
+  /** What earlier runs wrote for this conversation: a status about one of their messages is tied back to it. */
+  priorLines?: ReadonlyArray<ChannelLogLine> | undefined;
+}
+
+/**
+ * How long a command that has just told an outcome waits for status webhooks
+ * before it reports the outcome as told. A provider reports a failed delivery
+ * AFTER the send answered, and a process that has exited hears nothing; this
+ * bounds the wait. `WHATSAPP_STATUS_GRACE_MS` overrides it (0 turns it off).
+ */
+export function statusGraceMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = Number(env["WHATSAPP_STATUS_GRACE_MS"]);
+  return Number.isFinite(raw) && raw >= 0 && env["WHATSAPP_STATUS_GRACE_MS"]?.trim() ? raw : 1000;
+}
+
+/** The cursor that says an outcome's message came back `failed`, so a later poll reports it as not told rather than as told. */
+export function undeliveredCursor(executionId: string, state: string): string {
+  return `undelivered:${executionId}:${state}`;
+}
+
+/**
+ * A `failed` status is an event in the proof bundle, always. When the message
+ * told an outcome it is `message.debtor.failed`, and the cursor above is taken:
+ * the cursor that says the person was told (`markTold`) stays held — a failed
+ * delivery is not retried by itself, because the usual cause (not a WhatsApp
+ * number, blocked) fails again — but nothing reports that outcome as told.
+ */
+export function recordDeliveryFailure(s: Setup, line: ChannelLogLine): void {
+  const payload = { message_id: line.message_id, errors: line.errors ?? [], channel: "whatsapp" };
+  if (!line.about) {
+    s.engine.note("message.failed", null, payload);
+    return;
+  }
+  s.store.setCursor(undeliveredCursor(line.about.execution_id, line.about.state), JSON.stringify(payload));
+  s.engine.note("message.debtor.failed", line.about.execution_id, { ...payload, state: line.about.state });
+}
+
+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}:${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 } : {}),
+    ...(options.priorLines ? { priorLines: options.priorLines } : {}),
+    onDeliveryFailed: (line) => recordDeliveryFailure(s, line),
+  });
+
+  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/checkout-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/checkout-agent/packages/agent-runtime/src/channels/whatsapp/run.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { statusGraceMs } from "./open.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);
+  let toldOutcome = false;
+  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, about?: Execution) => {
+      if (about) toldOutcome = true;
+      outbox.push({ kind: "text", text: line, ...(about ? { about: { execution_id: about.id, state: about.state } } : {}) });
+    },
+    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();
+    // An outcome told in this run may still come back failed; give the provider its bounded moment before the receiver closes.
+    if (toldOutcome) await channel.settle(statusGraceMs());
+  } finally {
+    await channel.close();
+  }
+
+  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId) };
+}

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

@@ -0,0 +1,127 @@
+/**
+ * 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;
+  /** The provider said the window is shut (131047) after ours read it open. Holds until the person writes again. */
+  private shutByProvider = false;
+
+  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;
+      this.shutByProvider = false;
+    }
+  }
+
+  /**
+   * The provider refused a free-form message because its window is shut. Its
+   * clock is the one the 24 hours are counted on, so from here the window
+   * reads shut whatever ours says, and the next message is a template.
+   */
+  observeProviderShut(): void {
+    this.shutByProvider = true;
+  }
+
+  /** 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 || this.shutByProvider) 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 };
+}

package/templates/checkout-agent/packages/agent-runtime/src/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * `codespar-agent <command> [args]`. The agent is the working directory; the
+ * command is this runner's, the same for every agent. What differs between
+ * agents is behind `kit`.
+ */
+import { stderr } from "node:process";
+import { loadAgent, type Agent } from "./agent.js";
+import { readDotEnv } from "./setup.js";
+import { check } from "./commands/check.js";
+import { decide } from "./commands/decide.js";
+import { runEval } from "./commands/eval.js";
+import { inspect } from "./commands/inspect.js";
+import { poll } from "./commands/poll.js";
+import { reconcile } from "./commands/reconcile.js";
+import { rerun } from "./commands/rerun.js";
+import { resume } from "./commands/resume.js";
+import { start } from "./commands/start.js";
+import { verify } from "./commands/verify.js";
+import { webhook } from "./commands/webhook.js";
+
+const COMMANDS = ["start", "consent", "approve", "deny", "resume", "rerun", "reconcile", "inspect", "poll", "webhook", "check", "eval", "verify"] as const;
+
+/** Commands that are not about an agent. `verify` reads a receipt file and a
+ *  public key set, which is all a party outside CodeSpar has: requiring an
+ *  `agent.yaml` above the working directory would mean the verifier needed the
+ *  agent that produced the receipt, and the whole point is that it does not. */
+const AGENTLESS: readonly string[] = ["verify"];
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const rest = [...argv];
+  let dir: string | undefined;
+  const at = rest.indexOf("--agent");
+  if (at >= 0) {
+    dir = rest[at + 1];
+    rest.splice(at, dir === undefined ? 1 : 2);
+  }
+  const first = rest[0];
+  const command = first !== undefined && !first.startsWith("-") ? rest.shift()! : "start";
+  if (!(COMMANDS as readonly string[]).includes(command)) {
+    stderr.write(`unknown command ${command}; one of: ${COMMANDS.join(", ")}\n`);
+    return 2;
+  }
+  if (AGENTLESS.includes(command)) return verify(rest);
+  const agent = await loadAgent(dir);
+  readDotEnv(agent.dir);
+  return run(agent, command, rest);
+}
+
+async function run(agent: Agent, command: string, argv: string[]): Promise<number> {
+  const awaitsPayer = agent.settlement === "await-payer";
+  switch (command) {
+    case "start":
+      return start(agent, argv);
+    case "consent": {
+      if (!agent.kit.consent) {
+        stderr.write(`${agent.slug}: this agent has no consent step (its policy is its own file, not a signed mandate)\n`);
+        return 2;
+      }
+      return agent.kit.consent({ agentDir: agent.dir, argv, say: (l) => void stderr.write(l + "\n") });
+    }
+    case "approve":
+      return decide(agent, "approve", argv);
+    case "deny":
+      return decide(agent, "deny", argv);
+    case "resume":
+      return resume(agent, argv);
+    case "rerun":
+      return rerun(agent, argv);
+    case "reconcile":
+      return reconcile(agent, argv);
+    case "inspect":
+      return inspect(agent, argv);
+    case "check":
+      return check(agent, argv);
+    case "eval":
+      return runEval(agent, argv);
+    case "poll":
+    case "webhook": {
+      if (!awaitsPayer) {
+        stderr.write(`${agent.slug}: ${command} is for an agent that waits for a payer; this one settles on the rail's answer\n`);
+        return 2;
+      }
+      return command === "poll" ? poll(agent, argv) : webhook(agent, argv);
+    }
+    default:
+      stderr.write(`unknown command ${command}\n`);
+      return 2;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+}

package/templates/checkout-agent/packages/agent-runtime/src/commands/check.ts

@@ -0,0 +1,15 @@
+/**
+ * `codespar-agent check [--json]`: the manifest-coherence gate of section 4.3.
+ */
+import { stderr, stdout } from "node:process";
+import { checkAgent } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+
+export function check(agent: Agent, argv: string[]): number {
+  const json = argv.includes("--json");
+  const report = checkAgent(agent.dir);
+  if (json) stdout.write(JSON.stringify(report) + "\n");
+  for (const f of report.findings) stderr.write(`${f.level === "error" ? "ERROR" : "warn "} ${f.code}: ${f.message}\n`);
+  stderr.write(report.ok ? `check ok: ${report.agent} agrees with its agent.yaml\n` : `check FAILED for ${report.agent ?? "agent"}\n`);
+  return report.ok ? 0 : 1;
+}

package/templates/checkout-agent/packages/agent-runtime/src/commands/decide.ts

@@ -0,0 +1,63 @@
+/**
+ * `codespar-agent approve|deny <execution-id> [--user <id>] [--json]`:
+ * decides an execution left in `awaiting_approval` (a `--input` run without
+ * `--approve`, a restart). Produces the section 4.2 artifact and runs the
+ * execution through the same last gate `start` uses.
+ */
+import { relative } from "node:path";
+import { stderr, stdout } from "node:process";
+import type { Agent } from "../agent.js";
+import { setup } from "../setup.js";
+import { handleExecution } from "../terminal.js";
+
+export async function decide(agent: Agent, decision: "approve" | "deny", argv: string[]): Promise<number> {
+  const awaitsPayer = agent.settlement === "await-payer";
+  const json = argv.includes("--json");
+  const user = argv.includes("--user") ? argv[argv.indexOf("--user") + 1] : undefined;
+  const wait = awaitsPayer && argv.includes("--wait") ? Number(argv[argv.indexOf("--wait") + 1]) : undefined;
+  const simulatePayer = awaitsPayer && argv.includes("--simulate-payer");
+  const executionId = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--user" && (!awaitsPayer || argv[i - 1] !== "--wait"));
+  const say = (l: string) => stderr.write(l + "\n");
+  if (!executionId) {
+    say(`usage: npm run ${decision} <execution-id> [--user <id>]${awaitsPayer ? " [--wait <seconds>] [--simulate-payer]" : ""} [--json]`);
+    return 2;
+  }
+  const s = setup(agent, { say, runId: `run_${decision}_${Date.now().toString(36)}` });
+  try {
+    const execution = s.engine.get(executionId);
+    if (!execution) {
+      say(`unknown execution ${executionId}`);
+      return 1;
+    }
+    if (execution.state !== "awaiting_approval") {
+      say(`${executionId} is ${execution.state}, not awaiting_approval; nothing to decide`);
+      return 1;
+    }
+    const final = await handleExecution(execution, {
+      setup: s,
+      approver: { id: user ?? s.kit.labels.defaultUser, channel: "terminal" },
+      decision,
+      say,
+      ...(json ? { tell: say } : {}),
+      waitSeconds: wait,
+      simulatePayer,
+    });
+    if (json) {
+      stdout.write(
+        JSON.stringify({
+          execution_id: final.id,
+          state: final.state,
+          reason: final.reason ?? null,
+          approval_id: final.approval_id ?? null,
+          ...(awaitsPayer ? { charge_ids: final.outcomes.map((o) => o.transaction_id ?? null) } : {}),
+          receipt_ids: final.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+          bundle_dir: relative(process.cwd(), s.bundle.dir),
+        }) + "\n",
+      );
+    }
+    if (awaitsPayer) return final.state === "executing" && final.reason !== "awaiting_settlement" ? 3 : 0;
+    return final.state === "executing" ? 3 : 0;
+  } finally {
+    s.close();
+  }
+}