@codespar/cli 0.17.0 → 0.18.1

package/templates/collections-agent/packages/agent-runtime/src/commands/verify.ts

@@ -1,31 +1,66 @@
 /**
- * `codespar-agent verify <receipt-file> [--json] [--keys <file>] [--url <url>]`:
+ * `codespar-agent verify <receipt-file> [--json] [--keys <file> | --url <url>] [--approval <file> [--approval-id <id>]] [--from-api]`:
  * the wave-5 gate — someone outside verifies a receipt without access to
- * CodeSpar.
+ * CodeSpar — and, since ent#1670, the body and the approval behind it.
  *
- * It takes a receipt JSON, fetches the public key set over plain HTTPS (or
- * reads a copy off disk, for a machine with no network), and checks the
- * Ed25519 signature with stock `node:crypto`. No CodeSpar key, no API key, no
- * SDK call: the verifier holds nothing, and that is what makes the answer
- * worth anything. It is the one command here that does NOT need an agent —
- * `cli.ts` dispatches it before it looks for an `agent.yaml` — because the
- * file it reads has usually been copied off the machine that produced it.
+ * Three checks, in order, each one only on the answer of the one before:
+ *
+ *   1. The Ed25519 signature over `codespar-receipt:v1:<id>:<chain>`, against
+ *      the public key set, fetched over plain HTTPS or read off disk.
+ *   2. The chain, recomputed from the API's receipt READ under the
+ *      `chain_recipe` the SAME key document publishes, held against the
+ *      signed one: this is what binds the payee, the amount and the approval
+ *      to the signature.
+ *   3. For a v4 chain, the sealed approval link held against the local
+ *      approval artifact: "this payment was made against the list H".
+ *
+ * The receipt file is either the read itself — what a tenant hands a third
+ * party, payee unmasked; checked with no credential at all — or a copy from a
+ * run's `runs/<run-id>/receipts/`, which masks the payee and carries none of
+ * the links. A copy reaches check 2 only with `--from-api`: the tenant's
+ * `CODESPAR_API_KEY` (the environment, or the `.env` of the agent the copy
+ * sits in) reads the receipt from the API, in memory, and nothing unmasked is
+ * written anywhere. Without it a copy answers `signature_only`, which is the
+ * truth about what a masked copy can prove. The approval artifact of a copy
+ * is the one its `approval_id` names in the run's own `approval.json`.
+ *
+ * It is the one command here that does NOT need an agent — `cli.ts`
+ * dispatches it before it looks for an `agent.yaml` — because the file it
+ * reads has usually been copied off the machine that produced it.
  *
  * `--json` follows the rule of section 14.5: machine data on stdout, valid
  * JSON and nothing else, human sentences on stderr. The exit code is the
  * verdict (`VERDICT_EXIT_CODES`), so a script branches on WHICH answer it got
  * rather than on "did it fail" — an unsigned receipt is not a failure and must
- * not exit 0 either.
+ * not exit 0 either, and neither is a signature whose body was not bound.
  */
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { stderr, stdout } from "node:process";
-import { DEFAULT_RECEIPT_KEYS_URL, VERDICT_EXIT_CODES, verifyReceipt, type KeySource, type ReceiptVerification } from "@codespar/agent-core";
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_RECEIPT_KEYS_URL,
+  VERDICT_EXIT_CODES,
+  copyDisagreesWithRead,
+  createCodeSparClient,
+  describeApiError,
+  isReceiptRead,
+  readSignedReceipt,
+  receiptKeysUrl,
+  signatureOnly,
+  verifyReceiptRead,
+  verifyReceiptWithKeys,
+  type ApprovalClaim,
+  type ExecutionItem,
+  type ReceiptVerification,
+} from "@codespar/agent-core";
+import { findAgentDir } from "../agent.js";
+import { readDotEnv } from "../setup.js";
 
-const USAGE = "usage: npm run verify <receipt-file> [--json] [--keys <key-set.json>] [--url <https://.../.well-known/codespar-receipt-keys.json>]";
+const USAGE =
+  "usage: npm run verify <receipt-file> [--json] [--keys <key-set.json> | --url <https://.../.well-known/codespar-receipt-keys.json>] [--approval <approval.json> [--approval-id <apr_...>]] [--from-api]";
 
