@codespar/cli 0.13.0 → 0.14.0

package/templates/bills-agent/packages/agent-core/src/stubs/charge-rail.ts

@@ -0,0 +1,193 @@
+/**
+ * STUB receivable rail. The deterministic stand-in for `POST /v1/charges`
+ * plus the sandbox payer, so the collections scenarios, the adversarial
+ * suite and the restart test run offline. Every issuance is persisted in
+ * state.db before the outcome is returned, so a process killed right after
+ * "the charge was issued" finds it again on `resume`.
+ *
+ * The fixture payer lives in the lookups: the first look after issuance
+ * finds the instrument registered (a cobranca com vencimento answers
+ * PROCESSING at create and PENDING once the clearing house has it), the
+ * second look finds what the payer did: paid (default), let it expire, or
+ * nothing yet. With a real key the scenario runner calls the sandbox pay
+ * route instead; this file never talks to the network.
+ */
+import { sha256Hex } from "../hash.js";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { StateStore } from "../state/store.js";
+import type { Actor, ChargeInstrument } from "../types.js";
+
+export type StubPayerBehaviour = "pays" | "expires" | "never";
+
+export interface StubChargeRailOptions {
+  clock?: () => Date;
+  /** What the fixture payer does with a receivable, once it is payable. */
+  payer?: StubPayerBehaviour;
+  /** Debtor documents the issuer refuses (`failed` issuance), to script a partial failure. */
+  refusePayees?: string[];
+  /** Attempt ids whose create answers `uncertain` once (the issuer's answer was lost); the reservation still exists and a later look finds it. */
+  uncertainOnce?: string[];
+  /** Test hook: called after the issuance is persisted and before the outcome is returned. */
+  afterDispatch?: (attemptId: string) => void;
+}
+
+interface PayerState {
+  looks: number;
+  fate: StubPayerBehaviour;
+}
+
+const CURSOR = (attemptId: string) => `stub-charge-payer:${attemptId}`;
+
+export class StubChargeRail implements PaymentRail {
+  readonly name = "stub-charge" as const;
+  private readonly clock: () => Date;
+  private fate: StubPayerBehaviour;
+  private readonly uncertainPending: Set<string>;
+  /** How many NEW receivables pay() issued. */
+  issueCount = 0;
+
+  constructor(
+    private readonly store: StateStore,
+    private readonly options: StubChargeRailOptions = {},
+  ) {
+    this.clock = options.clock ?? (() => new Date());
+    this.fate = options.payer ?? "pays";
+    this.uncertainPending = new Set(options.uncertainOnce ?? []);
+  }
+
+  /** Changes what the fixture payer does with the receivables issued from now on. */
+  setPayer(behaviour: StubPayerBehaviour): void {
+    this.fate = behaviour;
+  }
+
+  /** Scripts the payer for ONE already-issued receivable (a scenario that pays or expires a specific parcel). */
+  decide(attemptId: string, behaviour: StubPayerBehaviour): void {
+    const state = this.payerState(attemptId);
+    this.savePayerState(attemptId, { looks: state?.looks ?? 0, fate: behaviour });
+  }
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    const existing = this.store.stubRailGet(payment.attempt_id);
+    if (existing) return existing.outcome as RailOutcome;
+
+    if (this.uncertainPending.has(payment.attempt_id)) {
+      this.uncertainPending.delete(payment.attempt_id);
+      // The issuer took the create and the answer was lost: the reservation exists, so a later lookup finds it.
+      this.persistIssued(payment, "PROCESSING", false);
+      return { status: "uncertain", code: "issuance_unconfirmed", message: "stub: the issuer's answer to the create was lost; the key is reserved" };
+    }
+
+    const at = this.clock().toISOString();
+    if (this.options.refusePayees?.includes(payment.payee)) {
+      const outcome: RailOutcome = { status: "failed", code: "issuer_refused", message: `stub: issuer refused a charge to ${payment.payee}` };
+      const { actor: _actor, ...request } = payment;
+      this.store.stubRailPut(payment.attempt_id, request, outcome, at);
+      this.options.afterDispatch?.(payment.attempt_id);
+      return outcome;
+    }
+    const outcome = this.persistIssued(payment, "PROCESSING", false);
+    this.options.afterDispatch?.(payment.attempt_id);
+    return outcome;
+  }
+
+  async lookup(attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const recorded = this.store.stubRailGet(attemptId);
+    if (!recorded) return undefined;
+    const outcome = recorded.outcome as RailOutcome;
+    if (outcome.status !== "accepted") return outcome;
+
+    const state = this.payerState(attemptId) ?? { looks: 0, fate: this.fate };
+    const looks = state.looks + 1;
+    this.savePayerState(attemptId, { ...state, looks });
+
+    // First look: the clearing house registered the instrument. It is payable from here.
+    if (looks === 1 || !outcome.instrument.payable) {
+      return this.update(attemptId, payment, "PENDING", true);
+    }
+    if (state.fate === "pays") {
+      const settled: RailOutcome = {
+        status: "settled",
+        transaction_id: outcome.transaction_id,
+        receipt_id: outcome.transaction_id,
+        money_moved: false,
+        sandbox: true,
+        raw: { stub: true, attempt_id: attemptId, simulated: true, settled_against: "sandbox_fixture", paid_at: this.clock().toISOString() },
+      };
+      this.replace(attemptId, payment, settled);
+      return settled;
+    }
+    if (state.fate === "expires") {
+      const failed: RailOutcome = { status: "failed", code: "charge_expired", message: `stub: the receivable ${outcome.transaction_id} reached its due date unpaid`, raw: { stub: true } };
+      this.replace(attemptId, payment, failed);
+      return failed;
+    }
+    return outcome;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    // The paid charge IS the record: found by its receipt id once the payer acted here, or by its charge id when the settlement came by event.
+    const sealed = this.store.stubRailFindByReceipt(receiptId) ?? this.store.stubRailFindByTransaction(receiptId);
+    if (!sealed) return undefined;
+    const req = sealed.request as Omit<RailPayment, "actor">;
+    const out = sealed.outcome as Extract<RailOutcome, { status: "settled" | "accepted" }>;
+    const raw = out.raw as { paid_at?: string };
+    return {
+      receipt_id: receiptId,
+      kind: "charge",
+      state: "paid",
+      mandate: { id: req.mandate_id },
+      payment: { amount_minor: req.amount_minor, payee: req.payee, attempt_id: req.attempt_id, money_moved: false, sandbox: true, at: raw.paid_at ?? sealed.at },
+      chain: null,
+      receipt_sig: null,
+      actor,
+      raw: { stub: true, charge_id: out.transaction_id, simulated: true, settled_against: "sandbox_fixture" },
+    };
+  }
+
+  private instrument(payment: RailPayment, status: string, payable: boolean, chargeId: string): ChargeInstrument {
+    return {
+      payable,
+      status,
+      pix_copy_paste: payable ? `00020126580014br.gov.bcb.pix0136stub-${chargeId}5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB` : null,
+      boleto_bank_line: payable ? `${sha256Hex(chargeId).replace(/[a-f]/g, "").padEnd(47, "0").slice(0, 47)}` : null,
+      boleto_bar_code: payable ? `${sha256Hex(`bar:${chargeId}`).replace(/[a-f]/g, "").padEnd(44, "0").slice(0, 44)}` : null,
+      due_date: payment.due_date ?? null,
+    };
+  }
+
+  private persistIssued(payment: RailPayment, status: string, payable: boolean): Extract<RailOutcome, { status: "accepted" }> {
+    const chargeId = `chg_stub_${sha256Hex(payment.attempt_id).slice(0, 16)}`;
+    const outcome: Extract<RailOutcome, { status: "accepted" }> = {
+      status: "accepted",
+      transaction_id: chargeId,
+      instrument: this.instrument(payment, status, payable, chargeId),
+      sandbox: true,
+      raw: { stub: true, attempt_id: payment.attempt_id, issued_at: this.clock().toISOString() },
+    };
+    const { actor: _actor, ...request } = payment;
+    if (this.store.stubRailPut(payment.attempt_id, request, outcome, this.clock().toISOString())) this.issueCount += 1;
+    return outcome;
+  }
+
+  private update(attemptId: string, payment: RailPayment, status: string, payable: boolean): Extract<RailOutcome, { status: "accepted" }> {
+    const recorded = this.store.stubRailGet(attemptId)!;
+    const prior = recorded.outcome as Extract<RailOutcome, { status: "accepted" }>;
+    const outcome = { ...prior, instrument: this.instrument(payment, status, payable, prior.transaction_id) };
+    this.replace(attemptId, payment, outcome);
+    return outcome;
+  }
+
+  private replace(attemptId: string, payment: RailPayment, outcome: RailOutcome): void {
+    const { actor: _actor, ...request } = payment;
+    this.store.stubRailReplace(attemptId, request, outcome, this.clock().toISOString());
+  }
+
+  private payerState(attemptId: string): PayerState | undefined {
+    const raw = this.store.getCursor(CURSOR(attemptId));
+    return raw ? (JSON.parse(raw) as PayerState) : undefined;
+  }
+
+  private savePayerState(attemptId: string, state: PayerState): void {
+    this.store.setCursor(CURSOR(attemptId), JSON.stringify(state));
+  }
+}

