@codespar/cli 0.14.1 → 0.17.0

package/templates/hello-agent/packages/agent-core/test/fixtures/staging-receipt-keys.json

@@ -0,0 +1,18 @@
+{
+  "issuer": "did:web:id.codespar.dev",
+  "algorithm": "Ed25519",
+  "signing_string": "codespar-receipt:v1:<receipt_id>:<chain>",
+  "keys": [
+    {
+      "kid": "did:web:id.codespar.dev#1",
+      "kty": "OKP",
+      "crv": "Ed25519",
+      "x": "u7hulmfhdU9wxv44pfychrNTF0RvUIwDn_QKi3j5Puk",
+      "alg": "EdDSA",
+      "use": "sig",
+      "status": "active",
+      "created_at": "2026-09-24T22:22:38.589Z",
+      "retired_at": null
+    }
+  ]
+}

package/templates/hello-agent/packages/agent-core/test/fixtures/staging-receipt.json

@@ -0,0 +1,24 @@
+{
+  "receipt_id": "rcpt_BkYTo_9eJnlyzGsRjfFYHk",
+  "state": "paid",
+  "mandate": {
+    "id": "cm_8m6ew__uzvMrp2i3"
+  },
+  "payment": {
+    "amount_minor": 185000,
+    "payee": null,
+    "attempt_id": "att_50fa99e93ed1183520bfd185d350a7c4_0",
+    "money_moved": false,
+    "sandbox": true,
+    "at": "2026-09-24T22:42:41.242Z"
+  },
+  "chain": "cf5a00d44c4aea42bd7e4bcb48f37f077bfeae1ff5f6f4fff20438861a79e17d",
+  "receipt_sig": "9a63a12e9ab88e10c76f77d8ec0c3f4dec9ca1251579a608be1be260922b312c",
+  "receipt_sig_ed25519": "aQTf3A1UR8kdthPUwBDfAmnnpYyn8SUp1DYyKcvMylOYhLtznQS_h2SB-N9PxQtSS2wTSO-lp_YDrrVS5Nz1CA",
+  "receipt_sig_kid": "did:web:id.codespar.dev#1",
+  "actor": {
+    "type": "agent",
+    "agent": "bills-agent@0.1.0",
+    "on_behalf_of": "usr_demo_titular"
+  }
+}

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

