@codespar/cli 0.18.1 → 0.20.0

package/templates/hello-agent/packages/agent-core/src/engine.ts

@@ -13,7 +13,7 @@
  */
 import { checkApprovalArtifact, createApprovalArtifact, type ApprovalSigner } from "./approval.js";
 import { maskPayee, type ProofBundle } from "./bundle.js";
-import { evaluateEscalation, type Escalation } from "./escalate.js";
+import { evaluateEscalation, localDate, type Escalation } from "./escalate.js";
 import { CHARGE_CANCELLED, CHARGE_EXPIRED, CHARGE_PAID, PAYMENT_FAILED, PAYMENT_SUCCEEDED, type PublishedEvent } from "./events.js";
 import type { Guardrails } from "./guardrails.js";
 import { batchAttemptId, itemsHash, sha256Hex } from "./hash.js";
@@ -21,10 +21,10 @@ import { newId } from "./ids.js";
 import { mandateExpired, payeeAllowed, resolveBeneficiary, windowCap, windowStart, type Mandate } from "./mandate.js";
 import type { Manifest } from "./manifest.js";
 import { checkQuote, quoteFromApproval } from "./quote.js";
-import { spendApprovalOf, type PaymentRail, type RailOutcome, type RailPayment, type SealedSpendApproval, type SpendApproval } from "./rail.js";
+import { sameWireActor, spendApprovalOf, wireActorOf, type PaymentRail, type RailOutcome, type RailPayment, type SealedSpendApproval, type SpendApproval } from "./rail.js";
 import { sameApprovalHash } from "./receipt-chain.js";
 import type { MandateStatusReport, MandateStatusSource } from "./revocation.js";
-import { isTerminal, transition, type Execution, type ExecutionState } from "./state-machine.js";
+import { isTerminal, transition, type Execution, type ExecutionState, type RailAnswer } from "./state-machine.js";
 import type { StateStore } from "./state/store.js";
 import type { Actor, ApprovalArtifact, ApprovalMode, ExecutionBatch, ExecutionComposition, ExecutionItem, ExecutionReason, ItemOutcome } from "./types.js";
 
@@ -131,6 +131,16 @@ export class ExecutionEngine {
     return this.deps.mandate;
   }
 