package/templates/bills-agent/packages/agent-core/src/stubs/mandate-status.ts

@@ -0,0 +1,57 @@
+/**
+ * STUB, for runs without a key: the CI, the scenarios and `rerun`, where
+ * there is no network. Answers the section 4.7 status check from the local
+ * state.db, so a scenario can revoke or pause a mandate mid-run
+ * (`before_decision`, `before_execute` in the scenario packs) and the core
+ * reacts exactly as it does against the API. Behind the same
+ * `MandateStatusSource` interface as `api/mandate-status.ts`, which is what
+ * a run with a test key gets instead; this file is never consulted on that
+ * path.
+ *
+ * It also holds the organization kill switch (`pauseAll`), which the API
+ * does not expose yet, so `org_paused` can be exercised locally.
+ */
+import type { MandateStatusSource, MandateStatus, MandateStatusReport } from "../revocation.js";
+import type { StateStore } from "../state/store.js";
+
+export const STUB_ORG_ID = "org_local_stub";
+
+export class LocalMandateStatusStub implements MandateStatusSource {
+  constructor(
+    private readonly store: StateStore,
+    private readonly clock: () => Date = () => new Date(),
+  ) {}
+
+  async check(mandateId: string): Promise<MandateStatusReport> {
+    const row = this.store.stubMandateStatus(mandateId);
+    return {
+      mandate_id: mandateId,
+      status: (row?.status as MandateStatus | undefined) ?? "active",
+      org_paused: this.store.stubOrgPaused(STUB_ORG_ID),
+      checked_at: this.clock().toISOString(),
+      source: "stub",
+    };
+  }
+
+  /** `codespar mandate revoke <id>`, locally. */
+  revoke(mandateId: string, reason = "revoked by operator"): void {
+    this.store.stubSetMandateStatus(mandateId, "revoked", reason, this.clock().toISOString());
+  }
+
+  pause(mandateId: string, reason = "paused by operator"): void {
+    this.store.stubSetMandateStatus(mandateId, "paused", reason, this.clock().toISOString());
+  }
+
+  resume(mandateId: string): void {
+    this.store.stubSetMandateStatus(mandateId, "active", null, this.clock().toISOString());
+  }
+
+  /** The organization kill switch, locally: the API has no `org pauseAll` yet. */
+  pauseAll(): void {
+    this.store.stubSetOrgPaused(STUB_ORG_ID, true, this.clock().toISOString());
+  }
+
+  resumeAll(): void {
+    this.store.stubSetOrgPaused(STUB_ORG_ID, false, this.clock().toISOString());
+  }
+}