@@ -0,0 +1,139 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hmacSigner } from "../src/approval.js";
+import { ProofBundle } from "../src/bundle.js";
+import { ExecutionEngine, type EngineDeps } from "../src/engine.js";
+import { GuardrailsSchema, type Guardrails } from "../src/guardrails.js";
+import { MandateSchema, type Mandate } from "../src/mandate.js";
+import { ManifestSchema, type Manifest } from "../src/manifest.js";
+import { StateStore } from "../src/state/store.js";
+import { LocalMandateStatusStub } from "../src/stubs/mandate-status.js";
+import type { MandateStatusSource } from "../src/revocation.js";
+import { StubRail, type StubRailOptions } from "../src/stubs/rail.js";
+import type { ApprovalMode } from "../src/types.js";
+
+export const ESCOLA = "escola@exemplo.com.br";
+export const MERCADO = "+5511999990001";
+export const FUNCIONARIA = "123.456.789-09";
+
+export function testManifest(over: Partial<Manifest> = {}): Manifest {
+  return ManifestSchema.parse({
+    schema: 1,
+    name: "bills-agent",
+    version: "0.1.0",
+    approval: ["human", "mandate"],
+    default_approval: "human",
+    escalate_above: { amount: 150000, new_beneficiary: true, outside_hours: "22:00-07:00" },
+    mcp: "@codespar/mcp@0.5.8",
+    cli: "@codespar/cli@0.14.0",
+    tools: "./tools.json",
+    guardrails: "./guardrails.json",
+    mandate_schema: "./mandate.example.json",
+    events: ["commerce.payment.succeeded", "commerce.payment.failed"],
+    channels: ["terminal"],
+    maturity: { "pix-out": "sandbox", "embedded-consent": "sandbox", "receipt-verification": "blocked" },
+    scenarios: "./scenarios/",
+    evals: "./evals/",
+    agents_md: "./AGENTS.md",
+    ...over,
+  });
+}
+
+export function testGuardrails(over: Partial<Guardrails> = {}): Guardrails {
+  return GuardrailsSchema.parse({
+    approval: "human",
+    escalate_above: { amount: 150000, new_beneficiary: true, outside_hours: "22:00-07:00" },
+    velocity: { window_hours: 24 },
+    ...over,
+  });
+}
+
+export function testMandate(over: Partial<Mandate> = {}): Mandate {
+  return MandateSchema.parse({
+    id: "mdt_test_0001",
+    version: 1,
+    consumer_id: "usr_demo",
+    agent_id: "bills-agent",
+    purpose: "contas do mes",
+    currency: "BRL",
+    cap_minor: 7200000,
+    per_tx_cap_minor: 250000,
+    periodic_cap: { window: "month", cap_minor: 600000 },
+    merchant_pin_kind: "pix-key",
+    merchant_allowlist: [ESCOLA, MERCADO, FUNCIONARIA],
+    beneficiaries: [
+      { alias: "escola", name: "Escola Aurora", payee: ESCOLA },
+      { alias: "mercado", name: "Mercado do Bairro", payee: MERCADO },
+      { alias: "funcionaria", name: "Maria (funcionaria)", payee: FUNCIONARIA },
+    ],
+    status: "active",
+    expires_at: "2027-09-23T00:00:00.000Z",
+    ...over,
+  });
+}
+
+export interface Harness {
+  dir: string;
+  store: StateStore;
+  gate: LocalMandateStatusStub;
+  rail: StubRail;
+  bundle: ProofBundle;
+  engine: ExecutionEngine;
+  now: Date;
+  setNow(date: Date): void;
+}
+
+export interface HarnessOptions {
+  mode?: ApprovalMode;
+  now?: Date;
+  guardrails?: Partial<Guardrails>;
+  mandate?: Partial<Mandate>;
+  manifest?: Partial<Manifest>;
+  rail?: StubRailOptions;
+  dir?: string;
+  runId?: string;
+  /** The section 4.7 status source; the local stub unless a test wires the API one. */
+  status?: MandateStatusSource;
+}
+
+export function harness(options: HarnessOptions = {}): Harness {
+  const dir = options.dir ?? mkdtempSync(join(tmpdir(), "agent-core-"));
+  let now = options.now ?? new Date("2026-09-23T18:00:00Z"); // 15:00 in Sao Paulo
+  const clock = () => now;
+  const store = new StateStore(join(dir, "state.db"));
+  const gate = new LocalMandateStatusStub(store, clock);
+  const rail = new StubRail(store, { clock, ...(options.rail ?? {}) });
+  const runId = options.runId ?? "run_test";
+  const bundle = new ProofBundle(join(dir, "runs"), runId);
+  const mode = options.mode ?? "human";
+  const deps: EngineDeps = {
+    store,
+    rail,
+    status: options.status ?? gate,
+    signer: hmacSigner("test", Buffer.alloc(32, 1)),
+    manifest: testManifest(options.manifest),
+    guardrails: testGuardrails({ approval: mode, ...(options.guardrails ?? {}) }),
+    mandate: testMandate(options.mandate),
+    bundle,
+    mode,
+    runId,
+    onBehalfOf: "usr_demo",
+    clock,
+  };
+  const engine = new ExecutionEngine(deps);
+  return {
+    dir,
+    store,
+    gate,
+    rail,
+    bundle,
+    engine,
+    get now() {
+      return now;
+    },
+    setNow(date: Date) {
+      now = date;
+    },
+  };
+}

