@codespar/cli 0.14.1 → 0.16.0

package/templates/hello-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/hello-agent/packages/agent-core/src/stubs/rail.ts

@@ -0,0 +1,141 @@
+/**
+ * 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[];
+  /**
+   * Payees whose first presentation answers `uncertain`, the way a timeout
+   * does: the provider still took the attempt, so a later lookup finds it.
+   * The payee twin of `refusePayees`, for scripting an unknown outcome in the
+   * MIDDLE of a multi-item execution, where the attempt ids are not known
+   * until the execution exists.
+   */
+  uncertainPayees?: 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>();
+  /** Attempts that already gave their one `uncertain`, so a re-presentation behaves normally. */
+  private readonly uncertainAnswered = 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;
+
+    const uncertainPayee = this.options.uncertainPayees?.includes(payment.payee) === true && !this.uncertainAnswered.has(payment.attempt_id);
+    if (this.uncertainArmed || this.uncertainPending.has(payment.attempt_id) || uncertainPayee) {
+      if (this.uncertainArmed || uncertainPayee) this.lateAttempts.add(payment.attempt_id);
+      this.uncertainAnswered.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)}`,
+      // The stub holds no CodeSpar key and must not look as though it did:
+      // `npm run verify` answers `unsigned` on a stub receipt, which is the
+      // truth about it.
+      receipt_sig_ed25519: null,
+      receipt_sig_kid: null,
+      actor,
+      raw: { stub: true, transaction_id: out.transaction_id },
+    };
+  }
+}

package/templates/hello-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/hello-agent/packages/agent-core/src/types.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 SET a line belongs to, when the line is one execution of a batch.
+ *
+ * A batch of N lines is N executions, each attested by its own `items_hash`.
+ * That leaves the list itself unattested: a person who approved four lines
+ * while the agent ran three leaves a bundle that does not say a fourth
+ * existed. `batch_hash` binds the set — computed once over the ordered lines
+ * at the moment the list is presented for approval, and carried by every
+ * artifact of that batch together with the line's own position in it.
+ *
+ * Absent on an execution that is not part of a batch, and an artifact
+ * without it is the artifact of section 4.2 unchanged, byte for byte: the
+ * field is omitted rather than null, so the canonical payload it signs is
+ * the same payload it signed before this existed.
+ */
+export interface ExecutionBatch {
+  /** The batch's reference, as the kit names it (`folha-2026-10`). */
+  ref: string;
+  /** `batchHash` over the batch's ordered lines, as they were presented. */
+  batch_hash: string;
+  /** This line's position in that ordered list, counting from 0. */
+  index: number;
+  /** How many lines the presented list held. */
+  count: number;
+}
+
+/** 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 this execution is one line of a batch: what binds the SET this line was approved inside. */
+  batch?: ExecutionBatch;
+  /** 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/hello-agent/packages/agent-core/test/approval.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { checkApprovalArtifact, createApprovalArtifact, hmacSigner } from "../src/approval.js";
+import { batchHash, itemsHash } from "../src/hash.js";
+import type { Execution } from "../src/state-machine.js";
+import type { Actor, ExecutionBatch, 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" };
+const mercado: ExecutionItem = { alias: "mercado", beneficiary: "Mercado", payee: "+5511999990001", amount: 42000, 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("carries the batch this line belongs to, and the whole of it is signed", () => {
+    const batch: ExecutionBatch = { ref: "folha-2026-10", batch_hash: batchHash([escola, mercado]), index: 0, count: 2 };
+    const exe = { ...execution([escola]), batch };
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    expect(artifact.batch).toEqual(batch);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+    // Moving the line inside the list, re-pricing the list, or renaming it:
+    // each is a different set, and the signature covers all of it.
+    for (const changed of [{ ...batch, index: 1 }, { ...batch, count: 3 }, { ...batch, ref: "folha-2026-11" }, { ...batch, batch_hash: batchHash([escola]) }]) {
+      expect(checkApprovalArtifact(signer, { ...artifact, batch: changed }, exe, now)).toEqual({ ok: false, problem: "signature_invalid" });
+      expect(checkApprovalArtifact(signer, artifact, { ...exe, batch: changed }, now)).toEqual({ ok: false, problem: "batch_mismatch" });
+    }
+  });
+
+  it("an artifact with no batch signs the payload it signed before batches existed", () => {
+    const exe = execution([escola]);
+    const artifact = createApprovalArtifact(signer, { execution: exe, approver: { type: "person", id: "usr_1", channel: "terminal" }, actor, now });
+    // Omitted, never null: a bills-agent run has no batch and must not grow a key.
+    expect("batch" in artifact).toBe(false);
+    expect(checkApprovalArtifact(signer, artifact, exe, now)).toEqual({ ok: true });
+    // An execution that gained a batch after the artifact was signed is not the one that was approved.
+    const joined = { ...exe, batch: { ref: "folha-2026-10", batch_hash: batchHash([escola]), index: 0, count: 1 } };
+    expect(checkApprovalArtifact(signer, artifact, joined, now)).toEqual({ ok: false, problem: "batch_mismatch" });
+  });
+
+  it("the batch hash IS the items hash of the whole ordered list, so a reader can recompute it", () => {
+    expect(batchHash([escola, mercado])).toBe(itemsHash([escola, mercado]));
+    // Order is part of it: `index` names a position, and a position only means something in a fixed order.
+    expect(batchHash([mercado, escola])).not.toBe(batchHash([escola, mercado]));
+    // A line dropped is a different set, which is the whole point.
+    expect(batchHash([escola])).not.toBe(batchHash([escola, mercado]));
+  });
+
+  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" });
+  });
+});

package/templates/hello-agent/packages/agent-core/test/bundle.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Section 11: what the proof bundle has to carry for `npm run inspect` to
+ * answer "why could the agent pay this" from the folder alone — the rail's
+ * request and its answer per attempt, and a receipt path that travels with
+ * the bundle instead of naming the machine that wrote it.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { maskPayee } from "../src/bundle.js";
+import { harness } from "./helpers.js";
+
+const approver = { id: "usr_demo", channel: "terminal" };
+
+async function settledRun() {
+  const h = harness({ mode: "human" });
+  const draft = await h.engine.draft({ items: [{ payee: "escola", amount: 185000, description: "outubro" }] });
+  if (!draft.ok) throw new Error("refused");
+  const approved = h.engine.approve(draft.execution.id, approver);
+  const settled = await h.engine.execute(approved.id);
+  return { h, settled };
+}
+
+describe("the proof bundle records the rail call and its answer", () => {
+  it("rail.dispatch names the idempotency key that makes a retry the same payment", async () => {
+    const { h, settled } = await settledRun();
+    const dispatch = h.bundle.readEvents().find((e) => e["type"] === "rail.dispatch");
+    expect(dispatch).toBeDefined();
+    const payload = dispatch!["payload"] as Record<string, unknown>;
+    expect(payload["idempotency_key"]).toBe(settled.idempotency_key);
+    expect(payload["attempt_id"]).toBe(settled.outcomes[0]?.attempt_id);
+    expect(payload["rail"]).toBe("stub");
+  });
+
+  it("rail.outcome carries what the rail answered: transaction, receipt and whether money moved", async () => {
+    const { h, settled } = await settledRun();
+    const outcome = h.bundle.readEvents().find((e) => e["type"] === "rail.outcome");
+    const payload = outcome!["payload"] as Record<string, unknown>;
+    expect(payload["status"]).toBe("settled");
+    expect(payload["receipt_id"]).toBe(settled.outcomes[0]?.receipt_id);
+    expect(payload["transaction_id"]).toBe(settled.outcomes[0]?.transaction_id);
+    expect(payload["money_moved"]).toBe(false);
+    expect(payload["sandbox"]).toBe(true);
+    // Never the provider's echo: `raw` may carry payer data the bundle does not promise to mask.
+    expect(payload["raw"]).toBeUndefined();
+  });
+
+  it("a refused attempt records the rail's own code and message", async () => {
+    const h = harness({ mode: "human", rail: { refusePayees: ["escola@exemplo.com.br"] } });
+    const draft = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!draft.ok) throw new Error("refused");
+    const approved = h.engine.approve(draft.execution.id, approver);
+    await h.engine.execute(approved.id);
+    const outcome = h.bundle.readEvents().find((e) => e["type"] === "rail.outcome");
+    const payload = outcome!["payload"] as Record<string, unknown>;
+    expect(payload["status"]).toBe("failed");
+    expect(payload["code"]).toBeTypeOf("string");
+    expect(payload["message"]).toBeTypeOf("string");
+  });
+
+  it("receipt.saved names the file inside the bundle, not the machine that wrote it", async () => {
+    const { h } = await settledRun();
+    const saved = h.bundle.readEvents().find((e) => e["type"] === "receipt.saved");
+    const path = (saved!["payload"] as { path: string }).path;
+    expect(path).toMatch(/^receipts\//);
+    expect(path).not.toContain(h.bundle.dir);
+    const receipt = JSON.parse(readFileSync(join(h.bundle.dir, path), "utf8")) as { payment: { payee: string } };
+    expect(receipt.payment.payee).toBe(maskPayee("escola@exemplo.com.br"));
+  });
+
+  it("the mandate snapshot carries the version the approval artifact names", async () => {
+    const { h, settled } = await settledRun();
+    h.bundle.mandateSnapshot(h.engine.mandate);
+    const snapshot = JSON.parse(readFileSync(join(h.bundle.dir, "mandate.snapshot.json"), "utf8")) as { version: number; signature?: string };
+    expect(snapshot.version).toBe(settled.mandate.version);
+    expect(snapshot.signature).toBeUndefined();
+    expect(h.bundle.readApprovals()[0]?.mandate.version).toBe(snapshot.version);
+  });
+
+  it("maskPayee is idempotent, so a reader may apply it to a value the bundle already masked", () => {
+    for (const raw of ["escola@exemplo.com.br", "+5511999990001", "12345678909", "*"]) {
+      expect(maskPayee(maskPayee(raw))).toBe(maskPayee(raw));
+    }
+  });
+});

package/templates/hello-agent/packages/agent-core/test/clock.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { FIXED_CLOCK_ENV, InvalidFixedClockError, fixedClock, resolveFixedClock } from "../src/clock.js";
+
+describe("fixedClock", () => {
+  it("starts at the instant and ticks one second per read, so no two events share a timestamp", () => {
+    const clock = fixedClock("2026-09-23T14:00:00-03:00");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:00.000Z");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:01.000Z");
+    expect(clock().toISOString()).toBe("2026-09-23T17:00:02.000Z");
+  });
+
+  it("refuses what Date cannot parse, and a bare date, naming the source", () => {
+    expect(() => fixedClock("yesterday")).toThrow(InvalidFixedClockError);
+    expect(() => fixedClock("2026-09-23", FIXED_CLOCK_ENV)).toThrow(/CODESPAR_AGENT_NOW must be an ISO 8601 instant/);
+  });
+});
+
+describe("resolveFixedClock", () => {
+  it("prefers the flag, falls back to the environment, and is undefined (the wall clock) without either", () => {
+    expect(resolveFixedClock(undefined, {})).toBeUndefined();
+    expect(resolveFixedClock(undefined, { [FIXED_CLOCK_ENV]: "   " })).toBeUndefined();
+    expect(resolveFixedClock(undefined, { [FIXED_CLOCK_ENV]: "2026-09-23T20:08:00-03:00" })!().toISOString()).toBe("2026-09-23T23:08:00.000Z");
+    expect(resolveFixedClock("2026-09-23T14:00:00-03:00", { [FIXED_CLOCK_ENV]: "2026-09-23T20:08:00-03:00" })!().toISOString()).toBe("2026-09-23T17:00:00.000Z");
+  });
+});