@codespar/cli 0.17.0 → 0.18.0

package/templates/collections-agent/packages/agent-core/src/bundle.ts

@@ -5,6 +5,7 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { canonicalJson } from "./hash.js";
 import type { Mandate } from "./mandate.js";
 import type { RailReceipt } from "./rail.js";
 import type { ApprovalArtifact } from "./types.js";
@@ -97,11 +98,18 @@ export class ProofBundle {
     writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
   }
 
-  /** Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it. */
-  receipt(receipt: RailReceipt): string {
+  /**
+   * Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it.
+   *
+   * `approval_id` names the artifact in `approval.json` whose hashes the spend carried, so `npm run verify` holds the receipt's sealed
+   * approval link against THAT artifact, found by identity and never by looking for one whose hash happens to match. The copy stays
+   * masked: binding its body to the chain needs the unmasked read, which `verify --from-api` takes from the API and writes nowhere.
+   */
+  receipt(receipt: RailReceipt, context: { approval_id?: string | undefined } = {}): string {
     const relative = join("receipts", `${receipt.receipt_id}.json`);
     const { raw: _raw, ...safe } = receipt;
-    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
+    const copy = { ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null }, ...(context.approval_id ? { approval_id: context.approval_id } : {}) };
+    writeFileSync(join(this.dir, relative), JSON.stringify(copy, null, 2) + "\n");
     return relative;
   }
 
@@ -149,6 +157,30 @@ function readdirSorted(dir: string): string[] {
     .sort();
 }
 
+/**
+ * Where the bundle's masked copy of a receipt says something the API's read of the same receipt does not. The copy is not what the
+ * signature covers, so a copy edited after the fact still verifies at the signature level; this is what catches it once the read is
+ * in hand. The payee is compared masked, the only form the copy holds. An empty list means the copy is a faithful mask of the read.
+ */
+export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Record<string, unknown>): string[] {
+  const field = (o: unknown, k: string): unknown => (o && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined);
+  const readPayee = field(read["quote"], "payee");
+  const expected: Array<[string, unknown, unknown]> = [
+    ["receipt_id", copy["receipt_id"], read["receipt_id"]],
+    ["chain", copy["chain"], read["chain"]],
+    ["mandate.id", field(copy["mandate"], "id"), field(read["mandate"], "id")],
+    ["payment.amount_minor", field(copy["payment"], "amount_minor"), field(read["payment"], "amount_minor")],
+    ["payment.attempt_id", field(copy["payment"], "attempt_id"), field(read["payment"], "attempt_id")],
+    ["payment.money_moved", field(copy["payment"], "money_moved"), field(read["payment"], "money_moved")],
+    ["payment.at", field(copy["payment"], "at"), field(read["payment"], "at")],
+    ["payment.payee", field(copy["payment"], "payee"), typeof readPayee === "string" ? maskPayee(readPayee) : null],
+  ];
+  // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
+  if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
+  if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
+}
+
 /** `escola@exemplo.com.br` -> `es***@exemplo.com.br`; `+5511999998888` -> `+55***8888`; a UUID keeps its first and last 4. */
 export function maskPayee(payee: string): string {
   if (payee === "*") return payee;

package/templates/collections-agent/packages/agent-core/src/channels.ts

@@ -47,16 +47,22 @@ export const ConversationScriptSchema = z
      * different one, which is the secrecy rule as code rather than as prose.
      */
     subject: z.string().min(1).optional(),
-    /** The person's turns, in order. */
+    /**
+     * The person's turns, in order: something they TYPED (`text`), or a quick
+     * reply they TAPPED (`reply`, the id of a button a declared template
+     * offers). Exactly one of the two.
+     */
     turns: z
       .array(
         z
           .object({
-            text: z.string().min(1),
+            text: z.string().min(1).optional(),
+            reply: z.object({ id: z.string().min(1), title: z.string().min(1).optional() }).strict().optional(),
             /** Seconds after the previous inbound turn, on the run's clock. Keeps a scripted run deterministic. */
             after_seconds: z.number().int().nonnegative().default(0),
           })
-          .strict(),
+          .strict()
+          .refine((t) => (t.text === undefined) !== (t.reply === undefined), { message: "a turn is either text the person typed or a reply they tapped, exactly one" }),
       )
       .nonempty(),
   })
@@ -86,6 +92,26 @@ export const TEMPLATE_REGISTRY_FILE = "templates.json";
  * match is a `132000` from the Cloud API and there is no reason to learn that
  * in production.
  */