package/templates/bills-agent/packages/agent-core/src/stubs/rail.ts

@@ -0,0 +1,124 @@
+/**
+ * STUB rail. A deterministic stand-in for the CodeSpar sandbox so the
+ * scenarios, the adversarial suite and the restart test run offline. Every
+ * attempt is persisted in state.db before the outcome is returned, which is
+ * what lets a process killed right after "the money left" be reconciled on
+ * `resume` instead of paying again. Receipts here are HMAC-shaped only in
+ * form; nothing about them is verifiable by anyone.
+ */
+import { sha256Hex } from "../hash.js";
+import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import type { StateStore } from "../state/store.js";
+import type { Actor } from "../types.js";
+
+export interface StubRailOptions {
+  clock?: () => Date;
+  /** Payees the stub refuses, to script a `failed` outcome. */
+  refusePayees?: string[];
+  /** Attempt ids the stub answers `uncertain` for, once. */
+  uncertainOnce?: string[];
+  /** Test hook: called after the attempt is persisted and before the outcome is returned. */
+  afterDispatch?: (attemptId: string) => void;
+  /** Attempt ids whose first lookup answers `in_flight` and whose second lookup finds the provider finished (settled), with no pay() in between. */
+  inFlightThenSettled?: string[];
+}
+
+export class StubRail implements PaymentRail {
+  readonly name = "stub" as const;
+  private readonly clock: () => Date;
+  private readonly uncertainPending: Set<string>;
+
+  constructor(
+    private readonly store: StateStore,
+    private readonly options: StubRailOptions = {},
+  ) {
+    this.clock = options.clock ?? (() => new Date());
+    this.uncertainPending = new Set(options.uncertainOnce ?? []);
+  }
+
+  private uncertainArmed = false;
+  private readonly inFlightSeen = new Set<string>();
+  /** Attempts that answered `uncertain` because the stub was armed: the "provider" did take them, and a later lookup finds them finished. */
+  private readonly lateAttempts = new Set<string>();
+  /** How many times pay() reached the point of persisting a NEW attempt. */
+  payCount = 0;
+
+  /** The NEXT new attempt answers `uncertain` once, whatever its id; the provider still took it, so a later lookup sees it in flight and then settled. For scenarios that reconcile. */
+  armUncertainOnce(): void {
+    this.uncertainArmed = true;
+  }
+
+  async pay(payment: RailPayment): Promise<RailOutcome> {
+    const existing = this.store.stubRailGet(payment.attempt_id);
+    if (existing) return existing.outcome as RailOutcome;
+
+    if (this.uncertainArmed || this.uncertainPending.has(payment.attempt_id)) {
+      if (this.uncertainArmed) this.lateAttempts.add(payment.attempt_id);
+      this.uncertainArmed = false;
+      this.uncertainPending.delete(payment.attempt_id);
+      return { status: "uncertain", code: "psp_dispatch_uncertain", message: "stub: outcome unknown on first presentation" };
+    }
+
+    const at = this.clock().toISOString();
+    const outcome: RailOutcome = this.options.refusePayees?.includes(payment.payee)
+      ? { status: "failed", code: "psp_dispatch_failed", message: `stub: provider refused payee ${payment.payee}` }
+      : {
+          status: "settled",
+          transaction_id: `stubtx_${sha256Hex(payment.attempt_id).slice(0, 16)}`,
+          receipt_id: `rcpt_stub_${sha256Hex(`receipt:${payment.attempt_id}`).slice(0, 16)}`,
+          money_moved: false,
+          sandbox: true,
+          raw: { stub: true, attempt_id: payment.attempt_id, at },
+        };
+    const { actor: _actor, ...request } = payment;
+    this.payCount += 1;
+    this.store.stubRailPut(payment.attempt_id, request, outcome, at);
+    this.options.afterDispatch?.(payment.attempt_id);
+    return outcome;
+  }
+
+  async lookup(attemptId: string, payment: RailPayment): Promise<RailLookup> {
+    const recorded = this.store.stubRailGet(attemptId)?.outcome as RailOutcome | undefined;
+    if (recorded) return recorded;
+    if (this.options.inFlightThenSettled?.includes(attemptId) || this.lateAttempts.has(attemptId)) {
+      if (!this.inFlightSeen.has(attemptId)) {
+        this.inFlightSeen.add(attemptId);
+        return { status: "in_flight" };
+      }
+      // The provider finished on its own; the stub records the outcome as the rail would, without a new dispatch.
+      const { actor: _actor, ...request } = payment;
+      const outcome: RailOutcome = {
+        status: "settled",
+        transaction_id: `stubtx_${sha256Hex(attemptId).slice(0, 16)}`,
+        receipt_id: `rcpt_stub_${sha256Hex(`receipt:${attemptId}`).slice(0, 16)}`,
+        money_moved: false,
+        sandbox: true,
+        raw: { stub: true, attempt_id: attemptId, finished_in_background: true },
+      };
+      this.store.stubRailPut(attemptId, request, outcome, this.clock().toISOString());
+      return outcome;
+    }
+    return undefined;
+  }
+
+  async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
+    const sealed = this.store.stubRailFindByReceipt(receiptId);
+    if (!sealed) return undefined;
+    const req = sealed.request as Omit<RailPayment, "actor">;
+    const out = sealed.outcome as Extract<RailOutcome, { status: "settled" }>;
+    const body = {
+      receipt_id: receiptId,
+      state: "paid",
+      mandate: { id: req.mandate_id },
+      payment: { amount_minor: req.amount_minor, payee: req.payee, attempt_id: req.attempt_id, money_moved: false, sandbox: true, at: sealed.at },
+    };
+    const chain = `sha256:${sha256Hex(JSON.stringify(body))}`;
+    return {
+      ...body,
+      chain,
+      receipt_sig: `stub:${sha256Hex(`sig:${chain}`).slice(0, 32)}`,
+      actor,
+      raw: { stub: true, transaction_id: out.transaction_id },
+    };
+  }
+}