-/** The fetcher the module is given. The only network in this feature, and it
- *  lives here rather than in the core so a unit test injects its own. */
+/** The fetcher the key set comes through: the one unauthenticated call in this command. */
 async function fetchKeyDocument(url: string): Promise<unknown> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 10_000);
@@ -38,69 +73,226 @@ async function fetchKeyDocument(url: string): Promise<unknown> {
   }
 }
 
+interface Args {
+  json: boolean;
+  keysFile?: string;
+  url?: string;
+  approvalFile?: string;
+  approvalId?: string;
+  fromApi: boolean;
+  receiptFile?: string;
+}
+
+const VALUED: readonly string[] = ["--keys", "--url", "--approval", "--approval-id"];
+
 export async function verify(argv: string[]): Promise<number> {
   const say = (line: string) => stderr.write(line + "\n");
-  let json = false;
-  let keysFile: string | undefined;
-  let url: string | undefined;
-  let receiptFile: string | undefined;
+  const args: Args = { json: false, fromApi: false };
 
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i]!;
-    if (a === "--json") json = true;
-    else if (a === "--keys" || a === "--url") {
+    if (a === "--json") args.json = true;
+    else if (a === "--from-api") args.fromApi = true;
+    else if (VALUED.includes(a)) {
       const value = argv[i + 1];
       if (value === undefined || value.startsWith("--")) {
         say(`${a} needs a value\n${USAGE}`);
         return 2;
       }
-      if (a === "--keys") keysFile = value;
-      else url = value;
+      if (a === "--keys") args.keysFile = value;
+      else if (a === "--url") args.url = value;
+      else if (a === "--approval") args.approvalFile = value;
+      else args.approvalId = value;
       i += 1;
     } else if (a === "--help" || a === "-h") {
       say(USAGE);
       say(`the key set is public and needs no credential; its default is ${DEFAULT_RECEIPT_KEYS_URL}`);
       say("--keys reads a saved copy of that document instead, so the check runs with no network at all");
+      say("the receipt file is the API's read (GET /v1/consumers/receipts/{id}), whose body is recomputed against the signed chain, or a run's copy, which proves the signature only");
+      say("--from-api reads a run's copy from the API with CODESPAR_API_KEY (in memory, nothing written), so its body and its approval are checked too; the key set then defaults to that deployment's");
+      say("--approval holds a v4 receipt's sealed approval link against an approval artifact (a run's copy uses its own approval.json)");
       return 0;
     } else if (a.startsWith("-")) {
       say(`unknown argument ${a}\n${USAGE}`);
       return 2;
-    } else if (receiptFile === undefined) receiptFile = a;
+    } else if (args.receiptFile === undefined) args.receiptFile = a;
     else {
-      say(`verify takes one receipt file (got ${receiptFile} and ${a})\n${USAGE}`);
+      say(`verify takes one receipt file (got ${args.receiptFile} and ${a})\n${USAGE}`);
       return 2;
     }
   }
 