+  /**
+   * The day it is for the person, in the guardrails' timezone, at this
+   * engine's clock (so `--now` pins it too). A tool that shows a due date
+   * shows this next to it: the model has no calendar of its own, and without
+   * it a bill due next week reads as one that already fell due.
+   */
+  today(): string {
+    return localDate(this.clock(), this.deps.guardrails.timezone);
+  }
+
   // ---- the model's only entry point -------------------------------------
 
   async draft(proposal: Proposal): Promise<DraftResult> {
@@ -420,6 +430,7 @@ export class ExecutionEngine {
   private async dispatch(execution: Execution<"executing">, payments: RailPayment[]): Promise<Execution> {
     const outcomes: ItemOutcome[] = [...execution.outcomes];
     const unknown: string[] = [];
+    const unknownAnswers: RailAnswer[] = [];
     const sealMismatches: string[] = [];
     this.deps.store.updateOutbox(execution.idempotency_key, "sent", undefined, this.clock().toISOString());
 
@@ -453,10 +464,11 @@ export class ExecutionEngine {
         // sent: an unknown answer about THIS payee says nothing about the next
         // one, and the execution stays open until reconciliation settles it.
         unknown.push(`attempt ${payment.attempt_id}: ${outcome.code} — outcome unknown, kept for reconciliation`);
+        unknownAnswers.push({ attempt_id: payment.attempt_id, code: outcome.code, message: outcome.message });
         continue;
       }
       if (outcome.status === "failed") {
-        outcomes.push({ index, attempt_id: payment.attempt_id, status: "failed", code: outcome.code, error: `${outcome.code}: ${outcome.message}`, ...(outcome.held ? { held: outcome.held } : {}) });
+        outcomes.push({ index, attempt_id: payment.attempt_id, status: "failed", code: outcome.code, message: outcome.message, error: `${outcome.code}: ${outcome.message}`, ...(outcome.held ? { held: outcome.held } : {}) });
         continue;
       }
       if (outcome.status === "accepted") {
@@ -469,7 +481,12 @@ export class ExecutionEngine {
       const mismatch = await this.ingestSettlement(execution, index, payment, outcome.receipt_id, PAYMENT_SUCCEEDED);
       if (mismatch) sealMismatches.push(mismatch);
     }
-    const closed = this.close({ ...execution, outcomes, ...(Object.keys(generations).length > 0 ? { attempt_generations: generations } : {}) }, payments.length, unknown.join("; ") || undefined);
+    const answers = [...(execution.uncertain_answers ?? []).filter((a) => !unknownAnswers.some((u) => u.attempt_id === a.attempt_id)), ...unknownAnswers];
+    const closed = this.close(
+      { ...execution, outcomes, ...(Object.keys(generations).length > 0 ? { attempt_generations: generations } : {}), ...(answers.length > 0 ? { uncertain_answers: answers } : {}) },
+      payments.length,
+      unknown.join("; ") || undefined,
+    );
     if (sealMismatches.length > 0) throw new ReceiptSealMismatchError(execution.id, sealMismatches);
     return closed;
   }
@@ -494,13 +511,12 @@ export class ExecutionEngine {
     if (execution.outcomes.length < attempts) {
       return this.leaveUnresolved(updated, unknownDetail ?? `${execution.outcomes.length} of ${attempts} attempt(s) have an outcome`);
     }
-    // An ambiguous receivable outranks any other failure: it is the one outcome that must be reconciled rather than issued again.
-    const failed = execution.outcomes.find((o) => o.status === "failed" && o.code === "charge_reference_ambiguous") ?? execution.outcomes.find((o) => o.status === "failed");
+    const failed = decisiveFailure(execution.outcomes);
     if (failed) {
       this.deps.store.updateOutbox(execution.idempotency_key, "failed", execution.outcomes, at);
       // `org_paused` is the API refusing the spend itself: the kill switch was pressed after the gate read the status. Nothing moved.
       const reason: ExecutionReason =
-        failed.code === "charge_expired" || failed.code === "charge_cancelled" || failed.code === "org_paused" || failed.code === "charge_reference_ambiguous" ? failed.code : "rail_failed";
+        failed.code === "charge_expired" || failed.code === "charge_cancelled" || failed.code === "charge_issuer_error" || failed.code === "org_paused" || failed.code === "charge_reference_ambiguous" ? failed.code : "rail_failed";
       return this.persist(transition(updated, "failed", { at, actor: this.agentActor, reason, detail: failed.error ?? "rail refused" }));
     }
     if (execution.outcomes.filter((o) => o.status === "settled").length === attempts) {
@@ -584,6 +600,11 @@ export class ExecutionEngine {
       this.record("receipt.seal_mismatch", executionId, { receipt_id: receiptId, attempt_id: payment.attempt_id, sealed_approval: receipt.approval, sent_approval: payment.approval });
       mismatches.push(`receipt ${receiptId} seals approval ${receipt.approval ? receipt.approval.items_hash : "none"}; attempt ${payment.attempt_id} sent ${payment.approval.items_hash}`);
     }
+    // §2: the actor the spend declared, as the API recorded it. A different one, or none, is an event and not a seal mismatch:
+    // the money and its link to the approval are what the receipt proves, and who triggered it is what it RECORDS.
+    if (receipt.sealed_actor !== undefined && !sameWireActor(receipt.sealed_actor, wireActorOf(payment.actor))) {
+      this.record("receipt.actor_mismatch", executionId, { receipt_id: receiptId, attempt_id: payment.attempt_id, sealed_actor: receipt.sealed_actor, sent_actor: wireActorOf(payment.actor) });
+    }
     return mismatches.length > 0 ? mismatches.join("; ") : undefined;
   }
 
@@ -671,7 +692,12 @@ export class ExecutionEngine {
         replace({ index, attempt_id: payment.attempt_id, status: "failed", code: seen.code, error: `${seen.code}: ${seen.message}`, ...(seen.held ? { held: seen.held } : {}) });
         continue;
       }
-      replace({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: seen.transaction_id, ...(seen.receipt_id ? { receipt_id: seen.receipt_id } : {}), ...(seen.replayed ? { replayed: true as const } : {}) });
+      // No `replayed` here, whatever the rail said. A lookup IS a second
+      // presentation of an attempt this execution already sent, so on the API
+      // every settled lookup answers `idempotent_replay`, including the one
+      // whose payment was this execution's own. The mark would say "someone
+      // else paid" about a payment nobody can attribute from here.
+      replace({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: seen.transaction_id, ...(seen.receipt_id ? { receipt_id: seen.receipt_id } : {}) });
       const mismatch = await this.ingestSettlement(execution, index, payment, seen.receipt_id, prior ? CHARGE_PAID : PAYMENT_SUCCEEDED);
       if (mismatch) sealMismatches.push(mismatch);
     }
@@ -1050,6 +1076,61 @@ function railAnswer(outcome: RailOutcome): Record<string, unknown> {
   }
 }
 
+/** The failed outcome an execution closes on. An ambiguous receivable outranks any other failure: it is the one outcome that must be reconciled rather than issued again. */
+function decisiveFailure(outcomes: readonly ItemOutcome[]): ItemOutcome | undefined {
+  return outcomes.find((o) => o.status === "failed" && o.code === "charge_reference_ambiguous") ?? outcomes.find((o) => o.status === "failed");
+}
+
+/** What the rail answered, verbatim: the code and message the API sent, not only `rail_failed` or `rail_uncertain` (#50). */
+export interface RailError {
+  /** `failed`: the answer the execution closed on. `uncertain`: an answer that left an attempt's outcome unknown. */
+  outcome: "failed" | "uncertain";
+  attempt_id: string;
+  code: string;
+  message: string | null;
+}
+
+/**
+ * The rail's own answer behind a failure, for `--json` and the terminal. The
+ * reason (`rail_failed`) says WHICH gate closed the execution; this says what
+ * the API said, so a first failure explains itself — `insufficient_funds` on
+ * an unfunded test wallet reads as that, not as a generic refusal. `null` when
+ * nothing failed and nothing was left unknown. A 5xx is not a failure — the
+ * money may have moved — so `provider_error` comes back as `uncertain`, with
+ * the API's words, while the execution stays open for reconciliation. An
+ * outcome stored before the message was kept carries only `code: message` in
+ * `error`, and that is what is returned.
+ */
+export function railErrorOf(execution: Pick<Execution, "outcomes" | "uncertain_answers">): RailError | null {
+  const failed = decisiveFailure(execution.outcomes);
+  if (failed?.code !== undefined) return { outcome: "failed", attempt_id: failed.attempt_id, code: failed.code, message: failed.message ?? failed.error ?? null };
+  const pending = (execution.uncertain_answers ?? []).find((a) => !execution.outcomes.some((o) => o.attempt_id === a.attempt_id));
+  return pending ? { outcome: "uncertain", attempt_id: pending.attempt_id, code: pending.code, message: pending.message } : null;
+}
+
+/**
+ * Settled, and every settled attempt was answered from the rail's record of
+ * an earlier presentation this execution never made: the money moved, and
+ * this execution did not move it. `dispatch` is the only writer of the mark,
+ * so a report can say "paid by this run" of everything else it calls settled.
+ */
+export function isReplayedSettlement(execution: Pick<Execution, "state" | "outcomes">): boolean {
+  const settled = execution.outcomes.filter((o) => o.status === "settled");
+  return execution.state === "settled" && settled.length > 0 && settled.every((o) => o.replayed === true);
+}
+
+/**
+ * A reason, or a rail code, that closes a payment without anything having
+ * failed: nobody paid the charge in time, the charge was withdrawn, or the
+ * organization pressed the kill switch. It reads with `denied` and `expired`,
+ * not with a rail failure, in every count and report.
+ */
+const DECLINED_REASONS: readonly string[] = ["charge_expired", "charge_cancelled", "org_paused"];
+
+export function isDeclinedReason(reason: string | null | undefined): boolean {
+  return typeof reason === "string" && DECLINED_REASONS.includes(reason);
+}
+
 /** The approval link a receipt sealed is the one a spend sent: the same hashes, in either spelling of the `sha256:` prefix. */
 function sealsApproval(sealed: SealedSpendApproval | null, sent: SpendApproval): boolean {
   return sealed !== null && sameApprovalHash(sealed.items_hash, sent.items_hash) && sameApprovalHash(sealed.batch_hash, sent.batch_hash ?? null);

package/templates/hello-agent/packages/agent-core/src/escalate.ts

@@ -71,6 +71,16 @@ export function localClock(now: Date, timezone: string): string {
   return `${hour}:${minute}`;
 }
 
+/** The calendar day `now` falls on in `timezone`, as `YYYY-MM-DD`. */
+export function localDate(now: Date, timezone: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" }).format(now);
+}
+
+/** Whole days from `today` to `date` (both `YYYY-MM-DD`): 0 is today, negative is already past. */
+export function daysUntil(today: string, date: string): number {
+  return Math.round((Date.parse(`${date}T00:00:00Z`) - Date.parse(`${today}T00:00:00Z`)) / 86_400_000);
+}
+
 /** `"22:00-07:00"` is the CLOSED window: inside it, the trigger fires. Crosses midnight when start > end. */
 export function isOutsideHours(window: string, now: Date, timezone: string): boolean {
   const [start, end] = window.split("-") as [string, string];

package/templates/hello-agent/packages/agent-core/src/index.ts

@@ -19,6 +19,9 @@ export * from "./tools.js";
 export * from "./bundle.js";
 export * from "./engine.js";
 export * from "./agent.js";
+export * from "./language.js";
+export * from "./locale.js";
+export * from "./strings.js";
 export * from "./check.js";
 export * from "./events.js";
 export * from "./state/store.js";

package/templates/hello-agent/packages/agent-core/src/language.ts

@@ -0,0 +1,52 @@
+/**
+ * The language a person wrote in, of the two the kits speak, and the sentence
+ * that tells the model to answer in it.
+ *
+ * A rule in the system prompt ("answer in the language of the person's latest
+ * message") was not enough (docs/OPEN_QUESTIONS.md §64): on the Messages API a
+ * tool result is a user-role message, so on any turn that used a tool the
+ * latest message the model read was Portuguese data, and five English requests
+ * out of five were answered in Portuguese. The loop therefore reads the
+ * language from what the person TYPED, deterministically, and states it for
+ * the whole turn.
+ *
+ * Function words, not a classifier: payee names, bill descriptions and
+ * amounts are the same in both languages and count for neither.
+ */
+
+export type ReplyLanguage = "pt-BR" | "en";
+
+const PT = new Set(
+  "de da das do dos para pra pro que com um uma os é está esta estou já foi o e em na nas nos no ao aos meu minha minhas meus você voce vocês não nao sim oi olá ola quanto quanta quais qual quero queria pague paga pagar pagamento pagamentos manda mande mandar roda rode rodar gastei gastou mês mes conta contas folha essa esse isso esta este semana tudo vence venceu obrigado obrigada por favor hoje agora fechado até como onde quando quem aqui sou eu pode posso preciso".split(" "),
+);
+const EN = new Set(
+  "the to and of for pay paid please my i i'm i'd i'll you your how much many what which when who is are was were have has had spent this that month week bill bills run payroll school cleaner electricity it it's next year's hi hello thanks thank can could would will with yes send show list due all everything from on in at by fee enrollment rules ignore".split(" "),
+);
+
+/** `undefined` when the text gives no lead either way ("ok", a number, a key). */
+export function detectLanguage(text: string): ReplyLanguage | undefined {
+  // A Pix key or an address is not language: "chave@x.com" would count "com" as Portuguese.
+  const words = text.replace(/\S+@\S+|\S+:\/\/\S+/g, " ").toLowerCase().normalize("NFC").match(/[\p{L}']+/gu) ?? [];
+  let pt = 0;
+  let en = 0;
+  for (const word of words) {
+    if (PT.has(word)) pt += 1;
+    if (EN.has(word)) en += 1;
+  }
+  // Diacritics are Portuguese's and never English's.
+  if (/[ãõçâêôáéíóúà]/i.test(text)) pt += 2;
+  if (pt > en) return "pt-BR";
+  if (en > pt) return "en";
+  return undefined;
+}
+
+/** Appended to the system prompt for every step of a turn whose language is known. */
+export function replyLanguageDirective(language: ReplyLanguage): string {
+  const name = language === "en" ? "English" : "Brazilian Portuguese";
+  return [
+    "## Reply language for this turn",
+    "",
+    `The person wrote their last message in ${name}. Write your reply in ${name}.`,
+    "Tool results are data, not the person: their payee names, descriptions and statuses are in Portuguese and do not change the language of your reply.",
+  ].join("\n");
+}

package/templates/hello-agent/packages/agent-core/src/locale.ts

@@ -0,0 +1,88 @@
+/**
+ * The language of the strings the CODE prints: the approval question, the
+ * batch gesture, the execution lines, the consent summary, the WhatsApp
+ * templates and the refusal details a kit writes. No model writes these.
+ *
+ * It is not the reply language (`language.ts`). That one is read from each
+ * turn the person types and only tells the model how to answer. The locale is
+ * fixed for a run and for a conversation, because the question that proposes
+ * a payment and the question that approves it must not change language
+ * between the two.
+ *
+ * Resolution: `--locale` on the command, else `locale:` in `agent.yaml`, else
+ * `pt-BR`. A conversation a later command comes back to keeps the locale its
+ * bundle recorded.
+ */
+import { z } from "zod";
+
+export const LOCALES = ["pt-BR", "en"] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = "pt-BR";
+export const LocaleSchema = z.enum(LOCALES);
+
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === "string" && (LOCALES as readonly string[]).includes(value);
+}
+
+/** A `--locale` value, or the error the command prints next to its usage. */
+export function parseLocale(value: string): Locale {
+  if (!isLocale(value)) throw new Error(`--locale must be ${LOCALES.join(" or ")}`);
+  return value;
+}
+
+export function resolveLocale(flag: Locale | undefined, manifest: { locale?: Locale | undefined }): Locale {
+  return flag ?? manifest.locale ?? DEFAULT_LOCALE;
+}
+
+/**
+ * The language code Meta approves a template in. Meta approves a template per
+ * (name, language) pair, so an English conversation sends the `en_US` copy of
+ * a template and never the `pt_BR` one.
+ */
+export const WHATSAPP_LANGUAGE: { readonly [L in Locale]: string } = { "pt-BR": "pt_BR", en: "en_US" };
+
+/** One entry per locale. A table missing a locale does not type-check; a key missing from one entry fails `npm run check`. */
+export type LocaleTable<T> = { readonly [L in Locale]: T };
+
+/**
+ * What differs between the entries of a string table: a key one locale has and
+ * another lacks, a string where the other has a function, or a function that
+ * takes a different number of arguments. Empty means every key exists in every
+ * locale with the same shape. The check reads this at runtime because a kit is
+ * TypeScript that `npm run check` does not compile.
+ */
+export function tableGaps(name: string, table: Partial<Record<Locale, object>>): string[] {
+  const gaps: string[] = [];
+  const entry = (l: Locale) => table[l] as Record<string, unknown> | undefined;
+  for (const locale of LOCALES) if (!entry(locale)) gaps.push(`${name} has no ${locale} entry`);
+  const keys = new Set(LOCALES.flatMap((l) => Object.keys(entry(l) ?? {})));
+  for (const key of [...keys].sort()) {
+    const shapes = LOCALES.map((l) => {
+      const value = entry(l)?.[key];
+      if (value === undefined) return "missing";
+      if (typeof value === "function") return `function/${value.length}`;
+      return typeof value === "string" && value.length > 0 ? "string" : `empty ${typeof value}`;
+    });
+    for (const [i, shape] of shapes.entries()) {
+      if (shape === "missing" || shape.startsWith("empty")) gaps.push(`${name}.${key} is ${shape} in ${LOCALES[i]}`);
+    }
+    if (new Set(shapes.filter((s) => s !== "missing")).size > 1) gaps.push(`${name}.${key} differs in shape across locales: ${LOCALES.map((l, i) => `${l} ${shapes[i]}`).join(", ")}`);
+  }
+  return gaps;
+}
+
+/** `185000` -> `R$ 1.850,00` in pt-BR, `R$1,850.00` in English: the two forms the prompts give the model since #62. */
+export function formatBRL(minor: number, locale: Locale): string {
+  const sign = minor < 0 ? "-" : "";
+  const abs = Math.abs(minor);
+  const cents = String(abs % 100).padStart(2, "0");
+  if (locale === "en") return `${sign}R$${Math.floor(abs / 100).toLocaleString("en-US")}.${cents}`;
+  return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${cents}`;
+}
+
+/** `2026-09-30` -> `30/09/2026` in pt-BR; English keeps the ISO date, which reads the same on either side of the Atlantic. */
+export function formatDay(iso: string, locale: Locale): string {
+  if (locale === "en") return iso;
+  const [y, m, d] = iso.split("-");
+  return `${d}/${m}/${y}`;
+}

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

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
+import { LocaleSchema } from "./locale.js";
 
 const PINNED_PACKAGE = /^@codespar\/(mcp|cli)@\d+\.\d+\.\d+$/;
 const HOURS_WINDOW = /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/;
@@ -34,12 +35,14 @@ export const ManifestSchema = z
     default_approval: z.enum(["human", "mandate"]),
     escalate_above: EscalateAboveSchema.optional(),
     mcp: z.string().regex(PINNED_PACKAGE, "mcp must pin an exact version, e.g. @codespar/mcp@0.5.8"),
-    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.14.0"),
+    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.18.1"),
     tools: z.string(),
     guardrails: z.string(),
     mandate_schema: z.string(),
     events: z.array(z.string().regex(/^commerce\.[a-z_.]+$/)),
     channels: z.array(z.enum(["terminal", "whatsapp"])).nonempty(),
+    /** The language of the strings the code prints (not of the model's replies). Optional: absent is `pt-BR`, which is what every agent printed before the field existed. */
+    locale: LocaleSchema.optional(),
     maturity: z.record(z.string(), MaturitySchema),
     scenarios: z.string(),
     evals: z.string(),

package/templates/hello-agent/packages/agent-core/src/rail.ts

@@ -75,7 +75,7 @@ export interface RailPayment {
    * its shape and never its content. A charge rail ignores it.
    */
   approval?: SpendApproval;
-  /** Section 4.5: carried on every call. The API has no wire field for it yet; see OPEN_QUESTIONS. */
+  /** Section 4.5: carried on every call, on the wire as `PaymentActor` (`wireActorOf`) since @codespar/sdk 0.16.10; see OPEN_QUESTIONS §2. */
   actor: Actor;
 }
 
@@ -167,9 +167,37 @@ export interface RailReceipt {
   receipt_sig_kid: string | null;
   /** Section 4.5: the kit stamps the actor onto the local copy of every receipt. */
   actor: Actor;
+  /**
+   * The actor the API RECORDED for the spend and read back (`PaymentActor`,
+   * @codespar/sdk 0.16.10): `null` when it recorded none — an API that did not
+   * take the field, or a spend that sent none. Absent when the rail cannot
+   * say: a charge, which records no actor.
+   */
+  sealed_actor?: WireActor | null;
   raw: unknown;
 }
 
+/**
+ * Who triggered a spend, in the API's own shape (`PaymentActor`,
+ * @codespar/sdk 0.16.10): the agent by its identifier and the consumer it acts
+ * for, or the person by id and the channel they acted from. The kit's `Actor`
+ * names the agent under `agent`; the wire names it under `id`, and that is the
+ * only difference.
+ */
+export type WireActor = { type: "agent"; id: string; on_behalf_of: string } | { type: "human"; id: string; channel?: string };
+
+export function wireActorOf(actor: Actor): WireActor {
+  return actor.type === "agent" ? { type: "agent", id: actor.agent, on_behalf_of: actor.on_behalf_of } : { type: "human", id: actor.id, channel: actor.channel };
+}
+
+/** The same actor, field for field. A human's channel counts: the same person on WhatsApp and on a dashboard are two events. */
+export function sameWireActor(a: WireActor | null, b: WireActor | null): boolean {
+  if (a === null || b === null) return a === b;
+  if (a.type === "agent" && b.type === "agent") return a.id === b.id && a.on_behalf_of === b.on_behalf_of;
+  if (a.type === "human" && b.type === "human") return a.id === b.id && (a.channel ?? null) === (b.channel ?? null);
+  return false;
+}
+
 /** What a reconcile learns: a recorded outcome, "still running", or nothing. Never a new payment. */
 export type RailLookup = RailOutcome | { status: "in_flight" } | undefined;
 

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

@@ -53,7 +53,7 @@
  */
 import { createPublicKey, verify as verifyDetached } from "node:crypto";
 import { itemsHash } from "./hash.js";
-import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type SealedApproval } from "./receipt-chain.js";
+import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type ChainRecipe, type SealedApproval } from "./receipt-chain.js";
 import type { ExecutionItem } from "./types.js";
 
 /** The domain tag. A receipt names the version it was sealed under through
@@ -123,6 +123,16 @@ export interface ChainCheck {
   reason: string;
 }
 
+/**
+ * Whether the sealed payment was a sandbox one and whether money moved, read off a body that recomputed to the signed chain. A field
+ * is `null` when the recipe's payment link for that version does not seal it: a value the chain does not cover is not reported as one
+ * it does. Only these two, so a verdict never carries the rest of the read (the tenant's read also carries `mandate.sig`).
+ */
+export interface SealedPayment {
+  sandbox: boolean | null;
+  money_moved: boolean | null;
+}
+
 /** What the sealed approval link was held against. Present on a v4 chain that recomputed. */
 export interface ApprovalLinkCheck {
   /** `matched`: the artifact's hashes are the sealed ones. `mismatch`: they are not. `not_compared`: no artifact was given. */
@@ -161,6 +171,8 @@ export interface ReceiptVerification {
   /** The body check, when one was attempted: only `verifyReceiptRead` attempts it, and only on a signature that verified. */
   chain_check?: ChainCheck;
   approval_check?: ApprovalLinkCheck;
+  /** Present exactly when the body recomputed to the signed chain. */
+  sealed_payment?: SealedPayment;
 }
 
 /** One published key, RFC 8037 shape, as the JWKS serves it. */
@@ -531,12 +543,13 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     };
   }
   const chainCheck: ChainCheck = { status: "recomputed", version: recomputed.version, recomputed: recomputed.chain, reason: "body_recomputes" };
+  const sealedPayment = sealedPaymentOf(read, recipe.recipe, recomputed.version);
   const bound = `the body recomputes to the signed chain under the published recipe (v${recomputed.version})`;
 
   const sealed = readSealedApproval(read);
   if (!sealed) {
     // Unreachable through the published recipe (v4 seals the link, and a read without it fails the recomputation above), kept so a future version is not misread.
-    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck };
+    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck, sealed_payment: sealedPayment };
   }
   const approval = options.approval;
   if (!approval) {
@@ -546,6 +559,7 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
       message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}. It seals the approval ${sealed.items_hash}${sealed.batch_hash ? ` (batch ${sealed.batch_hash})` : ""}; no approval artifact was given to hold it against`,
       chain_check: chainCheck,
       approval_check: { status: "not_compared", sealed, artifact: null, reason: "no_artifact" },
+      sealed_payment: sealedPayment,
     };
   }
 
@@ -557,6 +571,7 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}, and ${why}: this payment was not sealed against the list artifact ${approval.approval_id} approved`,
     chain_check: chainCheck,
     approval_check: { status: "mismatch", sealed, artifact, reason },
+    sealed_payment: sealedPayment,
   });
   if (approval.items && itemsHash(approval.items) !== approval.items_hash) {
     return mismatch("artifact_items_hash_inconsistent", `the artifact's items_hash ${approval.items_hash} is not the hash of the items it lists (${itemsHash(approval.items)})`);
@@ -573,5 +588,18 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     message: `receipt ${signature.receipt_id} was sealed by CodeSpar, ${bound}, and it was paid against the list artifact ${approval.approval_id} approved (${sealed.items_hash}${sealed.batch_hash ? `, batch ${sealed.batch_hash}` : ""}). WHO approved it is in the artifact, under a local key, and nowhere in the seal`,
     chain_check: chainCheck,
     approval_check: { status: "matched", sealed, artifact, reason: "approval_matches" },
+    sealed_payment: sealedPayment,
+  };
+}
+
+function sealedPaymentOf(read: Record<string, unknown>, recipe: ChainRecipe, version: number): SealedPayment {
+  const spec = recipe.links.find((l) => l.from === "payment");
+  const fields = spec?.fields ?? spec?.fields_by_version?.[String(version)] ?? [];
+  const payment = read["payment"];
+  const pick = (name: string): boolean | null => {
+    if (!fields.includes(name) && !fields.includes(`${name}${recipe.optional_marker}`)) return null;
+    const value = isRecord(payment) ? payment[name] : undefined;
+    return typeof value === "boolean" ? value : null;
   };
+  return { sandbox: pick("sandbox"), money_moved: pick("money_moved") };
 }

package/templates/hello-agent/packages/agent-core/src/secrets.ts

@@ -1,26 +1,71 @@
 /**
  * Sandbox by construction: a key outside the `csk_test_` pattern fails
  * before any network call. Nothing in this repository ever holds a live key.
+ *
+ * Three different mistakes land here and each has its own fix, so each has
+ * its own message (#50): no key at all (the `.env` was never copied, or sits
+ * where the agent does not read it), the `.env.example` placeholder left in
+ * place, and a key that is not a test key. Telling a newcomer who has no key
+ * that their key is LIVE sends them looking for the wrong thing.
  */
 export const TEST_KEY_PREFIX = "csk_test_";
 
+/** The value `.env.example` ships with. It has the test prefix and is nobody's key. */
+export const CODESPAR_KEY_PLACEHOLDER = "csk_test_your_key_here";
+
+/** Why a `CODESPAR_API_KEY` cannot be used: absent or empty, the placeholder, or not a test key. */
+export type TestKeyProblem = "missing" | "placeholder" | "not_test";
+
+export function testKeyProblem(key: string | undefined): TestKeyProblem | undefined {
+  const value = key?.trim() ?? "";
+  if (value === "") return "missing";
+  if (value === CODESPAR_KEY_PLACEHOLDER) return "placeholder";
+  if (!value.startsWith(TEST_KEY_PREFIX) || value.length <= TEST_KEY_PREFIX.length) return "not_test";
+  return undefined;
+}
+
+/**
+ * `envFile` is the `.env` the agent actually reads, as the runner resolves it
+ * (`agents/<agent>/.env`, relative to where the command ran). The core does
+ * not know which agent it runs for, so without it the message names the
+ * pattern instead of the path.
+ */
+export function testKeyMessage(problem: TestKeyProblem, envFile?: string): string {
+  const file = envFile ?? "agents/<agent>/.env";
+  switch (problem) {
+    case "missing":
+      return (
+        `CODESPAR_API_KEY is not set: copy ${file}.example to ${file} and paste a ${TEST_KEY_PREFIX} key from https://codespar.dev/auth/signup. ` +
+        `${file} is the file this agent reads; a .env anywhere else, the repository root included, is not read.`
+      );
+    case "placeholder":
+      return `CODESPAR_API_KEY is still the placeholder from .env.example (${CODESPAR_KEY_PLACEHOLDER}): replace it in ${file} with your own ${TEST_KEY_PREFIX} key from https://codespar.dev/auth/signup.`;
+    case "not_test":
+      return (
+        `CODESPAR_API_KEY must be a test key (prefix "${TEST_KEY_PREFIX}"). ` +
+        `This kit runs in the sandbox only; a live key is refused before any call is made. It is read from the environment, or from ${file}.`
+      );
+  }
+}
+
 export class NotATestKeyError extends Error {
-  constructor() {
-    super(
-      `CODESPAR_API_KEY must be a test key (prefix "${TEST_KEY_PREFIX}"). ` +
-        "This kit runs in the sandbox only; a live key is refused before any call is made.",
-    );
+  constructor(
+    readonly problem: TestKeyProblem = "not_test",
+    readonly envFile?: string,
+  ) {
+    super(testKeyMessage(problem, envFile));
     this.name = "NotATestKeyError";
   }
 }
 
 export function isTestKey(key: string | undefined): key is string {
-  return typeof key === "string" && key.startsWith(TEST_KEY_PREFIX) && key.length > TEST_KEY_PREFIX.length;
+  return testKeyProblem(key) === undefined;
 }
 
 export function assertTestKey(key: string | undefined): string {
-  if (!isTestKey(key)) throw new NotATestKeyError();
-  return key;
+  const problem = testKeyProblem(key);
+  if (problem) throw new NotATestKeyError(problem);
+  return key!.trim();
 }
 
 /** For logs and bundles: the prefix and the last four characters, nothing else. */

package/templates/hello-agent/packages/agent-core/src/state-machine.ts

@@ -62,6 +62,13 @@ export interface TransitionRecord {
   actor: Actor;
 }
 
+/** The code and message a rail answered for one attempt, as the rail gave them. */
+export interface RailAnswer {
+  attempt_id: string;
+  code: string;
+  message: string;
+}
+
 export interface Execution<S extends ExecutionState = ExecutionState> {
   id: string;
   run_id: string;
@@ -97,6 +104,13 @@ export interface Execution<S extends ExecutionState = ExecutionState> {
   reason?: ExecutionReason;
   detail?: string;
   outcomes: ItemOutcome[];
+  /**
+   * What the rail answered, verbatim, for attempts whose outcome it left
+   * UNKNOWN (a timeout, a 5xx such as `provider_error`): no outcome exists for
+   * them, so their code and message would otherwise live only in the event
+   * log. An entry whose attempt later gains an outcome is superseded by it.
+   */
+  uncertain_answers?: RailAnswer[];
   history: TransitionRecord[];
   created_at: string;
   updated_at: string;