+/**
+ * A quick-reply button a template offers, and what tapping it MEANS.
+ *
+ * `intent` is the turn the model receives when the person taps it — written
+ * here, by whoever wrote the template, and never by the model. A tap carries
+ * an id and a title; the title is copy and can change, the id cannot, and the
+ * intent is what the id stands for. An id this registry does not declare is
+ * not a turn at all.
+ */
+export const QuickReplySchema = z
+  .object({
+    id: z.string().regex(/^[a-z0-9_]{1,64}$/, "a reply id is lower-case letters, digits and underscores"),
+    /** What the button says. Meta caps a quick reply at 20 characters. */
+    title: z.string().min(1).max(20),
+    intent: z.string().min(1),
+  })
+  .strict();
+
+export type QuickReply = z.infer<typeof QuickReplySchema>;
+
 export const WhatsAppTemplateSchema = z
   .object({
     /** Meta's own naming rule for a template. */
@@ -94,6 +120,15 @@ export const WhatsAppTemplateSchema = z
     language: z.string().regex(/^[a-z]{2}(_[A-Z]{2})?$/, 'expected a language code, e.g. "pt_BR"'),
     description: z.string().min(1),
     body: z.string().min(1),
+    /** Quick replies the template carries (Meta allows up to three on a template). */
+    buttons: z.array(QuickReplySchema).max(3).optional(),
+    /**
+     * The template a poll sends when the outcome it must tell has no copy of
+     * its own: it says there is news and asks the person to answer, and states
+     * nothing about the outcome — so it can never be the wrong news. Exactly
+     * one per registry, taking no variables (`npm run check`).
+     */
+    fallback: z.boolean().optional(),
   })
   .strict();
 
@@ -120,12 +155,23 @@ export const TemplateRegistrySchema = z
   .strict()
   .superRefine((registry, ctx) => {
     const seen = new Set<string>();
+    const replyIds = new Set<string>();
     for (const [i, template] of registry.templates.entries()) {
       if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
       seen.add(template.name);
+      // A tap is resolved by its id alone, so one id means one intent across the whole registry.
+      for (const [j, button] of (template.buttons ?? []).entries()) {
+        if (replyIds.has(button.id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice` });
+        replyIds.add(button.id);
+      }
     }
   });
 
+/** Every quick reply the registry declares, by id: the only taps that can become a turn. */
+export function declaredReplies(templates: readonly WhatsAppTemplate[]): Map<string, QuickReply> {
+  return new Map(templates.flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
+}
+
 export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;
 
 export function parseTemplateRegistry(text: string): TemplateRegistry {

package/templates/collections-agent/packages/agent-core/src/check.ts

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, templateArity } from "./channels.js";
+import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, declaredReplies, templateArity, type TemplateRegistry } from "./channels.js";
 import { GuardrailsSchema } from "./guardrails.js";
 import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js";
 import { MandateSchema } from "./mandate.js";
@@ -121,12 +121,35 @@ export function checkAgent(agentDir: string): CheckReport {
   if (!manifest.channels.includes("whatsapp") && scripts.length > 0) {
     error("channels_undeclared", `channels/whatsapp/ ships ${scripts.length} conversation(s) but agent.yaml does not declare the whatsapp channel`);
   }
+  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
+  let registry: TemplateRegistry | undefined;
+  if (existsSync(registryPath)) {
+    const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
+    if (parsed.success) registry = parsed.data;
+  }
+  const replies = declaredReplies(registry?.templates ?? []);
   for (const file of scripts) {
     const parsed = ConversationScriptSchema.safeParse(JSON.parse(readFileSync(join(whatsappDir, file), "utf8")));
     if (!parsed.success) error("channels_script_invalid", `channels/whatsapp/${file}: ${parsed.error.message}`);
     else if (parsed.data.name !== file.replace(/\.json$/, "")) error("channels_script_invalid", `channels/whatsapp/${file} declares name ${parsed.data.name}`);
+    else {
+      // A scripted tap must be one a declared template offers: the channel drops any other, so the script would test nothing.
+      for (const turn of parsed.data.turns) {
+        if (turn.reply && !replies.has(turn.reply.id)) error("channels_script_invalid", `channels/whatsapp/${file} taps ${turn.reply.id}, which no template in ${TEMPLATE_REGISTRY_FILE} offers`);
+      }
+    }
+  }
+  // An agent on WhatsApp closes outcomes days later, outside the window, where
+  // only a template goes. One it has no copy for still has to reach the
+  // person, so the registry declares a fallback that states no outcome.
+  if (manifest.channels.includes("whatsapp")) {
+    if (!existsSync(registryPath)) error("channels_templates_missing", `agent.yaml declares the whatsapp channel and channels/whatsapp/${TEMPLATE_REGISTRY_FILE} does not exist`);
+    else if (registry) {
+      const fallbacks = registry.templates.filter((t) => t.fallback);
+      if (fallbacks.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${fallbacks.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
+      else if (templateArity(fallbacks[0]!.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallbacks[0]!.name} takes variables; it is sent when nothing specific can be said, so it takes none`);
+    }
   }
-  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
   if (existsSync(registryPath)) {
     const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
     if (!parsed.success) error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${parsed.error.message}`);