package/templates/bills-agent/packages/agent-core/src/tools.ts

@@ -0,0 +1,55 @@
+/**
+ * `tools.json`: the closed list of tools the model may call. Tool-level
+ * authority comes before mandate-level authority: a tool that is not in
+ * this file is refused before anything else looks at the call.
+ *
+ * Two kinds. `meta_tools` are CodeSpar meta-tool names, with the input the
+ * kit accepts for them (a snapshot of the MCP shape, pinned by `mcp` in the
+ * manifest; see OPEN_QUESTIONS on why the list is not fetched live).
+ * `local_tools` are the agent's own read-only helpers.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import type { ToolSpec } from "./providers/types.js";
+
+const ToolDefinitionSchema = z
+  .object({
+    name: z.string().regex(/^[a-z][a-z0-9_]*$/),
+    description: z.string().min(1),
+    input_schema: z.record(z.string(), z.unknown()),
+    /** `payment` and `charge` tools create a `drafted` execution and nothing else; `read` tools never touch money. `charge` is the receivable side: the counterparty pays us. */
+    effect: z.enum(["payment", "charge", "read"]),
+  })
+  .strict();
+
+export const ToolsFileSchema = z
+  .object({
+    meta_tools: z.array(ToolDefinitionSchema),
+    local_tools: z.array(ToolDefinitionSchema),
+  })
+  .strict()
+  .superRefine((t, ctx) => {
+    const names = new Set<string>();
+    for (const tool of [...t.meta_tools, ...t.local_tools]) {
+      if (names.has(tool.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate tool ${tool.name}` });
+      names.add(tool.name);
+    }
+    for (const [i, tool] of t.meta_tools.entries()) {
+      if (!tool.name.startsWith("codespar_")) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["meta_tools", i, "name"], message: "meta-tools are named codespar_*" });
+    }
+  });
+
+export type ToolsFile = z.infer<typeof ToolsFileSchema>;
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
+
+export function loadToolsFile(path: string): ToolsFile {
+  return ToolsFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export function toolSpecs(tools: ToolsFile): ToolSpec[] {
+  return [...tools.meta_tools, ...tools.local_tools].map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }));
+}
+
+export function allowedToolNames(tools: ToolsFile): Set<string> {
+  return new Set([...tools.meta_tools, ...tools.local_tools].map((t) => t.name));
+}

package/templates/bills-agent/packages/agent-core/src/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared shapes of the core. Amounts are always integer minor units (BRL
+ * cents). Timestamps are ISO 8601 strings so they survive SQLite and JSON
+ * unchanged.
+ */
+
+export type ApprovalMode = "human" | "mandate";
+
+/** Section 4.5: who acted. Every API call and every receipt carries one. */
+export type Actor =
+  | { type: "agent"; agent: string; on_behalf_of: string }
+  | { type: "human"; id: string; channel: string };
+
+/** One line of an execution: a payee and an amount, resolved by the core. */
+export interface ExecutionItem {
+  /** The alias the model used (`escola`), when it used one. */
+  alias?: string;
+  /** Display name from the mandate's named payees, when known. */
+  beneficiary: string;
+  /** The pinned payee key (a Pix key for `pix-key` mandates). */
+  payee: string;
+  amount: number;
+  currency: string;
+  description?: string;
+  /** A receivable's due date (`YYYY-MM-DD`). Part of the `items_hash` when present: moving it after approval is a different charge. */
+  due_date?: string;
+}
+
+/** The trigger of section 4.4 that sent a `mandate` execution to a human. */
+export type EscalationTrigger = "amount" | "new_beneficiary" | "outside_hours";
+
+/** Stable reasons a transition can carry. They are the readable-failure contract. */
+export type ExecutionReason =
+  | "mandate_revoked"
+  | "mandate_paused"
+  | "mandate_expired"
+  | "mandate_status_unavailable"
+  | "org_paused"
+  | "beneficiary_not_allowed"
+  | "per_tx_cap_exceeded"
+  | "window_cap_exceeded"
+  | "approval_expired"
+  | "items_hash_mismatch"
+  | "mandate_changed"
+  | "denied_by_approver"
+  | "rail_failed"
+  | "rail_uncertain"
+  | "tool_not_allowed"
+  | "model_total_mismatch"
+  | "outside_hours"
+  | "escalated"
+  /** The agent's own envelope (guardrails) refused what the model proposed: a discount, an instalment count or a due date outside it. */
+  | "outside_envelope"
+  /** A receivable was issued and the rail is waiting for the payer; the execution stays `executing` until `commerce.charge.*` closes it. */
+  | "awaiting_settlement"
+  | "charge_expired"
+  | "charge_cancelled";
+
+export interface MandateRef {
+  id: string;
+  version: number;
+}
+
+/** Section 4.2. */
+export interface ApprovalArtifact {
+  approval_id: string;
+  execution_id: string;
+  mode: ApprovalMode;
+  approver:
+    | { type: "person"; id: string; channel: string }
+    | { type: "mandate"; id: string };
+  approved_at: string;
+  expires_at: string;
+  mandate: MandateRef;
+  items: ExecutionItem[];
+  items_hash: string;
+  /** Present when a section 4.4 trigger sent the execution to a human first. */
+  escalation?: { trigger: EscalationTrigger; detail: string };
+  actor: Actor;
+  signature: { alg: "HMAC-SHA256"; key_id: string; value: string };
+}
+
+export interface ItemOutcome {
+  index: number;
+  attempt_id: string;
+  /** `accepted`: the rail took the attempt and the outcome comes later (a receivable waiting for its payer). Not terminal. */
+  status: "settled" | "failed" | "accepted";
+  receipt_id?: string;
+  transaction_id?: string;
+  /** The rail's code on a failed outcome (`charge_expired`, `charge_cancelled`, a provider code). */
+  code?: string;
+  error?: string;
+  /** What the payer is shown for an accepted receivable, as the rail handed it back. Presentation only; nothing here decides money. */
+  instrument?: ChargeInstrument;
+}
+
+/** The payable legs of a receivable. Null until the issuer registers the instrument (a cobranca com vencimento answers PROCESSING first). */
+export interface ChargeInstrument {
+  payable: boolean;
+  pix_copy_paste: string | null;
+  boleto_bank_line: string | null;
+  boleto_bar_code: string | null;
+  due_date: string | null;
+  /** The issuer's normalized state as last read: PROCESSING, PENDING, CONFIRMED, EXPIRED, CANCELLED. */
+  status: string;
+}

package/templates/bills-agent/packages/agent-core/test/approval.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { checkApprovalArtifact, createApprovalArtifact, hmacSigner } from "../src/approval.js";
+import { itemsHash } from "../src/hash.js";
+import type { Execution } from "../src/state-machine.js";
+import type { Actor, ExecutionItem } from "../src/types.js";
+
+const actor: Actor = { type: "human", id: "usr_1", channel: "terminal" };
+const signer = hmacSigner("test", Buffer.alloc(32, 7));
+const now = new Date("2026-09-23T14:03:11Z");
+
+function execution(items: ExecutionItem[]): Execution<"awaiting_approval"> {
+  return {
+    id: "exe_1",
+    run_id: "run_1",
+    state: "awaiting_approval",
+    mode: "human",
+    actor: { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_1" },
+    items,
+    total: items.reduce((s, i) => s + i.amount, 0),
+    currency: "BRL",
+    items_hash: itemsHash(items),
+    mandate: { id: "mdt_1", version: 3 },
+    idempotency_key: "idk_1",
+    blocking_reasons: [],
+    outcomes: [],
+    history: [],
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  };
+}
+
+const escola: ExecutionItem = { alias: "escola", beneficiary: "Escola", payee: "escola@exemplo.com.br", amount: 185000, currency: "BRL" };
+
+describe("section 4.2: approval artifact", () => {
+  it("has the schema of the spec and an HMAC signature that verifies", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(artifact.approval_id).toMatch(/^apr_/);
+    expect(artifact.execution_id).toBe("exe_1");
+    expect(artifact.mode).toBe("human");
+    expect(artifact.mandate).toEqual({ id: "mdt_1", version: 3 });
+    expect(artifact.items_hash).toMatch(/^sha256:[0-9a-f]{64}$/);
+    expect(artifact.signature.alg).toBe("HMAC-SHA256");
+    expect(artifact.actor).toEqual(actor);
+    expect(new Date(artifact.expires_at).getTime() - new Date(artifact.approved_at).getTime()).toBe(15 * 60 * 1000);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+  });
+
+  it("items_hash ignores presentation fields and changes when the money fields change", () => {
+    const base = itemsHash([escola]);
+    expect(itemsHash([{ ...escola, description: "outubro", beneficiary: "Escola X" }])).toBe(base);
+    expect(itemsHash([{ ...escola, amount: 185001 }])).not.toBe(base);
+    expect(itemsHash([{ ...escola, payee: "outra@chave" }])).not.toBe(base);
+  });
+
+  it("refuses when the list changed after approval (items_hash mismatch)", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    const tampered = { ...exe, items: [{ ...escola, amount: 500000 }] };
+    expect(checkApprovalArtifact(signer, artifact, tampered, now)).toEqual({ ok: false, problem: "items_hash_mismatch" });
+  });
+
+  it("refuses a tampered artifact, an expired one and a foreign key", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(checkApprovalArtifact(signer, { ...artifact, items_hash: itemsHash([{ ...escola, amount: 1 }]) }, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+    expect(checkApprovalArtifact(signer, artifact, exe, new Date(now.getTime() + 16 * 60 * 1000))).toEqual({ ok: false, problem: "expired" });
+    expect(checkApprovalArtifact(hmacSigner("other", Buffer.alloc(32, 9)), artifact, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+    expect(checkApprovalArtifact(signer, artifact, { ...exe, mandate: { id: "mdt_1", version: 4 } }, now)).toEqual({ ok: false, problem: "wrong_mandate" });
+  });
+
+  it("records the escalation trigger when there was one", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, {
+      execution: exe,
+      approver: { type: "person", id: "usr_1", channel: "terminal" },
+      actor,
+      now,
+      escalation: { trigger: "amount", detail: "above 150000" },
+    });
+    expect(artifact.escalation).toEqual({ trigger: "amount", detail: "above 150000" });
+  });
+});