@codespar/cli 0.12.1 → 0.14.0

package/templates/collections-agent/packages/agent-core/src/agent.ts

@@ -0,0 +1,125 @@
+/**
+ * The tool-use loop. The provider says what the model wants; this file
+ * dispatches only the tools `tools.json` names, records every step in the
+ * transcript, and hands payment tools to the engine, which is the only
+ * thing that can move an execution past `drafted`.
+ */
+import type { ProofBundle } from "./bundle.js";
+import type { ExecutionEngine } from "./engine.js";
+import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
+import { isReply } from "./providers/types.js";
+import type { Execution } from "./state-machine.js";
+import type { ToolsFile } from "./tools.js";
+import { allowedToolNames, toolSpecs } from "./tools.js";
+
+export interface ToolContext {
+  engine: ExecutionEngine;
+  /** Fires when a payment tool created an execution; the channel decides what to do with it (ask, or run). */
+  onExecution: (execution: Execution) => Promise<Execution>;
+}
+
+export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+
+export interface AgentLoopOptions {
+  runtime: AgentRuntime;
+  tools: ToolsFile;
+  handlers: Record<string, ToolHandler>;
+  system: string;
+  bundle: ProofBundle;
+  engine: ExecutionEngine;
+  onExecution: ToolContext["onExecution"];
+  /** A hard stop on tool round-trips per turn, so a looping model cannot run forever. */
+  maxSteps?: number;
+  clock?: () => Date;
+}
+
+export interface TurnResult {
+  reply: string;
+  tool_calls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+export class AgentLoop {
+  private readonly messages: ConversationMessage[] = [];
+  private readonly allowed: Set<string>;
+  private readonly specs: ToolSpec[];
+  private readonly clock: () => Date;
+
+  constructor(private readonly options: AgentLoopOptions) {
+    this.allowed = allowedToolNames(options.tools);
+    this.specs = toolSpecs(options.tools);
+    this.clock = options.clock ?? (() => new Date());
+  }
+
+  get history(): readonly ConversationMessage[] {
+    return this.messages;
+  }
+
+  async turn(userText: string): Promise<TurnResult> {
+    const { runtime, bundle } = this.options;
+    const maxSteps = this.options.maxSteps ?? 8;
+    const calls: TurnResult["tool_calls"] = [];
+    const executions: Execution[] = [];
+
+    this.messages.push({ role: "user", content: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+
+    for (let step = 0; step < maxSteps; step += 1) {
+      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      if (isReply(out)) {
+        this.messages.push({ role: "assistant", content: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant_step", reply: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant", text: out.text });
+        return { reply: out.text, tool_calls: calls, executions };
+      }
+
+      this.messages.push({ role: "assistant", content: "", tool_calls: out });
+      bundle.transcript({ at: this.now(), kind: "assistant_step", tool_calls: out });
+
+      for (const call of out) {
+        const result = await this.dispatch(call, executions);
+        calls.push({ name: call.name, refused: result.refused });
+        this.messages.push({ role: "tool", tool_call_id: call.id, name: call.name, content: JSON.stringify(result.content), ...(result.refused ? { is_error: true } : {}) });
+        bundle.transcript({ at: this.now(), kind: "tool_result", tool_call_id: call.id, name: call.name, refused: result.refused, content: result.content });
+      }
+    }
+
+    const text = "I stopped: too many tool steps in one turn. Nothing was paid beyond what the trail shows.";
+    this.messages.push({ role: "assistant", content: text });
+    bundle.transcript({ at: this.now(), kind: "assistant", text, truncated: true });
+    return { reply: text, tool_calls: calls, executions };
+  }
+
+  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+    const { bundle, handlers, engine, onExecution } = this.options;
+    bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
+
+    if (!this.allowed.has(call.name)) {
+      // Section 15, closed tools: a tool outside tools.json is refused, and the refusal is in the trail.
+      bundle.event({ at: this.now(), type: "tool.refused", tool: call.name, reason: "tool_not_allowed", actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_not_allowed", message: `${call.name} is not in this agent's tools.json` } };
+    }
+    const handler = handlers[call.name];
+    if (!handler) return { refused: true, content: { error: "tool_not_implemented", message: `${call.name} has no handler` } };
+
+    try {
+      const content = await handler(call.input, {
+        engine,
+        onExecution: async (execution) => {
+          const settledOrNot = await onExecution(execution);
+          executions.push(settledOrNot);
+          return settledOrNot;
+        },
+      });
+      return { refused: false, content };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      bundle.event({ at: this.now(), type: "tool.error", tool: call.name, message, actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_failed", message } };
+    }
+  }
+
+  private now(): string {
+    return this.clock().toISOString();
+  }
+}

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

@@ -0,0 +1,154 @@
+/**
+ * The CodeSpar receivable rail: the merchant COLLECTS. `pay()` issues a
+ * cobranca com vencimento through `POST /v1/charges` (the REST form of the
+ * `codespar_charge` meta-tool, action=create): `method: "boleto"` plus a
+ * `due_date` is what makes it ONE receivable the payer settles either by
+ * boleto or by Pix; `idempotency_key` is REQUIRED on that create and is our
+ * attempt id, so a retry returns the same charge instead of a second
+ * receivable the same debtor could pay twice. An immediate Pix
+ * (`method: "pix"`) is deliberately not used: the API does not replay its
+ * create on a key and does not read it back, so it cannot close a loop.
+ *
+ * `lookup()` is `GET /v1/charges/{id}`, which accepts our idempotency key as
+ * the id; the kit polls it to close the cycle when no webhook can reach a
+ * terminal. Branching is on `local_status` and the normalized `status`, never
+ * on prose. Amounts cross the wire in MAJOR units (`amount: 1080.5`), which
+ * is what `coerceMetaChargeArgs` reads; the answer's `amount_minor` is
+ * compared with what was asked and a mismatch is a failure, not a charge.
+ *
+ * There is no receipt object for a receivable; the paid charge as the API
+ * reports it is what the bundle keeps, marked `kind: "charge"` and unsealed.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { Actor, ChargeInstrument } from "../types.js";
+import { describeApiError, isUncertain } from "./client.js";
+
+/** The `/v1/charges` answer, as the SDK types it. */
+export interface ChargeView {
+  id: string | null;
+  status: string;
+  local_status: string;
+  status_conflict: boolean;
+  method: string;
+  currency: string;
+  amount: number;
+  amount_minor: number;
+  due_date: string | null;
+  payable: boolean;
+  boleto_bar_code: string | null;
+  boleto_bank_line: string | null;
+  pix_copy_paste: string | null;
+  credit_correlation_armed: boolean;
+  payment_in_flight: boolean;
+  settlement: "confirmed" | "pending" | "unconfirmable" | null;
+  issuance_unconfirmed: boolean;
+}
+
+export function instrumentOf(view: ChargeView): ChargeInstrument {
+  return {
+    payable: view.payable,
+    status: view.status,
+    pix_copy_paste: view.pix_copy_paste,
+    boleto_bank_line: view.boleto_bank_line,
+    boleto_bar_code: view.boleto_bar_code,
+    due_date: view.due_date,
+  };
+}
+
+/** What a charge view means for the attempt. The row's own status wins over the issuer's normalized one where they name a terminal state. */
+export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight" } {
+  if (view.issuance_unconfirmed || !view.id) return { status: "in_flight" };
+  const id = view.id;
+  if (view.local_status === "settled" || view.status === "CONFIRMED" || view.settlement === "confirmed") {
+    return { status: "settled", transaction_id: id, receipt_id: id, money_moved: false, sandbox: true, raw: view };
+  }
+  if (view.local_status === "expired" || view.status === "EXPIRED") {
+    return { status: "failed", code: "charge_expired", message: `charge ${id} reached its due date unpaid`, raw: view };
+  }
+  if (view.status === "CANCELLED" || view.local_status === "cancelled") {
+    return { status: "failed", code: "charge_cancelled", message: `charge ${id} was withdrawn`, raw: view };
+  }
+  return { status: "accepted", transaction_id: id, instrument: instrumentOf(view), sandbox: true, raw: view };
+}
+
+export class CodeSparChargeRail implements PaymentRail {
+  readonly name = "codespar-charge" as const;
+
+  constructor(private readonly api: ApiClient) {}
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    if (!payment.due_date) return { status: "failed", code: "due_date_required", message: "a receivable needs a due_date; the immediate Pix charge cannot be read back or replayed" };
+    let view: ChargeView;
+    try {
+      view = (await this.api.post("/v1/charges", {
+        body: {
+          amount: payment.amount_minor / 100,
+          currency: payment.currency,
+          method: "boleto",
+          description: payment.description ?? payment.purpose,
+          buyer: { name: payment.beneficiary ?? payment.payee, document: payment.payee },
+          due_date: payment.due_date,
+          idempotency_key: payment.attempt_id,
+        },
+      })) as ChargeView;
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (isUncertain(failure) || failure.code === "issuance_unconfirmed") return { status: "uncertain", code: failure.code, message: failure.message };
+      return { status: "failed", code: failure.code, message: failure.message };
+    }
+    if (view.issuance_unconfirmed || !view.id) return { status: "uncertain", code: "issuance_unconfirmed", message: "the issuer's answer to the create was lost; the key is reserved and a later read resolves it" };
+    if (view.amount_minor !== payment.amount_minor) {
+      // The API understood another amount than the one approved. The receivable exists; withdraw it rather than leave a debt nobody approved.
+      const withdrawn = await this.withdraw(view.id);
+      return { status: "failed", code: "amount_mismatch", message: `the API issued ${view.amount_minor} for a request of ${payment.amount_minor} (charge ${view.id}); ${withdrawn ? "withdrawn" : "withdrawal refused, an operator must cancel it"}` };
+    }
+    const outcome = outcomeOf(view);
+    // `in_flight` is excluded above (`issuance_unconfirmed` / no id); the create answers a state, never "still running".
+    return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
+  }
+
+  async lookup(attemptId: string, _payment: RailPayment): Promise<RailLookup> {
+    try {
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: attemptId } })) as ChargeView;
+      return outcomeOf(view);
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      if (failure.status === 409) return { status: "in_flight" };
+      return { status: "uncertain", code: failure.code, message: failure.message };
+    }
+  }
+
+  async receipt(chargeId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    try {
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId } })) as ChargeView;
+      const raw = view as ChargeView & { settled_at?: string };
+      return {
+        receipt_id: chargeId,
+        kind: "charge",
+        state: view.local_status === "settled" ? "paid" : view.local_status,
+        mandate: { id: "n/a" },
+        // The read names no buyer, so the payee is not on this record; the execution's item names the debtor.
+        payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: raw.settled_at ?? new Date().toISOString() },
+        chain: null,
+        receipt_sig: null,
+        actor,
+        raw: view,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  private async withdraw(chargeId: string): Promise<boolean> {
+    try {
+      await this.api.post("/v1/charges/{chargeId}/cancel", { path: { chargeId } });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/templates/collections-agent/packages/agent-core/src/api/client.ts

@@ -0,0 +1,53 @@
+/**
+ * The one place the kit talks to the CodeSpar API. The key is checked for
+ * the `csk_test_` prefix before the client is built, so no live key ever
+ * reaches the network from this repository.
+ */
+import { ApiClient, CodesparApiError, TimeoutError } from "@codespar/sdk";
+import { assertTestKey } from "../secrets.js";
+
+export const DEFAULT_BASE_URL = "https://api.codespar.dev";
+
+export interface CodeSparClientOptions {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export function createCodeSparClient(options: CodeSparClientOptions): ApiClient {
+  const apiKey = assertTestKey(options.apiKey);
+  return new ApiClient({
+    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    apiKey,
+    ...(options.projectId ? { projectId: options.projectId } : {}),
+    timeout: options.timeoutMs ?? 30_000,
+  });
+}
+
+export interface ApiFailure {
+  status: number;
+  code: string;
+  message: string;
+  body?: unknown;
+}
+
+/** Normalise the SDK's two error classes into one readable shape without leaking the body into logs. */
+export function describeApiError(err: unknown): ApiFailure {
+  if (err instanceof TimeoutError) return { status: 0, code: "timeout", message: `request timed out after ${err.timeoutMs}ms` };
+  if (err instanceof CodesparApiError) {
+    const body = err.body as { error?: { code?: string; message?: string } } | undefined;
+    return {
+      status: err.status,
+      code: err.code ?? body?.error?.code ?? (err.status === 0 ? "network" : `http_${err.status}`),
+      message: body?.error?.message ?? err.message,
+      body: err.body,
+    };
+  }
+  return { status: 0, code: "unknown", message: err instanceof Error ? err.message : String(err) };
+}
+
+/** 5xx, timeouts and `psp_dispatch_uncertain` mean "the money may have moved". */
+export function isUncertain(failure: ApiFailure): boolean {
+  return failure.status === 0 || failure.status >= 500 || failure.code === "psp_dispatch_uncertain" || failure.code === "psp_attempt_uncertain";
+}

package/templates/collections-agent/packages/agent-core/src/api/mandate-status.ts

@@ -0,0 +1,58 @@
+/**
+ * Mandate status from the API: `GET /v1/mandates/{id}`, the one registered
+ * spelling of the consumer-allowance point read (the SDK's OpenAPI says the
+ * path has no alias; `/v1/consumers/mandates/{id}` answers 404 on staging,
+ * measured 2026-09-23). Consulted before `executing` (section 4.7), through
+ * the same `csk_test_` client every other call of the kit uses.
+ *
+ * Fail-closed: this source never throws and never assumes. A transport
+ * failure, a timeout, a 404, a 5xx, an unreadable body or a status outside
+ * `active | paused | revoked | expired` is reported as `unknown`, and the
+ * engine executes nothing on `unknown`.
+ *
+ * The organization kill switch (`org pauseAll`) has no API surface, so
+ * `org_paused` is `false` here: the API cannot say it, and this source does
+ * not invent it.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import { z } from "zod";
+import type { MandateStatusReport, MandateStatusSource } from "../revocation.js";
+import { describeApiError } from "./client.js";
+
+/** The two fields of the 14-field projection the gate reads; the rest is passed through untouched. */
+const MandateReadSchema = z
+  .object({
+    status: z.enum(["active", "paused", "revoked", "expired"]),
+    expires_at: z.string(),
+  })
+  .passthrough();
+
+export class ApiMandateStatusSource implements MandateStatusSource {
+  constructor(
+    private readonly api: ApiClient,
+    private readonly clock: () => Date = () => new Date(),
+  ) {}
+
+  async check(mandateId: string): Promise<MandateStatusReport> {
+    const base = { mandate_id: mandateId, org_paused: false, checked_at: this.clock().toISOString(), source: "api" as const };
+    let body: unknown;
+    try {
+      body = await this.api.get("/v1/mandates/{id}", { path: { id: mandateId } });
+    } catch (err) {
+      const failure = describeApiError(err);
+      const detail =
+        failure.status === 404
+          ? `the API has no mandate ${mandateId} for this key (${failure.code})`
+          : `GET /v1/mandates/${mandateId} did not answer (${failure.code}): ${failure.message}`;
+      return { ...base, status: "unknown", detail };
+    }
+    const parsed = MandateReadSchema.safeParse(body);
+    if (!parsed.success) {
+      const status = body && typeof body === "object" && "status" in body ? String((body as { status: unknown }).status) : "missing";
+      return { ...base, status: "unknown", detail: `GET /v1/mandates/${mandateId} answered a status this kit does not read (${status})` };
+    }
+    const expiresAt = new Date(parsed.data.expires_at).getTime();
+    const expired = Number.isFinite(expiresAt) && expiresAt <= this.clock().getTime();
+    return { ...base, status: expired && parsed.data.status === "active" ? "expired" : parsed.data.status };
+  }
+}

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

@@ -0,0 +1,101 @@
+/**
+ * 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";
+
+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,
+        actor,
+        raw: r,
+      };
+    } catch (err) {
+      const failure = describeApiError(err);
+      if (failure.status === 404) return undefined;
+      throw err;
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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. The route is not in the SDK's typed operations yet
+ * (merged 2026-09-23), so it is called by path.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import { describeApiError, type ApiFailure } 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 };
+
+export async function paySandboxCharge(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+  try {
+    const state = (await api.request("post", "/v1/test/charges/{chargeId}/pay" as never, {
+      path: { chargeId: chargeRef },
+      body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
+    } as never)) as SandboxPaidState;
+    return { ok: true, state };
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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 } 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),
+    ...(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" };
+
+/**
+ * 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" };
+  if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
+  return { ok: true };
+}