@codespar/cli 0.17.0 → 0.18.1

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

@@ -0,0 +1,239 @@
+/**
+ * Wires the core for one agent: manifest, guardrails, mandate, state, rail,
+ * status source, signer, bundle, provider. Everything the commands and the
+ * terminal channel share, whatever the agent is; what the agent brings is the
+ * rail, the tool handlers and the policy extension, through its kit.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  AgentLoop,
+  ExecutionEngine,
+  LocalMandateStatusStub,
+  ProofBundle,
+  ReplayRuntime,
+  StateStore,
+  loadGuardrails,
+  loadManifest,
+  loadOrCreateLocalApprovalKey,
+  loadToolsFile,
+  newRunId,
+  resolveFixedClock,
+  type AgentRuntime,
+  type ApprovalMode,
+  type ConversationScript,
+  type Execution,
+  type Guardrails,
+  type LoadedManifest,
+  type Mandate,
+  type MandateStatusSource,
+  type PaymentRail,
+  type StubChargeRailOptions,
+  type StubRailOptions,
+  type ToolContext,
+  type ToolHandler,
+} from "@codespar/agent-core";
+import { AnthropicRuntime } from "@codespar/agent-core/providers/anthropic";
+import type { ApiClient } from "@codespar/sdk";
+import { envName, type Agent } from "./agent.js";
+import type { AgentKit, RailKind, SandboxPayer, Settlement } from "./kit.js";
+
+/** The `.env.example` placeholder counts as no key: a copied example must replay, not call Anthropic with a fake key. */
+export const ANTHROPIC_KEY_PLACEHOLDER = "sk-ant-your_key_here";
+export const CODESPAR_KEY_PLACEHOLDER = "csk_test_your_key_here";
+
+export type ProviderKind = "anthropic" | "replay";
+
+export function stateDirOf(agent: Agent): string {
+  return join(agent.dir, ".codespar");
+}
+
+export function mandatePathOf(agent: Agent): string {
+  return join(stateDirOf(agent), "mandate.json");
+}
+
+/** The runs folder in use: the agent's own, or the scratch one the restart test points at. */
+export function runsDir(agent: Agent, env: NodeJS.ProcessEnv = process.env): string {
+  return env[envName(agent, "RUNS_DIR")] ?? join(agent.dir, "runs");
+}
+
+export interface SetupOptions {
+  mode?: ApprovalMode | undefined;
+  rail?: RailKind | undefined;
+  provider?: ProviderKind | undefined;
+  transcript?: string | undefined;
+  runId?: string | undefined;
+  runsDir?: string | undefined;
+  stateDir?: string | undefined;
+  now?: (() => Date) | undefined;
+  stubRail?: StubRailOptions | StubChargeRailOptions | undefined;
+  /** Use this mandate instead of the local or the example one (scenarios, tests). */
+  mandate?: Mandate | undefined;
+  env?: NodeJS.ProcessEnv;
+  say?: ((line: string) => void) | undefined;
+}
+
+export interface Setup {
+  agent: Agent;
+  kit: AgentKit;
+  settlement: Settlement;
+  manifest: LoadedManifest;
+  guardrails: Guardrails;
+  mode: ApprovalMode;
+  mandate: Mandate;
+  store: StateStore;
+  gate: LocalMandateStatusStub;
+  rail: PaymentRail;
+  railKind: RailKind;
+  api: ApiClient | undefined;
+  status: MandateStatusSource;
+  /** `await-payer` agents only: who plays the counterparty in the sandbox. */
+  payer: SandboxPayer | undefined;
+  /** Milliseconds between two looks at an issued receivable: 0 on the stub. */
+  pollIntervalMs: number;
+  bundle: ProofBundle;
+  runId: string;
+  engine: ExecutionEngine;
+  system: string;
+  handlers: Record<string, ToolHandler>;
+  tools: ReturnType<typeof loadToolsFile>;
+  /**
+   * The conversation this run is bound to, when a channel binds one (WhatsApp):
+   * its contact and its subject. Set by the channel's start, read by a kit
+   * whose rules depend on who the person is — a sale is charged to the
+   * customer the conversation is with, and to nobody else.
+   */
+  conversation?: ConversationScript | undefined;
+  /** `onBatch` is for a channel that takes one gesture per batch; without it every line is decided in `onExecution`. */
+  makeLoop(runtime: AgentRuntime, onExecution: (execution: Execution) => Promise<Execution>, onBatch?: ToolContext["onBatch"]): AgentLoop;
+  makeRuntime(): AgentRuntime;
+  close(): void;
+}
+
+export function readDotEnv(agentDir: string): void {
+  const path = join(agentDir, ".env");
+  if (!existsSync(path)) return;
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const m = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!m || !m[1]) continue;
+    const value = (m[2] ?? "").replace(/^["']|["']$/g, "");
+    if (process.env[m[1]] === undefined) process.env[m[1]] = value;
+  }
+}
+
+export function resolveProvider(env: NodeJS.ProcessEnv, requested: ProviderKind | undefined): ProviderKind {
+  if (requested) return requested;
+  const key = env["ANTHROPIC_API_KEY"]?.trim();
+  return key && key !== ANTHROPIC_KEY_PLACEHOLDER ? "anthropic" : "replay";
+}
+
+export function resolveRailKind(env: NodeJS.ProcessEnv, requested: RailKind | undefined): RailKind {
+  if (requested) return requested;
+  const key = env["CODESPAR_API_KEY"];
+  if (!key || key === CODESPAR_KEY_PLACEHOLDER) return "stub";
+  return "api";
+}
+
+export function setup(agent: Agent, options: SetupOptions = {}): Setup {
+  const env = options.env ?? process.env;
+  const say = options.say ?? ((line: string) => process.stderr.write(line + "\n"));
+  // `--now` on the one-shot, or CODESPAR_AGENT_NOW for every command: the clock the engine, the stubs, the gate and the loop read (#16).
+  const now = options.now ?? resolveFixedClock(undefined, env);
+  const manifest = loadManifest(join(agent.dir, "agent.yaml"));
+  const guardrails = loadGuardrails(manifest.resolvePath(manifest.manifest.guardrails));
+  const tools = loadToolsFile(manifest.resolvePath(manifest.manifest.tools));
+  const system = readFileSync(join(agent.dir, "SYSTEM_PROMPT.md"), "utf8");
+  const mode: ApprovalMode = options.mode ?? manifest.manifest.default_approval;
+  if (!manifest.manifest.approval.includes(mode)) throw new Error(`agent.yaml does not support approval: ${mode}`);
+
+  // <PREFIX>_STATE_DIR / <PREFIX>_RUNS_DIR exist for the restart test, which drives a child process over a scratch state.
+  const stateDir = options.stateDir ?? env[envName(agent, "STATE_DIR")] ?? stateDirOf(agent);
+  const runs = options.runsDir ?? runsDir(agent, env);
+  const store = new StateStore(join(stateDir, "state.db"));
+  const gate = new LocalMandateStatusStub(store, now);
+  const signer = loadOrCreateLocalApprovalKey(stateDir);
+
+  const railKind = resolveRailKind(env, options.rail);
+  const built = agent.kit.buildRail({
+    kind: railKind,
+    env,
+    agentDir: agent.dir,
+    stateDir,
+    manifest,
+    store,
+    gate,
+    now,
+    mandate: options.mandate,
+    stubRail: options.stubRail,
+    envVar: (name) => env[envName(agent, name)],
+  });
+  const { rail, mandate } = built;
+  const status = built.status ?? gate;
+
+  const runId = options.runId ?? newRunId(mode);
+  const bundle = new ProofBundle(runs, runId);
+  bundle.mandateSnapshot(mandate);
+  // Section 11: mode, rail and mandate id. The VERSION rides with the id, so a reader knows which signing of the mandate authorised the run without opening the snapshot.
+  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, mandate_version: mandate.version, started_at: (now ?? (() => new Date()))().toISOString() });
+
+  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails, store });
+  const engine = new ExecutionEngine({
+    store,
+    rail,
+    status,
+    signer,
+    manifest: manifest.manifest,
+    guardrails: { ...guardrails, approval: mode },
+    mandate,
+    bundle,
+    mode,
+    runId,
+    onBehalfOf: mandate.consumer_id,
+    ...(policyExtension ? { policyExtension } : {}),
+    ...(now ? { clock: now } : {}),
+  });
+
+  const makeRuntime = (): AgentRuntime => {
+    const provider = resolveProvider(env, options.provider);
+    if (provider === "anthropic") return new AnthropicRuntime({ apiKey: env["ANTHROPIC_API_KEY"] });
+    if (!options.transcript) throw new Error("the replay provider needs a transcript (--transcript <file> or --scenario <name>)");
+    say(`[replay] no ANTHROPIC_API_KEY: replaying ${options.transcript}`);
+    return ReplayRuntime.fromFile(options.transcript);
+  };
+
+  const s: Setup = {
+    agent,
+    kit: agent.kit,
+    settlement: agent.settlement,
+    manifest,
+    guardrails,
+    mode,
+    mandate,
+    store,
+    gate,
+    rail,
+    railKind,
+    api: built.api,
+    status,
+    payer: built.payer,
+    pollIntervalMs: built.pollIntervalMs ?? 0,
+    bundle,
+    runId,
+    engine,
+    system,
+    handlers: {},
+    tools,
+    makeRuntime,
+    makeLoop: (runtime, onExecution, onBatch) => new AgentLoop({ runtime, tools, handlers: s.handlers, system, bundle, engine, onExecution, ...(onBatch ? { onBatch } : {}), ...(now ? { clock: now } : {}) }),
+    close: () => store.close(),
+  };
+  s.handlers = agent.kit.handlers(s);
+  return s;
+}
+
+export class NoMandateError extends Error {
+  constructor() {
+    super("no signed mandate yet: run `npm run consent -- --yes` first (or `npm start` without --input, which starts the consent when a test key is present)");
+    this.name = "NoMandateError";
+  }
+}

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

