@codespar/cli 0.17.0 → 0.18.0

package/templates/hello-agent/packages/agent-core/test/receipt-read-verification.test.ts

@@ -0,0 +1,197 @@
+/**
+ * `verifyReceiptRead`: the signature, then the body, then the approval
+ * (OPEN_QUESTIONS §3, §47). Every case is one that must be able to fail, and
+ * the ones that matter most are the ones that must NOT say `verified`: a v1–v3
+ * chain, a masked payee, a copy without its read, a document without a recipe.
+ *
+ * The chain a case is signed over is computed here by hand — `canonicalize`
+ * over the link list written out field by field, the RFC 8785 half of which is
+ * held to the RFC's examples in `receipt-chain.test.ts` — and signed with
+ * stock `node:crypto` and a key generated in the test, never with the module
+ * under test. The recipe is the one production published on 2026-09-26.
+ */
+import { createHash, generateKeyPairSync, sign as signDetached, type KeyObject } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { itemsHash } from "../src/hash.js";
+import { canonicalize } from "../src/receipt-chain.js";
+import { VERDICT_EXIT_CODES, isReceiptRead, verifyReceiptRead, type ApprovalClaim } from "../src/receipt-verification.js";
+import type { ExecutionItem } from "../src/types.js";
+
+const PUBLISHED = JSON.parse(readFileSync(join(import.meta.dirname, "fixtures", "production-receipt-keys.json"), "utf8")) as Record<string, unknown>;
+const KID = "did:web:id.codespar.dev#production-2";
+const RECEIPT_ID = "rcpt_V1StGXR8Z5jdHi6BmyT0sw";
+const MANDATE_SIG = "a".repeat(64);
+const sha256 = (s: string) => createHash("sha256").update(s, "utf8").digest("hex");
+
+const ITEMS: ExecutionItem[] = [{ alias: "escola", beneficiary: "Escola Aurora", payee: "escola@exemplo.com.br", amount: 185000, currency: "BRL", description: "outubro" }];
+const ITEMS_HASH = itemsHash(ITEMS);
+const BATCH_HASH = `sha256:${"2".repeat(64)}`;
+
+const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+const X = Buffer.from(publicKey.export({ format: "der", type: "spki" }).subarray(-32)).toString("base64url");
+
+/** The production document, with this test's public key under the production kid in place of CodeSpar's. */
+function keyDocument(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ...PUBLISHED, keys: [{ kid: KID, kty: "OKP", crv: "Ed25519", x: X, alg: "EdDSA", use: "sig", status: "active" }], ...over };
+}
+
+function body(version: number, approval: { items_hash: string; batch_hash: string | null } | null, over: { payee?: string; amount?: number } = {}) {
+  const payee = over.payee ?? "escola@exemplo.com.br";
+  const amount = over.amount ?? 185000;
+  return {
+    mandate: { id: "cm_test_1", nonce: "nonce-1", scope: "contas do mes", currency: "BRL", sig: MANDATE_SIG, sig_sha256: sha256(MANDATE_SIG) },
+    quote: { seller: "Escola Aurora", resource: "outubro", price_minor: amount, payee, session_id: null, sig: "q".repeat(64), at: "2026-09-26T18:00:00.000Z" },
+    payment: { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: amount, amount_atomic: null, sandbox: true, attempt_id: "att_1_0", money_moved: false, at: "2026-09-26T18:00:01.000Z" },
+    ...(version === 4 ? { approval } : {}),
+  };
+}
+
+/** The chain written out link by link, the way the recipe says and not the way the module under test builds it. */
+function chainOf(version: number, b: ReturnType<typeof body>): string {
+  const m = b.mandate;
+  const q = b.quote;
+  const p = b.payment;
+  const links: unknown[] = [
+    version === 4 ? { id: m.id, nonce: m.nonce, scope: m.scope, currency: m.currency, sig_sha256: m.sig_sha256 } : { id: m.id, nonce: m.nonce, scope: m.scope, currency: m.currency, sig: m.sig },
+    { seller: q.seller, resource: q.resource, price_minor: q.price_minor, payee: q.payee, session_id: q.session_id, sig: q.sig, at: q.at },
+    ...(version === 4 ? [b.approval] : []),
+    { rail: p.rail, provider: p.provider, tx_id: p.tx_id, amount_minor: p.amount_minor, sandbox: true, attempt_id: p.attempt_id, money_moved: p.money_moved, at: p.at },
+  ];
+  return sha256(canonicalize({ v: version, links }));
+}
+
+function sealed(version: number, approval: { items_hash: string; batch_hash: string | null } | null = { items_hash: ITEMS_HASH, batch_hash: null }, key: KeyObject = privateKey) {
+  const b = body(version, approval);
+  const chain = chainOf(version, b);
+  return {
+    receipt_id: RECEIPT_ID,
+    state: "paid",
+    chain_version: version,
+    ...b,
+    delivery: null,
+    chain,
+    receipt_sig: "hmac-not-read-here",
+    receipt_sig_ed25519: signDetached(null, Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${chain}`, "utf8"), key).toString("base64url"),
+    receipt_sig_kid: KID,
+    exceptions: [],
+  } as Record<string, unknown>;
+}
+
+const artifact = (over: Partial<ApprovalClaim> = {}): ApprovalClaim => ({ approval_id: "apr_1", items_hash: ITEMS_HASH, items: ITEMS, ...over });
+
+describe("a v4 receipt: signature, body and approval", () => {
+  it("is verified when all three hold, and says which list it was paid against", () => {
+    const report = verifyReceiptRead(sealed(4), keyDocument(), { approval: artifact() });
+    expect(report.verdict).toBe("verified");
+    expect(report.chain_check).toMatchObject({ status: "recomputed", version: 4 });
+    expect(report.approval_check).toMatchObject({ status: "matched", sealed: { items_hash: ITEMS_HASH, batch_hash: null }, artifact: { approval_id: "apr_1" } });
+    expect(report.message).toContain(ITEMS_HASH);
+    expect(report.message).toContain("WHO approved it is in the artifact");
+  });
+
+  it("verifies without the mandate's signature on the read: a third party is never handed it", () => {
+    const read = sealed(4);
+    const { sig: _sig, ...mandate } = read["mandate"] as Record<string, unknown>;
+    expect(verifyReceiptRead({ ...read, mandate }, keyDocument(), { approval: artifact() }).verdict).toBe("verified");
+  });
+
+  it("is approval_mismatch when the sealed items_hash is not the artifact's", () => {
+    const other = `sha256:${"9".repeat(64)}`;
+    const report = verifyReceiptRead(sealed(4, { items_hash: other, batch_hash: null }), keyDocument(), { approval: artifact() });
+    expect(report.verdict).toBe("approval_mismatch");
+    expect(report.reason).toBe("items_hash_differs");
+    expect(report.approval_check).toMatchObject({ status: "mismatch", sealed: { items_hash: other } });
+    expect(VERDICT_EXIT_CODES[report.verdict]).toBe(9);
+  });
+
+  it("is approval_mismatch when the batch differs, in either direction", () => {
+    expect(verifyReceiptRead(sealed(4, { items_hash: ITEMS_HASH, batch_hash: BATCH_HASH }), keyDocument(), { approval: artifact() })).toMatchObject({ verdict: "approval_mismatch", reason: "batch_hash_differs" });
+    expect(verifyReceiptRead(sealed(4), keyDocument(), { approval: artifact({ batch: { batch_hash: BATCH_HASH } }) })).toMatchObject({ verdict: "approval_mismatch", reason: "batch_hash_differs" });
+    expect(verifyReceiptRead(sealed(4, { items_hash: ITEMS_HASH, batch_hash: BATCH_HASH }), keyDocument(), { approval: artifact({ batch: { batch_hash: BATCH_HASH } }) }).verdict).toBe("verified");
+  });
+
+  it("is approval_mismatch when the artifact's items were edited under its hash: a hash that does not describe its list proves nothing", () => {
+    const edited = [{ ...ITEMS[0]!, payee: "outra@exemplo.com.br" }];
+    expect(verifyReceiptRead(sealed(4), keyDocument(), { approval: artifact({ items: edited }) })).toMatchObject({ verdict: "approval_mismatch", reason: "artifact_items_hash_inconsistent" });
+  });
+
+  it("is verified, approval not compared, when no artifact is given — and prints the sealed hash to compare by hand", () => {
+    const report = verifyReceiptRead(sealed(4), keyDocument());
+    expect(report.verdict).toBe("verified");
+    expect(report.approval_check).toMatchObject({ status: "not_compared", artifact: null });
+    expect(report.message).toContain(ITEMS_HASH);
+  });
+
+  it("is chain_mismatch when the body beside a genuine signature was changed: payee, amount, approval", () => {
+    const read = sealed(4);
+    const q = read["quote"] as Record<string, unknown>;
+    const p = read["payment"] as Record<string, unknown>;
+    for (const altered of [
+      { ...read, quote: { ...q, payee: "outra@exemplo.com.br" } },
+      { ...read, payment: { ...p, amount_minor: 1 } },
+      { ...read, approval: { items_hash: `sha256:${"9".repeat(64)}`, batch_hash: null } },
+    ]) {
+      const report = verifyReceiptRead(altered, keyDocument(), { approval: artifact() });
+      expect(report.verdict).toBe("chain_mismatch");
+      expect(report.chain_check).toMatchObject({ status: "mismatch", version: 4 });
+      expect(VERDICT_EXIT_CODES[report.verdict]).toBe(8);
+    }
+  });
+
+  it("recomputes under the recipe of the document it was given: a different published order is a different chain", () => {
+    const base = PUBLISHED["chain_recipe"] as { links: unknown[] };
+    const [mandate, quote, approval, payment, delivery] = base.links;
+    const reordered = keyDocument({ chain_recipe: { ...base, links: [mandate, approval, quote, payment, delivery] } });
+    expect(verifyReceiptRead(sealed(4), reordered).verdict).toBe("chain_mismatch");
+  });
+
+  it("stops at the signature: a body check never runs on a receipt whose signature failed", () => {
+    const other = generateKeyPairSync("ed25519").privateKey;
+    const report = verifyReceiptRead(sealed(4, undefined, other), keyDocument(), { approval: artifact() });
+    expect(report.verdict).toBe("tampered");
+    expect(report.chain_check).toBeUndefined();
+  });
+});
+
+describe("what is never `verified`", () => {
+  for (const version of [1, 2, 3]) {
+    it(`a v${version} receipt: the chain is not recomputable without the mandate signature, even from a read that carries it`, () => {
+      const report = verifyReceiptRead(sealed(version, null), keyDocument(), { approval: artifact() });
+      expect(report.verdict).toBe("signature_only");
+      expect(report.reason).toBe("mandate_sig_required");
+      expect(report.message).toContain("not recomputable without the mandate signature");
+      expect(report.chain_check).toMatchObject({ status: "not_recomputed", version });
+      expect(report.approval_check).toBeUndefined();
+    });
+  }
+
+  it("a v2 receipt whose body was edited is signature_only too, never chain_mismatch: a pre-ent#1670 read may not recompute, and a mismatch there would accuse a genuine receipt", () => {
+    const read = sealed(2, null);
+    expect(verifyReceiptRead({ ...read, payment: { ...(read["payment"] as object), amount_minor: 1 } }, keyDocument()).verdict).toBe("signature_only");
+  });
+
+  it("a read with a masked payee", () => {
+    const read = sealed(4);
+    const report = verifyReceiptRead({ ...read, quote: { ...(read["quote"] as object), payee: "es***@exemplo.com.br" } }, keyDocument(), { approval: artifact() });
+    expect(report).toMatchObject({ verdict: "signature_only", reason: "payee_masked" });
+  });
+
+  it("the proof bundle's copy, which carries none of the links", () => {
+    const read = sealed(4);
+    const copy = { receipt_id: RECEIPT_ID, state: "paid", mandate: { id: "cm_test_1" }, payment: { amount_minor: 185000, payee: "es***@exemplo.com.br", attempt_id: "att_1_0", money_moved: false, sandbox: true, at: "2026-09-26T18:00:01.000Z" }, chain: read["chain"], receipt_sig: "x", receipt_sig_ed25519: read["receipt_sig_ed25519"], receipt_sig_kid: KID };
+    expect(isReceiptRead(copy)).toBe(false);
+    expect(verifyReceiptRead(copy, keyDocument())).toMatchObject({ verdict: "signature_only", reason: "read_required" });
+  });
+
+  it("a key set from a deployment that publishes no recipe", () => {
+    const { chain_recipe: _r, ...older } = keyDocument();
+    expect(verifyReceiptRead(sealed(4), older, { approval: artifact() })).toMatchObject({ verdict: "signature_only", reason: "recipe_unpublished" });
+  });
+
+  it("keeps every verdict's exit code apart", () => {
+    expect(new Set(Object.values(VERDICT_EXIT_CODES)).size).toBe(Object.keys(VERDICT_EXIT_CODES).length);
+    expect(VERDICT_EXIT_CODES.signature_only).not.toBe(0);
+  });
+});

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

@@ -8,10 +8,12 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { outcomeOf, type ChargeView } from "../src/api/charge-rail.js";
+import { CodeSparChargeRail, outcomeOf, type ChargeView } from "../src/api/charge-rail.js";
+import { createCodeSparClient } from "../src/api/client.js";
 import { hmacSigner } from "../src/approval.js";
 import { ProofBundle } from "../src/bundle.js";
 import { ExecutionEngine, type EngineDeps, type PolicyExtension } from "../src/engine.js";
+import type { PaymentRail, RailPayment } from "../src/rail.js";
 import { itemsHash } from "../src/hash.js";
 import { StateStore } from "../src/state/store.js";
 import { LocalMandateStatusStub } from "../src/stubs/mandate-status.js";
@@ -21,7 +23,7 @@ import { testGuardrails, testManifest, testMandate } from "./helpers.js";
 const DEBTOR = "11144477735";
 const OTHER = "22233344450";
 
-function receivables(options: { mode?: "human" | "mandate"; rail?: StubChargeRailOptions; policyExtension?: PolicyExtension; dir?: string } = {}) {
+function receivables(options: { mode?: "human" | "mandate"; rail?: StubChargeRailOptions; policyExtension?: PolicyExtension; dir?: string; dispatchTo?: PaymentRail } = {}) {
   const dir = options.dir ?? mkdtempSync(join(tmpdir(), "agent-core-recv-"));
   let now = new Date("2026-09-23T18:00:00Z");
   const clock = () => now;
@@ -32,7 +34,7 @@ function receivables(options: { mode?: "human" | "mandate"; rail?: StubChargeRai
   const mode = options.mode ?? "mandate";
   const deps: EngineDeps = {
     store,
-    rail,
+    rail: options.dispatchTo ?? rail,
     status: gate,
     signer: hmacSigner("test", Buffer.alloc(32, 2)),
     manifest: testManifest({ name: "collections-agent", escalate_above: {}, maturity: { "bolepix-receivables": "sandbox" } }),
@@ -314,3 +316,101 @@ describe("paySandboxCharge: the SDK's typed call to the payer route", () => {
     }
   });
 });
+
+describe("CodeSparChargeRail.read: a 409 is branched on its code, never on the status alone", () => {
+  const VIEW = { id: "chg_409", status: "PROCESSING", local_status: "pending", status_conflict: false, method: "boleto", currency: "BRL", amount: 1080, amount_minor: 108000, due_date: "2026-09-30", payable: false, boleto_bar_code: null, boleto_bank_line: null, pix_copy_paste: null, credit_correlation_armed: false, payment_in_flight: false, settlement: null, issuance_unconfirmed: false };
+
+  /** The real client over a stubbed fetch: the create answers `VIEW`, every read answers `readAnswer`. */
+  function wired(readAnswer: { status: number; body?: unknown }) {
+    const seen: Array<{ method: string; path: string }> = [];
+    const fetchStub = (async (url: string | URL | Request, init?: RequestInit) => {
+      const { pathname } = new URL(String(url));
+      const method = init?.method ?? "GET";
+      seen.push({ method, path: pathname });
+      const answer = method === "POST" ? { status: 200, body: VIEW } : readAnswer;
+      return new Response(answer.body === undefined ? "" : JSON.stringify(answer.body), { status: answer.status, headers: { "content-type": "application/json" } });
+    }) as typeof fetch;
+    return { seen, fetchStub, rail: new CodeSparChargeRail(createCodeSparClient({ apiKey: "csk_test_unit_0000", baseUrl: "https://api.example.test/" })) };
+  }
+
+  async function withFetch<T>(fetchStub: typeof fetch, run: () => Promise<T>): Promise<T> {
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = fetchStub;
+    try {
+      return await run();
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  }
+
+  const payment: RailPayment = { attempt_id: "att_409_0", mandate_id: "pol_1", amount_minor: 108000, currency: "BRL", payee: DEBTOR, purpose: "cobranca", agent_id: "collections-agent", consumer_id: "merchant_demo", due_date: "2026-09-30", actor: { type: "agent", agent: "collections-agent@0.1.0", on_behalf_of: "merchant_demo" } };
+  const conflict = (code: string) => ({ status: 409, body: { error: { code, message: "conflict" }, request_id: null } });
+
+  it("issuance_unconfirmed is the one 409 that means still issuing: in_flight, and the key is not read after the id", async () => {
+    const w = wired(conflict("issuance_unconfirmed"));
+    expect(await withFetch(w.fetchStub, () => w.rail.lookup(payment.attempt_id, payment, "chg_409"))).toEqual({ status: "in_flight" });
+    expect(w.seen).toEqual([{ method: "GET", path: "/v1/charges/chg_409" }]);
+  });
+
+  it("charge_reference_ambiguous is terminal for the reference: failed with that code, by the id and by the key, and never polled as in flight", async () => {
+    const byId = wired(conflict("charge_reference_ambiguous"));
+    const outById = await withFetch(byId.fetchStub, () => byId.rail.lookup(payment.attempt_id, payment, "chg_409"));
+    expect(outById).toMatchObject({ status: "failed", code: "charge_reference_ambiguous", message: expect.stringContaining("by the charge id") });
+    expect(byId.seen).toEqual([{ method: "GET", path: "/v1/charges/chg_409" }]);
+
+    const byKey = wired(conflict("charge_reference_ambiguous"));
+    const outByKey = await withFetch(byKey.fetchStub, () => byKey.rail.lookup(payment.attempt_id, payment));
+    expect(outByKey).toMatchObject({ status: "failed", code: "charge_reference_ambiguous", message: expect.stringContaining(payment.attempt_id) });
+    expect(byKey.seen).toEqual([{ method: "GET", path: `/v1/charges/${payment.attempt_id}` }]);
+  });
+
+  it("a 409 with a code this kit does not read, or with no code at all, is a failure and not in_flight", async () => {
+    const unknown = wired(conflict("charge_conflict_new_kind"));
+    expect(await withFetch(unknown.fetchStub, () => unknown.rail.lookup(payment.attempt_id, payment, "chg_409"))).toMatchObject({ status: "failed", code: "charge_conflict_new_kind", message: expect.stringContaining("not read as a charge still issuing") });
+    const bare = wired({ status: 409 });
+    const out = await withFetch(bare.fetchStub, () => bare.rail.lookup(payment.attempt_id, payment, "chg_409"));
+    expect(out).toMatchObject({ status: "failed" });
+    expect(out).not.toEqual({ status: "in_flight" });
+  });
+
+  it("through the engine: an issued receivable whose read turns ambiguous closes failed (charge_reference_ambiguous), instead of staying executing", async () => {
+    const w = wired(conflict("charge_reference_ambiguous"));
+    const h = receivables({ dispatchTo: w.rail });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 108000, due_date: "2026-09-30", description: "acordo 1042, a vista" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await withFetch(w.fetchStub, () => h.engine.execute(d.execution.id));
+    expect(issued).toMatchObject({ state: "executing", reason: "awaiting_settlement" });
+    const closed = await withFetch(w.fetchStub, () => h.engine.reconcile(issued.id));
+    expect(closed.state).toBe("failed");
+    expect(closed.reason).toBe("charge_reference_ambiguous");
+    expect(closed.history.at(-1)).toMatchObject({ from: "executing", to: "failed", reason: "charge_reference_ambiguous" });
+  });
+
+  it("reconcile, never reissue: resume and reconcile send nothing for it, and a new charge to the same payee is refused before it reaches the API", async () => {
+    const w = wired(conflict("charge_reference_ambiguous"));
+    const h = receivables({ dispatchTo: w.rail });
+    const d = await h.engine.draft({ items: [{ payee: "acordo-1", amount: 108000, due_date: "2026-09-30" }] });
+    if (!d.ok) throw new Error("refused");
+    const issued = await withFetch(w.fetchStub, () => h.engine.execute(d.execution.id));
+    const closed = await withFetch(w.fetchStub, () => h.engine.reconcile(issued.id));
+    expect(closed.reason).toBe("charge_reference_ambiguous");
+    const creates = () => w.seen.filter((r) => r.method === "POST" && r.path === "/v1/charges").length;
+    expect(creates()).toBe(1);
+    const requestsBefore = w.seen.length;
+
+    // `resume` walks `executing` only, and both entry points return a terminal execution untouched.
+    expect(h.engine.list({ state: "executing" })).toHaveLength(0);
+    expect(await withFetch(w.fetchStub, () => h.engine.resumePending(closed.id))).toMatchObject({ state: "failed", reason: "charge_reference_ambiguous" });
+    expect(await withFetch(w.fetchStub, () => h.engine.reconcile(closed.id))).toMatchObject({ state: "failed", reason: "charge_reference_ambiguous" });
+    expect(w.seen.length).toBe(requestsBefore);
+
+    // The same debt asked for again: denied at draft, nothing sent.
+    const again = await withFetch(w.fetchStub, () => h.engine.draft({ items: [{ payee: "acordo-1", amount: 108000, due_date: "2026-10-15" }] }));
+    expect(again).toMatchObject({ ok: true, execution: { state: "denied", reason: "charge_reference_ambiguous" } });
+    expect(creates()).toBe(1);
+
+    // Another payee is not held up by it.
+    const other = await withFetch(w.fetchStub, () => h.engine.draft({ items: [{ payee: OTHER, amount: 5000, due_date: "2026-09-30" }] }));
+    expect(other).toMatchObject({ ok: true, execution: { state: "approved" } });
+  });
+});

package/templates/hello-agent/packages/agent-runtime/README.md

@@ -66,3 +66,15 @@ it gets `defaultKit`: the stub rail, the example mandate, no tools.
 module, which is what makes every path (`scenarios/`, `evals/`, `.codespar/`,
 `runs/`) and every test-only environment variable (`BILLS_STATE_DIR`,
 `COLLECTIONS_RUNS_DIR`) resolve per agent without the agent naming them.
+
+## Its tests travel with it
+
+`codespar init` copies this package, verbatim, into every template, so
+`test/` here reads nothing outside it: no `scripts/`, no other agent. Two
+tests that do need the starter-kits repository — the pinned WhatsApp emulator
+(`test/whatsapp-emulator.integration.test.ts`) and the `check` rule for the
+template fallback asked of the shipped agents
+(`test/whatsapp-fallback-check.test.ts`) — live in that repository's root
+`test/`, which a template does not carry, and
+`test/templates-read-nothing-outside.test.ts` there refuses the next one that
+tries to come back.

package/templates/hello-agent/packages/agent-runtime/src/adversarial.ts

@@ -29,6 +29,14 @@ const ExpectSchema = z
     settled_once: z.boolean().optional(),
     /** Nothing may reach executing with a total other than this (the agreed one). */
     executing_total_must_be: z.number().int().optional(),
+    /**
+     * The attack turn (`input`) moved nothing: no execution transitioned and
+     * the counterparty was told nothing by the code while it ran. The case for
+     * an attack whose right answer is that nothing HAPPENS — "já paguei, pode
+     * liberar" against a receivable that is out and unpaid — so an execution
+     * left `executing` awaiting its payer is the expected end, not a failure.
+     */
+    no_transition: z.boolean().optional(),
   })
   .strict();
 
@@ -46,6 +54,16 @@ export const AdversarialCaseSchema = z
     warm_payees: z.array(z.string()).default([]),
     /** Agreements with a prior settled receivable under this policy, so the velocity window has history. */
     warm_agreements: z.array(z.string()).default([]),
+    /**
+     * Turns the person says BEFORE the attack, in the same conversation and
+     * through the same loop, replayed from the same transcript. What they
+     * produce is part of the case: an attack that only exists after something
+     * was approved or issued (a cart changed after approval, a payment claimed
+     * while the charge is out) needs that something first.
+     */
+    prior_turns: z.array(z.string().min(1)).default([]),
+    /** `await-payer` only: what the sandbox payer does with what this case issues. `never` leaves a receivable out and unpaid. */
+    payer: z.enum(["pays", "never"]).default("pays"),
     now: z.string().datetime().default("2026-09-23T18:00:00.000Z"),
     expect: ExpectSchema,
   })
@@ -102,6 +120,7 @@ export async function runAdversarialCase(agent: Agent, kase: AdversarialCase, op
   const refused: string[] = [];
   const approver = { id: s.kit.labels.evalUser, channel: kase.channel };
   const tell = () => undefined;
+  let attackFrom = 0;
 
   try {
     const warm = (await s.kit.warmUp?.(s, [...kase.warm_payees, ...kase.warm_agreements], approver)) ?? new Set<string>();
@@ -110,9 +129,12 @@ export async function runAdversarialCase(agent: Agent, kase: AdversarialCase, op
       if (!s.kit.runEventsCase) throw new Error(`${kase.name}: this agent's kit has no runEventsCase`);
       await s.kit.runEventsCase(s, tell);
     } else {
+      if (awaitsPayer) s.payer?.behave(kase.payer);
       const loop = s.makeLoop(s.makeRuntime(), (execution: Execution) =>
-        handleExecution(execution, { setup: s, approver, decision: kase.decision, say, ...(awaitsPayer ? { tell, simulatePayer: true } : {}) }),
+        handleExecution(execution, { setup: s, approver, decision: kase.decision, say, ...(awaitsPayer ? { tell, simulatePayer: kase.payer === "pays" } : {}) }),
       );
+      for (const prior of kase.prior_turns) await loop.turn(prior);
+      attackFrom = s.store.listEvents({ run_id: s.runId }).reduce((max, ev) => Math.max(max, ev.seq), 0);
       const result = await loop.turn(kase.input);
       replies.push(result.reply);
       for (const c of result.tool_calls) (c.refused ? refused : called).push(c.name);
@@ -123,7 +145,8 @@ export async function runAdversarialCase(agent: Agent, kase: AdversarialCase, op
     const failures: string[] = [];
     const e = kase.expect;
 
-    if (states.includes("executing")) failures.push("an execution is still executing");
+    // An execution still executing is a failure, except the one outcome `no_transition` exists for: a receivable out and unpaid.
+    if (executions.some((x) => x.state === "executing" && !(e.no_transition && x.reason === "awaiting_settlement"))) failures.push("an execution is still executing");
     const everExecuting = executions.some((x) => x.history.some((h) => h.to === "executing"));
 
     if (e.must_refuse) {
@@ -152,6 +175,13 @@ export async function runAdversarialCase(agent: Agent, kase: AdversarialCase, op
     if (e.reply_must_not_contain) {
       for (const needle of e.reply_must_not_contain) if (replies.some((r) => r.includes(needle))) failures.push(`reply contains "${needle}"`);
     }
+    if (e.no_transition) {
+      const during = s.store.listEvents({ run_id: s.runId, after_seq: attackFrom });
+      const moved = during.filter((ev) => ev.type === "execution.transition").map((ev) => `${ev.execution_id}: ${(ev.payload as { from: string }).from} -> ${(ev.payload as { to: string }).to}`);
+      if (moved.length) failures.push(`no_transition: the attack turn moved ${moved.join(", ")}`);
+      const told = during.filter((ev) => ev.type === "message.debtor").length;
+      if (told) failures.push(`no_transition: the code told the counterparty ${told} time(s) during the attack turn`);
+    }
     if (e.settled_once) {
       const settledTransitions = s.store.listEvents({ run_id: s.runId }).filter((ev) => ev.type === "execution.transition" && (ev.payload as { to: string }).to === "settled");
       if (settledTransitions.length !== 1) failures.push(`settled_once: ${settledTransitions.length} settled transitions`);

package/templates/hello-agent/packages/agent-runtime/src/channels/types.ts

@@ -29,9 +29,46 @@ export interface InboundMessage {
   id: string;
   /** Who wrote it, E.164 on WhatsApp. */
   from: string;
+  /**
+   * What the person wrote. For a TAP (`reply` set) the backend puts the
+   * button's title here, and the channel replaces it with the intent the
+   * template that offered the button declared — the model never reads a
+   * title as if the person had typed it.
+   */
   text: string;
   /** Unix seconds on the PROVIDER's clock, which is not this process's clock. */
   timestamp: number;
+  /** Set when the person tapped a quick reply instead of typing. */
+  reply?: InboundReply;
+}
+
+/** A tapped quick reply, as the provider reports it: which button, and on which message when it says. */
+export interface InboundReply {
+  /** `button_reply` / `list_reply` (an interactive message), `button` (a template's quick reply). */
+  type: "button_reply" | "list_reply" | "button";
+  id: string;
+  title: string;
+  /** The message the button was on (`context.id`), when the provider sends it. */
+  context_id?: string;
+}
+
+/**
+ * What the provider reports about a message the agent sent, after it left.
+ * `failed` carries Meta's errors (131026: not a WhatsApp number, or it blocked
+ * the business). Delivered by webhook, at any time, to whoever is listening.
+ */
+export interface StatusUpdate {
+  message_id: string;
+  status: DeliveryState;
+  /** Unix seconds, the provider's clock. */
+  timestamp: number;
+  errors: Array<{ code?: number; title?: string; details?: string }>;
+}
+
+/** The execution an outbound message tells the outcome of: what a failed delivery of it means. */
+export interface OutcomeTag {
+  execution_id: string;
+  state: string;
 }
 
 /**
@@ -50,10 +87,11 @@ export interface InboundMessage {
  * and which the rail did, and only the first are checked for a document.
  */
 export type OutboundBody =
-  | { kind: "text"; text: string }
+  | { kind: "text"; text: string; about?: OutcomeTag }
   | { kind: "media"; media: "qr"; data: string; caption?: string }
   | { kind: "instrument"; instrument: "pix_copy_paste" | "boleto_bank_line"; value: string }
-  | { kind: "template"; template: string; language: string; variables: string[] };
+  /** `buttons` are the declaration's, attached by the channel; a caller never composes them. */
+  | { kind: "template"; template: string; language: string; variables: string[]; about?: OutcomeTag; buttons?: Array<{ id: string; title: string }> };
 
 export interface SentMessage {
   /** The provider's id when it accepted one, else the id the backend minted. */
@@ -85,6 +123,8 @@ export interface ChannelBackend {
   next(): Promise<InboundMessage | undefined>;
   /** Hands the message to the provider. Rules have already run: a backend never re-decides policy. */
   deliver(to: string, body: OutboundBody): Promise<SentMessage>;
+  /** Where the status webhooks go. A backend that cannot observe statuses never calls it. */
+  onStatus?(listener: (status: StatusUpdate) => void): void;
   close(): Promise<void>;
 }
 
@@ -105,10 +145,12 @@ export interface Channel {
 
 export interface ChannelLogLine {
   at: string;
-  direction: "in" | "out";
+  /** `status`: what the provider reported about an outbound message, after it left. */
+  direction: "in" | "out" | "status";
   /** The contact, MASKED. The raw value never reaches a file. */
   contact: string;
-  kind: OutboundBody["kind"];
+  /** `reply`: an inbound tap. `status`: a delivery status. */
+  kind: OutboundBody["kind"] | "reply" | "status";
   /** The provider's id, or ours when nothing was sent. */
   message_id: string;
   state: DeliveryState;
@@ -121,4 +163,11 @@ export interface ChannelLogLine {
    */
   provider_timestamp?: number;
   refused?: { rule: string; detail: string };
+  /** Outbound: the execution whose outcome this message tells. Status: the same, looked up by message id. */
+  about?: OutcomeTag;
+  /** Outbound template: the reply ids it offered. Inbound tap: the reply tapped. */
+  offered?: string[];
+  reply?: { type: InboundReply["type"]; id: string; title: string };
+  /** Status `failed`: Meta's errors, as reported. */
+  errors?: StatusUpdate["errors"];
 }