package/templates/hello-agent/packages/agent-core/test/mandate-status.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Section 4.7 against the real client: `ApiMandateStatusSource` reads
+ * `GET /v1/mandates/{id}` on a mocked HTTP server, and the engine is driven
+ * through it. Every answer but `active` must keep `rail.pay` from ever
+ * being called, and a read that does not answer must refuse too.
+ */
+import { createServer, type Server } from "node:http";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createCodeSparClient } from "../src/api/client.js";
+import { ApiMandateStatusSource } from "../src/api/mandate-status.js";
+import type { MandateStatusSource } from "../src/revocation.js";
+import { harness, type Harness } from "./helpers.js";
+
+const MANDATE_ID = "mdt_test_0001";
+const NOW = new Date("2026-09-23T18:00:00Z");
+const approver = { id: "usr_demo_titular", channel: "terminal" };
+
+/** The 14-field projection `GET /v1/mandates/{id}` answers (measured on staging, 2026-09-23). */
+function mandateBody(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: MANDATE_ID,
+    consumer_id: "usr_demo",
+    agent_id: "bills-agent",
+    display_name: null,
+    purpose: "contas do mes",
+    merchant_allowlist: ["escola@exemplo.com.br"],
+    merchant_pin_kind: "pix-key",
+    intent_note: null,
+    cap_minor: "7200000",
+    per_tx_cap_minor: "250000",
+    currency: "BRL",
+    status: "active",
+    expires_at: "2027-09-23T00:00:00.000Z",
+    created_at: "2026-09-23T00:00:00.000Z",
+    ...over,
+  };
+}
+
+type Answer = { status: number; body?: unknown; hang?: boolean };
+
+let server: Server;
+let baseUrl: string;
+let next: Answer = { status: 200, body: mandateBody() };
+const requests: Array<{ method: string; url: string; bearerIsTestKey: boolean }> = [];
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    requests.push({ method: req.method ?? "", url: req.url ?? "", bearerIsTestKey: (req.headers.authorization ?? "").startsWith("Bearer csk_test_") });
+    if (next.hang) return; // never answers: the client's timeout is the only way out
+    res.writeHead(next.status, { "content-type": "application/json" });
+    res.end(typeof next.body === "string" ? next.body : JSON.stringify(next.body));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+});
+
+afterAll(async () => {
+  server.closeAllConnections();
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+});
+
+beforeEach(() => {
+  next = { status: 200, body: mandateBody() };
+  requests.length = 0;
+});
+
+function apiSource(timeoutMs = 5_000): ApiMandateStatusSource {
+  // The placeholder passes the `csk_test_` guard and is the one test-key-shaped string the secret scan allows.
+  return new ApiMandateStatusSource(createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs }), () => NOW);
+}
+
+function apiHarness(status: MandateStatusSource = apiSource()): Harness {
+  return harness({ mode: "mandate", now: NOW, manifest: { escalate_above: {} }, guardrails: { escalate_above: {} }, status });
+}
+
+/** Drafts and approves under `active`, then flips the API's answer: the last gate is what is under test. */
+async function approvedThen(h: Harness, answer: Answer): Promise<string> {
+  const d = await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] });
+  if (!d.ok) throw new Error(`refused before draft: ${d.reason}`);
+  expect(d.execution.state).toBe("approved");
+  next = answer;
+  return d.execution.id;
+}
+
+describe("ApiMandateStatusSource reads GET /v1/mandates/{id} with the test key", () => {
+  it("answers the status the API gives, on the one registered spelling of the route", async () => {
+    const report = await apiSource().check(MANDATE_ID);
+    expect(report).toMatchObject({ mandate_id: MANDATE_ID, status: "active", org_paused: false, source: "api" });
+    expect(requests).toEqual([{ method: "GET", url: `/v1/mandates/${MANDATE_ID}`, bearerIsTestKey: true }]);
+  });
+
+  it("an active mandate past its expires_at is expired, whatever the status field says", async () => {
+    next = { status: 200, body: mandateBody({ expires_at: "2026-09-23T17:59:59.000Z" }) };
+    expect((await apiSource().check(MANDATE_ID)).status).toBe("expired");
+  });
+
+  it("never throws: 404, 500, a hung connection, a body without a readable status and a status outside the four are all `unknown`, with a reason", async () => {
+    next = { status: 404, body: { error: { code: "mandate_not_found", message: "no such mandate" }, request_id: null } };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("no mandate") });
+    next = { status: 500, body: { error: { code: "internal", message: "boom" } } };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("did not answer") });
+    next = { status: 200, body: "not json at all" };
+    expect((await apiSource().check(MANDATE_ID)).status).toBe("unknown");
+    next = { status: 200, body: mandateBody({ status: "frozen" }) };
+    expect(await apiSource().check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("frozen") });
+    next = { status: 200, hang: true };
+    expect(await apiSource(150).check(MANDATE_ID)).toMatchObject({ status: "unknown", detail: expect.stringContaining("timeout") });
+  });
+});
+
+describe("section 4.7 through the engine, on the API source: executing only on active", () => {
+  it("active: the approved execution reaches executing and settles on the rail", async () => {
+    const h = apiHarness();
+    const id = await approvedThen(h, { status: 200, body: mandateBody() });
+    const out = await h.engine.execute(id);
+    expect(out.state).toBe("settled");
+    expect(h.rail.payCount).toBe(1);
+  });
+
+  const refusals: Array<[string, Answer, string, string]> = [
+    ["paused", { status: 200, body: mandateBody({ status: "paused" }) }, "denied", "mandate_paused"],
+    ["revoked", { status: 200, body: mandateBody({ status: "revoked" }) }, "denied", "mandate_revoked"],
+    ["expired", { status: 200, body: mandateBody({ status: "expired" }) }, "expired", "mandate_expired"],
+    ["500", { status: 500, body: { error: { code: "internal", message: "boom" } } }, "denied", "mandate_status_unavailable"],
+    ["404", { status: 404, body: { error: { code: "mandate_not_found", message: "gone" } } }, "denied", "mandate_status_unavailable"],
+    ["timeout", { status: 200, hang: true }, "denied", "mandate_status_unavailable"],
+  ];
+  for (const [name, answer, state, reason] of refusals) {
+    it(`${name} after approval: ${state} (${reason}), no outbox row, rail.pay never called`, async () => {
+      const h = apiHarness(name === "timeout" ? apiSource(150) : apiSource());
+      const id = await approvedThen(h, answer);
+      const out = await h.engine.execute(id);
+      expect(out.state).toBe(state);
+      expect(out.reason).toBe(reason);
+      expect(out.detail).toContain(MANDATE_ID);
+      expect(h.store.listOutbox()).toHaveLength(0);
+      expect(h.rail.payCount).toBe(0);
+      // A new request under the same answer is refused before anything is drafted.
+      expect(await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] })).toMatchObject({ ok: false, refused_before_draft: true, reason });
+      expect(h.store.listExecutions()).toHaveLength(1);
+    });
+  }
+
+  it("a source that throws is fail-closed too: mandate_status_unavailable, rail.pay never called", async () => {
+    const h = apiHarness({ check: async () => { throw new Error("socket hang up"); } });
+    expect(await h.engine.draft({ items: [{ payee: "escola", amount: 1000 }] })).toMatchObject({ ok: false, reason: "mandate_status_unavailable" });
+    expect(h.rail.payCount).toBe(0);
+  });
+
+  it("the API source never reports org_paused: the API has no kill-switch read, and the source does not invent one", async () => {
+    expect((await apiSource().check(MANDATE_ID)).org_paused).toBe(false);
+  });
+});

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { parseManifest } from "../src/manifest.js";
+
+const valid = `
+schema: 1
+name: bills-agent
+version: 0.1.0
+approval: [human, mandate]
+default_approval: human
+escalate_above:
+  amount: 150000
+  new_beneficiary: true
+  outside_hours: "22:00-07:00"
+mcp: "@codespar/mcp@0.5.8"
+cli: "@codespar/cli@0.14.0"
+tools: ./tools.json
+guardrails: ./guardrails.json
+mandate_schema: ./mandate.example.json
+events: [commerce.payment.succeeded, commerce.payment.failed]
+channels: [terminal]
+maturity:
+  pix-out: sandbox
+  embedded-consent: sandbox
+  receipt-verification: blocked
+scenarios: ./scenarios/
+evals: ./evals/
+agents_md: ./AGENTS.md
+`;
+
+describe("section 4.3: agent.yaml schema 1", () => {
+  it("parses the example", () => {
+    const m = parseManifest(valid);
+    expect(m.name).toBe("bills-agent");
+    expect(m.escalate_above?.amount).toBe(150000);
+  });
+
+  it("refuses an unpinned mcp or cli, a wrong schema, and an unknown field", () => {
+    expect(() => parseManifest(valid.replace('"@codespar/mcp@0.5.8"', '"@codespar/mcp"'))).toThrow(/mcp/);
+    expect(() => parseManifest(valid.replace('"@codespar/cli@0.14.0"', '"@codespar/cli@latest"'))).toThrow(/cli/);
+    expect(() => parseManifest(valid.replace("schema: 1", "schema: 2"))).toThrow();
+    expect(() => parseManifest(valid + "telemetry: true\n")).toThrow(/unrecognized/i);
+    expect(() => parseManifest(valid.replace("default_approval: human", "default_approval: mandate").replace("approval: [human, mandate]", "approval: [human]"))).toThrow(/default_approval/);
+    expect(() => parseManifest(valid.replace('outside_hours: "22:00-07:00"', 'outside_hours: "10pm-7am"'))).toThrow(/HH:MM/);
+  });
+});