@@ -0,0 +1,263 @@
+/**
+ * The terminal channel: what `codespar-agent start` opens. No account, no
+ * server. It shows what the core decided, asks the person when an execution
+ * is awaiting approval, and prints where the sealed outcome landed. The
+ * words are the agent's (`kit.labels`, `kit.describeExecution`); the order
+ * of the gates is the runner's and is the same for every agent.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin, stderr, stdout } from "node:process";
+import { relative } from "node:path";
+import type { AgentRuntime, BatchGesture, BatchPresentation, ChargeInstrument, Execution } from "@codespar/agent-core";
+import { pollUntilClosed, type PollResult } from "./poll.js";
+import type { Setup } from "./setup.js";
+
+export interface TerminalOptions {
+  setup: Setup;
+  approver: { id: string; channel: string };
+  /** Non-interactive decision for a one-shot: approve, deny, or leave it awaiting. */
+  decision?: "approve" | "deny" | "none";
+  /** `await-payer` only: seconds to wait for the payer after issuing. */
+  waitSeconds?: number | undefined;
+  /** `await-payer` only: let the sandbox payer act once the receivable is payable. */
+  simulatePayer?: boolean | undefined;
+  say?: ((line: string) => void) | undefined;
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /**
+   * Where the lines for the counterparty go (the conversation); `say` is the
+   * operator's console. `about` is the execution whose OUTCOME the line tells,
+   * so a channel can tie a failed delivery of it back to that outcome.
+   */
+  tell?: ((line: string, about?: Execution) => void) | undefined;
+  /**
+   * How a payable receivable is put in front of the counterparty. Defaults to
+   * the kit's own, which writes lines to a console. A channel overrides it,
+   * because a QR on WhatsApp is an image and the copy-and-paste is its own
+   * message, and neither of those is a line of text.
+   */
+  presentInstrument?: ((execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void) => void | Promise<void>) | undefined;
+  /**
+   * The gestures taken on whole batches in this session, by batch ref. When a
+   * line of a batch arrives and its ref is here, the line is decided by the
+   * gesture instead of by a question; see `presentBatch`.
+   */
+  gestures?: BatchGestures | undefined;
+}
+
+/** One gesture per batch ref: the list it was taken on, and the positions vetoed. */
+export type BatchGestures = Map<string, BatchGestureRecord>;
+type BatchGestureRecord = { batch_hash: string; count: number; vetoed: Set<number> };
+
+export function describeExecution(execution: Execution, setup: Setup): string[] {
+  return setup.kit.describeExecution(execution, setup);
+}
+
+/** The one message per outcome, recorded so a duplicate event never sends it twice. */
+export function announceOutcome(execution: Execution, setup: Setup, tell: (line: string) => void): boolean {
+  return setup.kit.announceOutcome?.(execution, setup, tell) ?? false;
+}
+
+/** The kit's follow-up to an outcome. Never throws: what follows a paid order cannot un-pay it. */
+export async function followUp(execution: Execution, setup: Setup, say: (line: string) => void): Promise<void> {
+  if (!setup.kit.followUp) return;
+  try {
+    await setup.kit.followUp(execution, setup, say);
+  } catch (err) {
+    say(`  follow-up of ${execution.id} failed and changed nothing about it: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function receiptLines(execution: Execution, setup: Setup, say: (line: string) => void): void {
+  for (const outcome of execution.outcomes) {
+    if (outcome.receipt_id) say(`  ${setup.kit.labels.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+  }
+}
+
+/** Decides an `awaiting_approval` execution and runs an `approved` one. Returns the final execution of this pass. */
+export async function handleExecution(execution: Execution, options: TerminalOptions): Promise<Execution> {
+  const { setup, approver } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
+  const labels = setup.kit.labels;
+  const engine = setup.engine;
+
+  for (const line of describeExecution(execution, setup)) say(line);
+
+  let current = execution;
+  if (current.state === "awaiting_approval") {
+    const gesture = options.decision === undefined && current.batch ? options.gestures?.get(current.batch.ref) : undefined;
+    if (gesture) {
+      current = decideByGesture(current, gesture, setup, approver);
+    } else {
+      let decision = options.decision;
+      if (!decision) {
+        if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
+        const ask = options.ask ?? defaultAsk;
+        const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
+        decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
+      }
+      if (decision === "approve") current = engine.approve(current.id, approver);
+      else if (decision === "deny") current = engine.deny(current.id, approver);
+      else {
+        say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
+        return current;
+      }
+    }
+    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+  }
+
+  // An agent that issues on request (`executeOnApproval: false`) leaves the approved execution for its own tool to issue.
+  if (current.state === "approved" && setup.kit.executeOnApproval !== false) {
+    current = await engine.execute(current.id);
+    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    if (setup.settlement === "immediate") {
+      receiptLines(current, setup, say);
+      if (current.state === "executing") say(labels.uncertainDispatch);
+    }
+  }
+
+  if (setup.settlement === "await-payer") {
+    if (current.state === "executing" && current.reason === "awaiting_settlement") {
+      const result = await waitForPayer(current.id, options);
+      current = result.execution;
+      say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""} apos ${result.rounds} consulta(s), ${result.seconds}s${result.timed_out ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`);
+      receiptLines(current, setup, say);
+    } else if (current.state === "executing") {
+      say(labels.uncertainDispatch);
+    }
+    const told = current;
+    announceOutcome(told, setup, (line) => tell(line, told));
+    await followUp(current, setup, say);
+  }
+  return current;
+}
+
+/**
+ * A line of a batch the person already decided on as a list. The gesture
+ * approves or vetoes a POSITION in ONE list: a line that names another list
+ * under the same ref is not covered by it, and "todas" must not become a yes
+ * to a list nobody was shown. `approve` still runs the policy and still mints
+ * this line's own artifact, which carries the `batch_hash` the gesture was
+ * taken on — that is what makes the gesture attested rather than asserted.
+ */
+function decideByGesture(execution: Execution, gesture: BatchGestureRecord, setup: Setup, approver: TerminalOptions["approver"]): Execution {
+  const engine = setup.engine;
+  const { batch_hash, index, count } = execution.batch!;
+  if (batch_hash !== gesture.batch_hash || count !== gesture.count) {
+    return engine.deny(execution.id, approver, `the list changed after the gesture: it was taken on ${gesture.count} line(s) hashing to ${gesture.batch_hash}, and this line belongs to ${count} hashing to ${batch_hash}`);
+  }
+  if (gesture.vetoed.has(index)) return engine.deny(execution.id, approver, `vetoed in the batch gesture (line ${index + 1} of ${count})`);
+  return engine.approve(execution.id, approver);
+}
+
+/**
+ * What the person answered to a whole list, or `undefined` when the answer
+ * cannot be read as one. Lines are numbered from 1, as they were shown.
+ * "todas" / "all", "todas exceto 3,7" / "all except 3,7", and "nenhuma" /
+ * "none" (also an empty answer: the default is no, as it is per line). A
+ * number outside the list is unreadable rather than ignored, because a typo
+ * that silently vetoed nothing would pay the line the person meant to stop.
+ */
+export function parseBatchGesture(answer: string, count: number): { vetoed: number[] } | undefined {
+  const text = answer.trim().toLowerCase();
+  const all = Array.from({ length: count }, (_, i) => i);
+  if (text === "" || text === "nenhuma" || text === "none" || text === "n" || text === "nao") return { vetoed: all };
+  if (text === "todas" || text === "all") return { vetoed: [] };
+  const except = /^(?:todas|all)\s+(?:exceto|except)\s+([\d\s,]+)$/.exec(text);
+  if (!except) return undefined;
+  const numbers = except[1]!.split(/[\s,]+/).filter(Boolean).map(Number);
+  if (numbers.length === 0 || numbers.some((n) => !Number.isInteger(n) || n < 1 || n > count)) return undefined;
+  return { vetoed: [...new Set(numbers.map((n) => n - 1))].sort((a, b) => a - b) };
+}
+
+/**
+ * Section 3, for a list: the person sees every line, the total and the hash
+ * prefix, and answers once. What they answer is recorded in the bundle as a
+ * `batch.gesture` event and kept for the lines that follow; each line is then
+ * decided by `decideByGesture` when it arrives, and each one it approves mints
+ * its own artifact as before.
+ */
+export async function presentBatch(batch: BatchPresentation, options: TerminalOptions & { gestures: BatchGestures }): Promise<BatchGesture> {
+  const { setup, approver } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const ask = options.ask ?? defaultAsk;
+  say(`  lote ${batch.ref} — ${batch.label}: ${batch.count} linha(s), total ${batch.total}, batch_hash ${batch.batch_hash.slice(0, 19)}…`);
+  for (const line of batch.lines) {
+    const note =
+      line.status === "already_settled"
+        ? " (ja paga; nao roda de novo)"
+        : line.status === "in_progress"
+          ? " (em andamento; nao roda de novo)"
+          : line.status === "attempt_id_conflict"
+            ? " (tentativa presa a outro pagamento; nao roda de novo)"
+            : "";
+    say(`    ${line.index + 1}. ${line.beneficiary}: ${line.amount}${note}`);
+  }
+  let parsed: { vetoed: number[] } | undefined;
+  while (!parsed) {
+    parsed = parseBatchGesture(await ask("  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] "), batch.count);
+    if (!parsed) say(`  nao entendi; responda todas, todas exceto <numeros de 1 a ${batch.count}> ou nenhuma`);
+  }
+  const vetoed = new Set(parsed.vetoed);
+  const gesture: BatchGesture = { batch_hash: batch.batch_hash, approved: batch.lines.map((l) => l.index).filter((i) => !vetoed.has(i)), vetoed: parsed.vetoed };
+  options.gestures.set(batch.ref, { batch_hash: batch.batch_hash, count: batch.count, vetoed });
+  setup.engine.note("batch.gesture", null, { batch_ref: batch.ref, batch_hash: batch.batch_hash, count: batch.count, total_minor: batch.total_minor, approved: gesture.approved, vetoed: gesture.vetoed, approver: { type: "human", id: approver.id, channel: approver.channel } });
+  say(`  -> lista ${gesture.vetoed.length === 0 ? "aprovada inteira" : gesture.approved.length === 0 ? "negada inteira" : `aprovada exceto ${gesture.vetoed.map((i) => i + 1).join(", ")}`}`);
+  return gesture;
+}
+
+export async function waitForPayer(executionId: string, options: TerminalOptions): Promise<PollResult> {
+  const { setup } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
+  const waitSeconds = options.waitSeconds ?? (setup.railKind === "api" ? 60 : 0);
+  return pollUntilClosed(setup.engine, executionId, {
+    intervalMs: setup.pollIntervalMs,
+    timeoutMs: waitSeconds * 1000,
+    payer: options.simulatePayer ? setup.payer : undefined,
+    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell),
+    onWait: (_e, round) => {
+      const line = setup.kit.labels.waitingForPayer?.(round);
+      if (setup.railKind === "api" && line !== undefined && round % 5 === 0) say(line);
+    },
+  });
+}
+
+let rl: ReturnType<typeof createInterface> | undefined;
+
+export function defaultAsk(question: string): Promise<string> {
+  rl ??= createInterface({ input: stdin, output: stderr });
+  return rl.question(question);
+}
+
+export function closeTerminal(): void {
+  rl?.close();
+  rl = undefined;
+}
+
+export async function interactive(options: TerminalOptions & { runtime: AgentRuntime }): Promise<void> {
+  const { setup } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const labels = setup.kit.labels;
+  // Interactive only: a person at the keyboard can decide a list in one go. The one-shot and the scenario runner pass one decision to every line and never reach this.
+  const gestures: BatchGestures = new Map();
+  const withGestures = { ...options, gestures };
+  const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, withGestures), (batch) => presentBatch(batch, withGestures));
+  say(`${setup.manifest.manifest.name} ${setup.manifest.manifest.version} — approval: ${setup.mode} — trilho: ${setup.railKind} — ${labels.mandateWord} ${setup.mandate.id}`);
+  say(`run ${setup.runId} — bundle em ${relative(process.cwd(), setup.bundle.dir)}`);
+  say(labels.intro);
+  for (;;) {
+    let text: string;
+    try {
+      text = await defaultAsk(labels.prompt);
+    } catch {
+      break;
+    }
+    const trimmed = text.trim();
+    if (!trimmed) continue;
+    if (["sair", "exit", "quit"].includes(trimmed.toLowerCase())) break;
+    const result = await loop.turn(trimmed);
+    stdout.write(result.reply + "\n");
+  }
+  closeTerminal();
+}

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

@@ -0,0 +1,131 @@
+/**
+ * The webhook channel: the OTHER way the cycle closes. The CodeSpar API
+ * delivers `commerce.charge.*` to a trigger's URL; a terminal kit has no
+ * URL the API can reach, so the default is the poll (`poll.ts`) and this
+ * receiver is what a developer wires when they do have one.
+ *
+ * STUB, on purpose: it does not register a trigger (that is
+ * `POST /v1/triggers` with `events: ["commerce.charge.paid", ...]`, done
+ * once with the CLI or the dashboard), it does not expose itself to the
+ * internet, and it holds no key. What it does is the receiving contract:
+ *
+ *   POST <url>
+ *   Content-Type: application/json
+ *   X-CodeSpar-Event: commerce.charge.paid
+ *   X-CodeSpar-Event-Id: evt_...
+ *   X-CodeSpar-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>
+ *   { "id": "evt_...", "type": "commerce.charge.paid", "source": "celcoin", "occurred_at": "...", "data": { "payment_id": "<charge id>", ... } }
+ *
+ * The body is handed to `engine.ingestExternalEvent` by the rail's charge id
+ * (`data.payment_id`), which the kit recorded when the attempt was accepted.
+ * Duplicates are dropped by event id, `paid` after `expired` (or the other
+ * way round) moves nothing, and the debtor is told once. With a trigger
+ * secret the signature is verified and a bad one is 401; without one, the
+ * receiver is unauthenticated and says so on start.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { Execution, ExecutionEngine } from "@codespar/agent-core";
+
+export interface WebhookDelivery {
+  id: string;
+  type: string;
+  source?: string;
+  occurred_at?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface WebhookHandlerOptions {
+  engine: ExecutionEngine;
+  /** The trigger's HMAC secret (`POST /v1/triggers` returns it once). Without it, no signature is checked. */
+  secret?: string | undefined;
+  /** Seconds a signature timestamp may be off. */
+  toleranceSeconds?: number;
+  clock?: () => Date;
+  /** What to do with an execution the delivery closed (tell the payer, fetch the record). */
+  onClosed?: (execution: Execution) => Promise<void> | void;
+}
+
+export interface WebhookResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+export function verifySignature(secret: string, header: string | undefined, body: string, now: Date, toleranceSeconds: number): { ok: true } | { ok: false; reason: string } {
+  if (!header) return { ok: false, reason: "missing X-CodeSpar-Signature" };
+  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
+  const t = parts["t"];
+  const v1 = parts["v1"];
+  if (!t || !v1) return { ok: false, reason: "malformed signature header" };
+  const skew = Math.abs(now.getTime() / 1000 - Number(t));
+  if (!Number.isFinite(skew) || skew > toleranceSeconds) return { ok: false, reason: "signature timestamp outside tolerance" };
+  const expected = createHmac("sha256", secret).update(`${t}.${body}`, "utf8").digest("hex");
+  if (expected.length !== v1.length || !timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"))) return { ok: false, reason: "signature mismatch" };
+  return { ok: true };
+}
+
+export function chargeIdOf(delivery: WebhookDelivery): string | undefined {
+  const data = delivery.data ?? {};
+  for (const key of ["payment_id", "charge_id", "external_reference"]) {
+    const v = data[key];
+    if (typeof v === "string" && v) return v;
+  }
+  return undefined;
+}
+
+/** The pure handler: headers and raw body in, status and body out. The HTTP server below is a thin wrapper. */
+export function createWebhookHandler(options: WebhookHandlerOptions) {
+  const clock = options.clock ?? (() => new Date());
+  return async (headers: Record<string, string | undefined>, rawBody: string): Promise<WebhookResponse> => {
+    if (options.secret) {
+      const check = verifySignature(options.secret, headers["x-codespar-signature"], rawBody, clock(), options.toleranceSeconds ?? 300);
+      if (!check.ok) return { status: 401, body: { error: "bad_signature", reason: check.reason } };
+    }
+    let delivery: WebhookDelivery;
+    try {
+      delivery = JSON.parse(rawBody) as WebhookDelivery;
+    } catch {
+      return { status: 400, body: { error: "invalid_json" } };
+    }
+    if (typeof delivery.id !== "string" || typeof delivery.type !== "string") return { status: 400, body: { error: "invalid_delivery", reason: "id and type are required" } };
+    if (!delivery.type.startsWith("commerce.charge.")) return { status: 200, body: { applied: false, reason: `event type ${delivery.type} is not a charge event` } };
+    const chargeId = chargeIdOf(delivery);
+    if (!chargeId) return { status: 200, body: { applied: false, reason: "delivery names no charge" } };
+    const before = options.engine.list({ state: "executing" }).map((e) => e.id);
+    const result = options.engine.ingestExternalEvent({ event_id: delivery.id, type: delivery.type, transaction_id: chargeId, ...(delivery.occurred_at ? { at: delivery.occurred_at } : {}) });
+    if (result.applied) {
+      for (const id of before) {
+        const after = options.engine.get(id);
+        if (after && after.state !== "executing") {
+          await options.engine.collectReceipts(after.id);
+          await options.onClosed?.(after);
+        }
+      }
+    }
+    // Always 2xx once the delivery was read: the API retries on anything else, and a duplicate or a late event is not an error.
+    return { status: 200, body: { applied: result.applied, reason: result.reason } };
+  };
+}
+
+export function startWebhookServer(port: number, options: WebhookHandlerOptions, say: (line: string) => void): Server {
+  const handle = createWebhookHandler(options);
+  const server = createServer((req, res) => {
+    if (req.method !== "POST") {
+      res.writeHead(405).end();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => {
+      const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k.toLowerCase(), Array.isArray(v) ? v[0] : v]));
+      void handle(headers, Buffer.concat(chunks).toString("utf8")).then((out) => {
+        res.writeHead(out.status, { "content-type": "application/json" }).end(JSON.stringify(out.body));
+      });
+    });
+  });
+  server.listen(port, () => {
+    say(`webhook receiver on http://127.0.0.1:${port}/ (${options.secret ? "signature verified" : "UNAUTHENTICATED: set the trigger secret to verify deliveries"})`);
+    say("register the URL once: codespar triggers create --events commerce.charge.paid,commerce.charge.expired,commerce.charge.cancelled --url <public url>");
+  });
+  return server;
+}