-  if (!receiptFile) {
+  if (!args.receiptFile) {
     say(USAGE);
     say("the receipt is the JSON the API returns from GET /v1/consumers/receipts/{id}, or a copy from a run's runs/<run-id>/receipts/");
     return 2;
   }
-  if (keysFile && url) {
+  if (args.keysFile && args.url) {
     say(`--keys and --url name two different key sets; pass one\n${USAGE}`);
     return 2;
   }
+  if (args.approvalId && !args.approvalFile) {
+    say(`--approval-id picks one artifact out of --approval; pass the file too\n${USAGE}`);
+    return 2;
+  }
 
-  const receipt = readJson(receiptFile, say);
+  const receipt = readJson(args.receiptFile, say);
   if (receipt === undefined) return 2;
 
-  let source: KeySource;
-  if (keysFile) {
-    const document = readJson(keysFile, say);
-    if (document === undefined) return 2;
-    source = { document, label: resolve(keysFile) };
-  } else {
-    source = { url: url ?? DEFAULT_RECEIPT_KEYS_URL, fetch: fetchKeyDocument };
+  // The read and the key set must come from ONE deployment: the recipe that
+  // binds the body is the key document's, and a staging read checked under
+  // production's document is the §47 trap again.
+  const apiBase = process.env["CODESPAR_API_URL"]?.trim() || DEFAULT_BASE_URL;
+  if (args.fromApi && args.url && new URL(args.url).origin !== new URL(apiBase).origin) {
+    say(`--from-api reads the receipt from ${new URL(apiBase).origin} and --url names the key set of ${new URL(args.url).origin}; the read and the key set must come from the same deployment\n${USAGE}`);
+    return 2;
+  }
+
+  let approval: ApprovalClaim | undefined;
+  if (args.approvalFile) {
+    const claim = readApprovalClaim(args.approvalFile, args.approvalId, say);
+    if (!claim) return 2;
+    approval = claim;
+  }
+
+  let keysDocument: unknown;
+  if (args.keysFile) {
+    keysDocument = readJson(args.keysFile, say);
+    if (keysDocument === undefined) return 2;
   }
 
-  const report = await verifyReceipt(receipt, source);
-  if (json) stdout.write(JSON.stringify(report) + "\n");
+  const report = await check(receipt, args, apiBase, approval, keysDocument);
+  if (args.json) stdout.write(JSON.stringify(report) + "\n");
   else stdout.write(render(report));
   say(report.message);
   return VERDICT_EXIT_CODES[report.verdict];
 }
 
+async function check(receipt: unknown, args: Args, apiBase: string, approval: ApprovalClaim | undefined, keysDocument: unknown): Promise<ReceiptVerification> {
+  // Answered before the network is touched, as before: an unsigned or
+  // malformed file needs no key set, and fetching one to check a signature
+  // that is not there would turn an offline answer into an outage.
+  const signed = readSignedReceipt(receipt);
+  if (!signed.ok || signed.fields.receipt_sig_ed25519 === null) return verifyReceiptWithKeys(receipt, { keys: [] }, "none");
+
+  let document: unknown;
+  let label: string;
+  if (args.keysFile) {
+    label = resolve(args.keysFile);
+    document = keysDocument;
+  } else {
+    label = args.url ?? (args.fromApi ? receiptKeysUrl(apiBase) : DEFAULT_RECEIPT_KEYS_URL);
+    try {
+      document = await fetchKeyDocument(label);
+    } catch (err) {
+      return unreachable(
+        signed.fields.receipt_id,
+        label,
+        `the published key set could not be read from ${label}: ${err instanceof Error ? err.message : String(err)}. Nothing is proved and nothing is disproved; the keys can also be saved to a file and passed in`,
+      );
+    }
+  }
+
+  if (isReceiptRead(receipt)) return verifyReceiptRead(receipt, document, { label, ...(approval ? { approval } : {}) });
+
+  // A run's copy: the signature is checked on the copy itself, as it always was.
+  const signature = verifyReceiptWithKeys(receipt, document, label);
+  if (signature.verdict !== "verified") return signature;
+  if (!args.fromApi) {
+    return signatureOnly(signature, "read_required", "this is a run's copy, which masks the payee and carries none of the chain's links. Recompute from the API's read: run this again with --from-api (the tenant's key, read-only, nothing written), or verify the read itself");
+  }
+
+  const read = await readFromApi(signed.fields.receipt_id, args.receiptFile!, apiBase);
+  if (!read.ok) return signatureOnly(signature, "read_unavailable", `the API's read of it could not be fetched (${read.detail}), so nothing is proved and nothing is disproved about the body`);
+  const differs = copyDisagreesWithRead(receipt as Record<string, unknown>, read.body);
+  if (differs.includes("chain")) {
+    // The copy's chain carries a signature that checked above, so a read with another chain is a re-seal, not an edit.
+    return signatureOnly(signature, "read_resealed", "the API's read carries a different chain than this copy: the receipt was re-sealed after the copy was written (a delivery or metering update). Verify the read itself");
+  }
+  if (differs.length > 0) {
+    return {
+      ...signature,
+      verdict: "chain_mismatch",
+      reason: "copy_differs_from_read",
+      message: `receipt ${signature.receipt_id}: this copy says something the sealed receipt does not (${differs.join(", ")}). The signature covers the id and the chain, not the copy's body, so the copy was edited after it was written`,
+      chain_check: { status: "mismatch", version: null, recomputed: null, reason: "copy_differs_from_read" },
+    };
+  }
+  const claim = approval ?? approvalOfCopy(receipt as Record<string, unknown>, args.receiptFile!);
+  return verifyReceiptRead(read.body, document, { label, ...(claim ? { approval: claim } : {}) });
+}
+
+function unreachable(receiptId: string, label: string, message: string): ReceiptVerification {
+  return { verdict: "unreachable", receipt_id: receiptId, kid: null, key_status: null, signing_string: null, keys_from: label, reason: "fetch_failed", message };
+}
+
+/**
+ * The receipt as the API reads it, for a copy, with the tenant's key. The key
+ * is the environment's, or the `.env` of the agent the copy sits in — the
+ * same place `npm start` reads it from — and only a `csk_test_` key is
+ * accepted, like everywhere else in this repository.
+ */
+async function readFromApi(receiptId: string, receiptFile: string, apiBase: string): Promise<{ ok: true; body: Record<string, unknown> } | { ok: false; detail: string }> {
+  const agentDir = findAgentDir(dirname(resolve(receiptFile)));
+  if (agentDir) readDotEnv(agentDir);
+  try {
+    const api = createCodeSparClient({ apiKey: process.env["CODESPAR_API_KEY"], baseUrl: apiBase, projectId: process.env["CODESPAR_PROJECT_ID"], timeoutMs: 15_000 });
+    const body: unknown = await api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
+    if (!isReceiptRead(body)) return { ok: false, detail: "the API answered something that is not a receipt read" };
+    return { ok: true, body };
+  } catch (err) {
+    const failure = describeApiError(err);
+    return { ok: false, detail: `${failure.code}: ${failure.message}` };
+  }
+}
+
+/**
+ * The artifact a run's copy names by `approval_id`, from the same run's
+ * `approval.json`. Found by identity: picking whichever artifact matched the
+ * sealed hash would make a mismatch impossible to see.
+ */
+function approvalOfCopy(copy: Record<string, unknown>, receiptFile: string): ApprovalClaim | undefined {
+  const id = copy["approval_id"];
+  const receipts = dirname(resolve(receiptFile));
+  const path = join(dirname(receipts), "approval.json");
+  if (typeof id !== "string" || basename(receipts) !== "receipts" || !existsSync(path)) return undefined;
+  try {
+    return pickArtifact(JSON.parse(readFileSync(path, "utf8")) as unknown, id);
+  } catch {
+    return undefined;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** One artifact out of an `approval.json` (a list) or a single artifact file, as the part the approval link is held against. */
+function pickArtifact(input: unknown, id: string | undefined): ApprovalClaim | undefined {
+  const candidates = (Array.isArray(input) ? input : [input]).filter((a): a is Record<string, unknown> => isRecord(a) && typeof a["items_hash"] === "string" && typeof a["approval_id"] === "string");
+  const chosen = id === undefined ? (candidates.length === 1 ? candidates[0] : undefined) : candidates.find((a) => a["approval_id"] === id);
+  if (!chosen) return undefined;
+  const batch = chosen["batch"];
+  return {
+    approval_id: chosen["approval_id"] as string,
+    items_hash: chosen["items_hash"] as string,
+    ...(Array.isArray(chosen["items"]) ? { items: chosen["items"] as ExecutionItem[] } : {}),
+    ...(isRecord(batch) && typeof batch["batch_hash"] === "string" ? { batch: { batch_hash: batch["batch_hash"] } } : {}),
+  };
+}
+
+/** `--approval`: `undefined` is a usage error, already said. */
+function readApprovalClaim(path: string, id: string | undefined, say: (line: string) => void): ApprovalClaim | undefined {
+  const input = readJson(path, say);
+  if (input === undefined) return undefined;
+  const claim = pickArtifact(input, id);
+  if (!claim) {
+    const count = Array.isArray(input) ? input.length : 1;
+    say(id ? `${resolve(path)} holds no approval artifact ${id}` : `${resolve(path)} holds ${count} approval artifacts, not one; name the one this payment carried with --approval-id`);
+  }
+  return claim;
+}
+
 /** A file that is missing or is not JSON is a refusal a person can act on, never a stack trace. */
 function readJson(path: string, say: (line: string) => void): unknown {
   let text: string;
@@ -124,6 +316,15 @@ function render(report: ReceiptVerification): string {
   if (report.kid) lines.push(`  key          ${report.kid}${report.key_status ? ` (${report.key_status})` : ""}`);
   if (report.keys_from) lines.push(`  key set      ${report.keys_from}`);
   if (report.signing_string) lines.push(`  signed       ${report.signing_string}`);
+  if (report.chain_check) {
+    const c = report.chain_check;
+    lines.push(`  body         ${c.status}${c.version !== null ? ` (chain v${c.version})` : ""}${c.recomputed && c.status === "mismatch" ? `, recomputes to ${c.recomputed}` : ""}`);
+  }
+  if (report.approval_check) {
+    const a = report.approval_check;
+    lines.push(`  approval     ${a.status}: sealed ${a.sealed.items_hash}${a.sealed.batch_hash ? ` batch ${a.sealed.batch_hash}` : ""}`);
+    if (a.artifact) lines.push(`               artifact ${a.artifact.approval_id} ${a.artifact.items_hash}${a.artifact.batch_hash ? ` batch ${a.artifact.batch_hash}` : ""}`);
+  }
   lines.push(`  reason       ${report.reason}`);
   return lines.join("\n") + "\n";
 }

package/templates/collections-agent/packages/agent-runtime/src/commands/webhook.ts

@@ -8,7 +8,7 @@
 import { stderr, stdout } from "node:process";
 import { envName, type Agent } from "../agent.js";
 import { setup } from "../setup.js";
-import { announceOutcome } from "../terminal.js";
+import { announceOutcome, followUp } from "../terminal.js";
 import { startWebhookServer } from "../webhook.js";
 
 export async function webhook(agent: Agent, argv: string[]): Promise<number> {
@@ -21,8 +21,9 @@ export async function webhook(agent: Agent, argv: string[]): Promise<number> {
     {
       engine: s.engine,
       secret,
-      onClosed: (execution) => {
+      onClosed: async (execution) => {
         announceOutcome(execution, s, (l) => void stdout.write(l + "\n"));
+        await followUp(execution, s, say);
       },
     },
     say,

package/templates/collections-agent/packages/agent-runtime/src/index.ts

@@ -10,3 +10,4 @@ export * from "./scenarios.js";
 export * from "./adversarial.js";
 export * from "./inspect.js";
 export { main } from "./cli.js";
+export { pollWhatsApp, type PollWhatsAppOptions } from "./commands/poll-whatsapp.js";

package/templates/collections-agent/packages/agent-runtime/src/inspect.ts

@@ -18,7 +18,7 @@
  * text: a debtor's own words are in `transcript.jsonl` and are not this
  * command's to re-publish.
  */
-import { maskPayee, type ApprovalArtifact, type ExecutionBatch, type ProofBundle } from "@codespar/agent-core";
+import { maskPayee, type ApprovalArtifact, type ExecutionBatch, type ExecutionComposition, type ProofBundle } from "@codespar/agent-core";
 import { formatMinor } from "./default-kit.js";
 
 export interface InspectItem {
@@ -87,6 +87,8 @@ export interface InspectExecution {
     items_hash: string;
     /** The set binding as the ARTIFACT carries it, which is the signed copy. */
     batch: ExecutionBatch | null;
+    /** What the single amount was composed of (a cart), as the artifact signed it. */
+    composition?: ExecutionComposition;
     mandate: { id: string; version: number };
     escalation: { trigger: string; detail: string } | null;
   } | null;
@@ -453,6 +455,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
       expires_at: artifact.expires_at,
       items_hash: artifact.items_hash,
       batch: batchBinding(artifact.batch),
+      ...(artifact.composition ? { composition: artifact.composition } : {}),
       mandate: artifact.mandate,
       escalation: artifact.escalation ? { trigger: artifact.escalation.trigger, detail: redact(artifact.escalation.detail) ?? "" } : null,
     };
@@ -575,6 +578,7 @@ function executionLines(execution: InspectExecution): Array<{ at: string; label:
   if (approval) {
     const wrapped = [`${approval.approval_id} · items_hash ${approval.items_hash}`, `under mandate ${approval.mandate.id} v${approval.mandate.version} · the artifact expires ${clock(approval.expires_at)}`];
     if (approval.batch) wrapped.push(`line ${approval.batch.index + 1} of ${approval.batch.count} of batch ${approval.batch.ref} · batch_hash ${approval.batch.batch_hash}`);
+    if (approval.composition) wrapped.push(`composed of ${approval.composition.line_count} line(s) of ${approval.composition.ref} · composition_hash ${approval.composition.composition_hash}`);
     if (approval.escalation) wrapped.push(`escalated by ${approval.escalation.trigger}: ${approval.escalation.detail}`);
     lines.push({ at: approval.approved_at, label: "approved", text: approverLabel(approval.approver), wrapped });
   }

package/templates/collections-agent/packages/agent-runtime/src/kit.ts

@@ -157,8 +157,19 @@ export interface AgentKit {
   usage(manifest: LoadedManifest): string;
   buildRail(ctx: RailContext): RailBuild;
   handlers(setup: Setup): Record<string, ToolHandler>;
-  /** The deterministic policy the core runs as its `policyExtension`. */
-  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails }): PolicyExtension | undefined;
+  /**
+   * Whether the channel dispatches an execution the moment it is approved.
+   * Default true. False when approving and issuing are two moments of the
+   * agent's own flow — a sale: the attendant (or the policy) confirms the
+   * order, and the charge goes out when the customer asks for it. The
+   * approved execution then waits, and the agent's own tool hands it to
+   * `engine.execute`, which runs the last gate like any other caller: a cart
+   * changed in between is caught there. An approved execution nobody issues
+   * expires on the approval TTL.
+   */
+  executeOnApproval?: boolean;
+  /** The deterministic policy the core runs as its `policyExtension`. `store` is the run's state.db, for a policy that judges durable state of the agent's own (a cart). */
+  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails; store: StateStore }): PolicyExtension | undefined;
   /** The console lines that describe one execution. */
   describeExecution(execution: Execution, setup: Setup): string[];
   /** The `--json` body of a one-shot. */
@@ -184,6 +195,18 @@ export interface AgentKit {
    * who was not told was not told.
    */
   outcomeTemplate?(execution: Execution): { template: string; variables: string[] } | undefined;
+  /**
+   * Work that FOLLOWS an outcome and is not part of it: a sale's service
+   * invoice once the order is `settled`. Runs after `announceOutcome`,
+   * wherever an outcome is announced (the terminal, the scenario runner,
+   * `poll`, `webhook`, the WhatsApp poll), and is awaited there. It can never
+   * move the execution it follows: a throw is reported on the operator's
+   * console and the outcome stands, because a paid order stays paid whatever
+   * happens after it.
+   */
+  followUp?(execution: Execution, setup: Setup, say: (line: string) => void): Promise<void>;
+  /** `resume` only: the follow-ups a crash left half-done. The same rule as the core's outbox: what provably never left may go; what may have left is reported, never sent again. */
+  resumeFollowUps?(setup: Setup, say: (line: string) => void): Promise<void>;
   /** Runs before a one-shot or an interactive session, when the mandate may have to be born first. Returns false to stop the run. */
   ensureMandate?(ctx: EnsureMandateContext): Promise<boolean>;
   /** `codespar-agent consent`. Absent means the agent has no consent step. */

package/templates/collections-agent/packages/agent-runtime/src/scenarios.ts

@@ -14,7 +14,7 @@ import type { ApprovalMode, Execution } from "@codespar/agent-core";
 import type { Agent } from "./agent.js";
 import type { RailKind } from "./kit.js";
 import { setup, type Setup } from "./setup.js";
-import { announceOutcome, handleExecution } from "./terminal.js";
+import { announceOutcome, followUp, handleExecution } from "./terminal.js";
 
 const TurnSchema = z
   .object({
@@ -204,7 +204,13 @@ export async function runScenario(agent: Agent, scenario: Scenario, options: Run
       for (const stuck of s.engine.list({ state: "executing" })) await s.engine.reconcile(stuck.id);
     }
     // Whatever closed after the conversation is told to the counterparty once, as the poll or the webhook would.
-    if (awaitsPayer) for (const e of s.engine.list()) if (e.run_id === s.runId) announceOutcome(e, s, tell);
+    if (awaitsPayer) {
+      for (const e of s.engine.list()) {
+        if (e.run_id !== s.runId) continue;
+        announceOutcome(e, s, tell);
+        await followUp(e, s, say);
+      }
+    }
 
     const events = s.store.listEvents({ run_id: s.runId });
     for (const e of events) {

package/templates/collections-agent/packages/agent-runtime/src/setup.ts

@@ -21,6 +21,7 @@ import {
   resolveFixedClock,
   type AgentRuntime,
   type ApprovalMode,
+  type ConversationScript,
   type Execution,
   type Guardrails,
   type LoadedManifest,
@@ -29,6 +30,7 @@ import {
   type PaymentRail,
   type StubChargeRailOptions,
   type StubRailOptions,
+  type ToolContext,
   type ToolHandler,
 } from "@codespar/agent-core";
 import { AnthropicRuntime } from "@codespar/agent-core/providers/anthropic";
@@ -95,7 +97,15 @@ export interface Setup {
   system: string;
   handlers: Record<string, ToolHandler>;
   tools: ReturnType<typeof loadToolsFile>;
-  makeLoop(runtime: AgentRuntime, onExecution: (execution: Execution) => Promise<Execution>): AgentLoop;
+  /**
+   * The conversation this run is bound to, when a channel binds one (WhatsApp):
+   * its contact and its subject. Set by the channel's start, read by a kit
+   * whose rules depend on who the person is — a sale is charged to the
+   * customer the conversation is with, and to nobody else.
+   */
+  conversation?: ConversationScript | undefined;
+  /** `onBatch` is for a channel that takes one gesture per batch; without it every line is decided in `onExecution`. */
+  makeLoop(runtime: AgentRuntime, onExecution: (execution: Execution) => Promise<Execution>, onBatch?: ToolContext["onBatch"]): AgentLoop;
   makeRuntime(): AgentRuntime;
   close(): void;
 }
@@ -166,7 +176,7 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
   // Section 11: mode, rail and mandate id. The VERSION rides with the id, so a reader knows which signing of the mandate authorised the run without opening the snapshot.
   bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, mandate_version: mandate.version, started_at: (now ?? (() => new Date()))().toISOString() });
 
-  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails });
+  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails, store });
   const engine = new ExecutionEngine({
     store,
     rail,
@@ -214,7 +224,7 @@ export function setup(agent: Agent, options: SetupOptions = {}): Setup {
     handlers: {},
     tools,
     makeRuntime,
-    makeLoop: (runtime, onExecution) => new AgentLoop({ runtime, tools, handlers: s.handlers, system, bundle, engine, onExecution, ...(now ? { clock: now } : {}) }),
+    makeLoop: (runtime, onExecution, onBatch) => new AgentLoop({ runtime, tools, handlers: s.handlers, system, bundle, engine, onExecution, ...(onBatch ? { onBatch } : {}), ...(now ? { clock: now } : {}) }),
     close: () => store.close(),
   };
   s.handlers = agent.kit.handlers(s);