@codespar/cli 0.18.1 → 0.20.0

package/templates/checkout-agent/packages/agent-core/src/agent.ts

@@ -6,6 +6,7 @@
  */
 import type { ProofBundle } from "./bundle.js";
 import type { ExecutionEngine } from "./engine.js";
+import { detectLanguage, replyLanguageDirective, type ReplyLanguage } from "./language.js";
 import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
 import { isReply } from "./providers/types.js";
 import type { Execution } from "./state-machine.js";
@@ -25,6 +26,23 @@ export interface ToolContext {
    * `onExecution`, and still mints its own artifact.
    */
   onBatch?: (batch: BatchPresentation) => Promise<BatchGesture | undefined>;
+  /**
+   * Fires for a line a payment tool was asked to pay and created NO execution
+   * for in this run: one an earlier run already covers, or one refused before
+   * a draft existed. Without it such a line leaves nothing behind for the
+   * channel to count, and a run that paid nobody reads like one that had
+   * nothing to say.
+   */
+  onNotRun?: (line: NotRunLine) => void;
+}
+
+/** A line a payment tool did not turn into an execution in this run, and why. */
+export interface NotRunLine {
+  /** What the person would call the line: a batch line's alias, a payee. */
+  ref: string;
+  /** `already_settled`: an earlier run paid it. `in_progress`: an earlier execution for it is still open. `refused`: it was refused before a draft. */
+  why: "already_settled" | "in_progress" | "refused";
+  detail?: string;
 }
 
 /** What a person sees when a whole batch is put in front of them: the list, its total, and the hash of the list. */
@@ -74,6 +92,8 @@ export interface TurnResult {
   reply: string;
   tool_calls: Array<{ name: string; refused: boolean }>;
   executions: Execution[];
+  /** Lines the turn's payment tools did not turn into an execution (`ToolContext.onNotRun`). */
+  not_run: NotRunLine[];
 }
 
 export class AgentLoop {
@@ -81,6 +101,8 @@ export class AgentLoop {
   private readonly allowed: Set<string>;
   private readonly specs: ToolSpec[];
   private readonly clock: () => Date;
+  /** The language the person last wrote in, kept when a turn gives no lead of its own ("ok"). */
+  private language: ReplyLanguage | undefined;
 
   constructor(private readonly options: AgentLoopOptions) {
     this.allowed = allowedToolNames(options.tools);
@@ -97,24 +119,28 @@ export class AgentLoop {
     const maxSteps = this.options.maxSteps ?? 8;
     const calls: TurnResult["tool_calls"] = [];
     const executions: Execution[] = [];
+    const notRun: NotRunLine[] = [];
+
+    this.language = detectLanguage(userText) ?? this.language;
+    const system = this.language ? `${this.options.system.trimEnd()}\n\n${replyLanguageDirective(this.language)}\n` : this.options.system;
 
     this.messages.push({ role: "user", content: userText });
-    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText, reply_language: this.language ?? null });
 
     for (let step = 0; step < maxSteps; step += 1) {
-      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      const out = await runtime.step({ system, messages: this.messages }, this.specs);
       if (isReply(out)) {
         this.messages.push({ role: "assistant", content: out.text });
         bundle.transcript({ at: this.now(), kind: "assistant_step", reply: out.text });
         bundle.transcript({ at: this.now(), kind: "assistant", text: out.text });
-        return { reply: out.text, tool_calls: calls, executions };
+        return { reply: out.text, tool_calls: calls, executions, not_run: notRun };
       }
 
       this.messages.push({ role: "assistant", content: "", tool_calls: out });
       bundle.transcript({ at: this.now(), kind: "assistant_step", tool_calls: out });
 
       for (const call of out) {
-        const result = await this.dispatch(call, executions);
+        const result = await this.dispatch(call, executions, notRun);
         calls.push({ name: call.name, refused: result.refused });
         this.messages.push({ role: "tool", tool_call_id: call.id, name: call.name, content: JSON.stringify(result.content), ...(result.refused ? { is_error: true } : {}) });
         bundle.transcript({ at: this.now(), kind: "tool_result", tool_call_id: call.id, name: call.name, refused: result.refused, content: result.content });
@@ -124,10 +150,10 @@ export class AgentLoop {
     const text = "I stopped: too many tool steps in one turn. Nothing was paid beyond what the trail shows.";
     this.messages.push({ role: "assistant", content: text });
     bundle.transcript({ at: this.now(), kind: "assistant", text, truncated: true });
-    return { reply: text, tool_calls: calls, executions };
+    return { reply: text, tool_calls: calls, executions, not_run: notRun };
   }
 
-  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+  private async dispatch(call: ToolCall, executions: Execution[], notRun: NotRunLine[]): Promise<{ refused: boolean; content: unknown }> {
     const { bundle, handlers, engine, onExecution, onBatch } = this.options;
     bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
 
@@ -148,6 +174,7 @@ export class AgentLoop {
           return settledOrNot;
         },
         ...(onBatch ? { onBatch } : {}),
+        onNotRun: (line) => void notRun.push(line),
       });
       return { refused: false, content };
     } catch (err) {

package/templates/checkout-agent/packages/agent-core/src/api/charge-rail.ts

@@ -1,6 +1,6 @@
 /**
  * The CodeSpar receivable rail: the merchant COLLECTS. `pay()` issues a
- * cobranca com vencimento through `POST /v1/charges` (the REST form of the
+ * cobrança com vencimento through `POST /v1/charges` (the REST form of the
  * `codespar_charge` meta-tool, action=create): `method: "boleto"` plus a
  * `due_date` is what makes it ONE receivable the payer settles either by
  * boleto or by Pix; `idempotency_key` is REQUIRED on that create and is our
@@ -65,6 +65,17 @@ export function instrumentOf(view: ChargeView): ChargeInstrument {
   };
 }
 
+/**
+ * Issuer statuses that end a registration with no instrument: no Pix, no
+ * boleto, nothing a payer can pay, and nothing will be. `ERROR` is the one
+ * measured (staging, 2026-09-27, OPEN_QUESTIONS §63): the read's documented
+ * set is `PROCESSING`, `PENDING`, `CONFIRMED`, `CANCELLED`, `EXPIRED`, and the
+ * field is a plain string. Any status this kit does not know stays
+ * `accepted` and unpayable: failing it could close an order a payer may yet
+ * pay, and waiting pays nobody.
+ */
+export const ISSUER_ERROR_STATUSES: readonly string[] = ["ERROR"];
+
 /** What a charge view means for the attempt. The row's own status wins over the issuer's normalized one where they name a terminal state. */
 export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight" } {
   if (view.issuance_unconfirmed || !view.id) return { status: "in_flight" };
@@ -78,6 +89,9 @@ export function outcomeOf(view: ChargeView): RailOutcome | { status: "in_flight"
   if (view.status === "CANCELLED" || view.local_status === "cancelled") {
     return { status: "failed", code: "charge_cancelled", message: `charge ${id} was withdrawn`, raw: view };
   }
+  if (ISSUER_ERROR_STATUSES.includes(view.status)) {
+    return { status: "failed", code: "charge_issuer_error", message: `the issuer ended charge ${id}'s registration in ${view.status}: no Pix, no boleto, nothing a payer can pay`, raw: view };
+  }
   return { status: "accepted", transaction_id: id, instrument: instrumentOf(view), sandbox: true, raw: view };
 }
 

package/templates/checkout-agent/packages/agent-core/src/api/rail.ts

@@ -10,14 +10,17 @@
  * envelope is preferred when it exists. Receipts come back from
  * `GET /v1/consumers/receipts/{id}`.
  *
- * The API has no `actor` field on the wire today (OPEN_QUESTIONS §2). The
- * spend carries `agent_id`, which the mandate binds; the full actor is
- * stamped on the local receipt copy and on every event of the bundle.
+ * Every spend carries the kit's `actor` on the wire (`PaymentActor`,
+ * @codespar/sdk 0.16.10): the agent and the consumer it acts for, or the
+ * person and their channel. The API records it on the receipt and reads it
+ * back, and the engine compares what came back with what was sent
+ * (OPEN_QUESTIONS §2). `agent_id` still goes too: it names the agent the
+ * mandate was SIGNED for, which is an authority, not the event.
  */
 import type { ApiClient } from "@codespar/sdk";
 import type { Mandate } from "../mandate.js";
 import { checkQuote } from "../quote.js";
-import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
+import { checkSpendApproval, wireActorOf, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
 import type { Actor } from "../types.js";
 import { describeApiError, isUncertain, type SpendErrorCode } from "./client.js";
 
@@ -59,11 +62,12 @@ export class CodeSparRail implements PaymentRail {
                 attempt_id: payment.attempt_id,
                 quote: quoted.quote,
                 approval: approval.approval,
+                actor: wireActorOf(payment.actor),
               },
             })
           : await this.api.post("/v1/consumers/mandates/{id}/spend", {
               path: { id: payment.mandate_id },
-              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval, actor: wireActorOf(payment.actor) },
             });
       return {
         status: "settled",
@@ -142,6 +146,8 @@ export class CodeSparRail implements PaymentRail {
         receipt_sig_ed25519: r.receipt_sig_ed25519 || null,
         receipt_sig_kid: r.receipt_sig_kid || null,
         actor,
+        // What the API recorded, as it read it back; the engine compares it with what the spend sent.
+        sealed_actor: r.actor,
         raw: r,
       };
     } catch (err) {

package/templates/checkout-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -14,6 +14,7 @@
  */
 import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
 import type { ApiFailure } from "./client.js";
+import { ISSUER_ERROR_STATUSES, type ChargeView } from "./charge-rail.js";
 import { createCodeSparClient, describeApiError } from "./client.js";
 
 /** What the payer route answers, as the SDK's generated OpenAPI types it. */
@@ -41,3 +42,38 @@ export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, c
     return { ok: false, failure: describeApiError(err) };
   }
 }
+
+/** Why the payer did not call the pay route: there was nothing a payer could have paid. */
+export type PayerRefusal = { code: "no_payable_instrument" | "charge_issuer_error"; message: string };
+
+export type GuardedPayResult = SandboxPayResult | { ok: false; refused: PayerRefusal };
+
+/**
+ * The sandbox payer as a PAYER: it reads the charge first and pays only an
+ * instrument a person could have paid, a Pix or a boleto line the read calls
+ * `payable`. A charge the issuer ended in error (`ERROR`) is refused as
+ * `charge_issuer_error`, anything else unpayable as `no_payable_instrument`,
+ * and in both cases the pay route is never called.
+ *
+ * The route itself settles whatever it is handed: a charge still
+ * `PROCESSING`, and on staging on 2026-09-27 a charge the issuer ended in
+ * `ERROR`, after which the read answers `CONFIRMED` (ent#1816,
+ * OPEN_QUESTIONS §63). A payer that trusted it turned an issuance that failed
+ * into a "settled" order no customer could have paid. No live payer can pay a
+ * charge with no instrument, so neither does this one.
+ */
+export async function payIfPayable(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<GuardedPayResult> {
+  let view: ChargeView;
+  try {
+    view = await api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } });
+  } catch (err) {
+    return { ok: false, failure: describeApiError(err) };
+  }
+  if (ISSUER_ERROR_STATUSES.includes(view.status)) {
+    return { ok: false, refused: { code: "charge_issuer_error", message: `the issuer ended charge ${chargeRef}'s registration in ${view.status}; there is no instrument to pay, so the pay route was not called` } };
+  }
+  if (!view.payable) {
+    return { ok: false, refused: { code: "no_payable_instrument", message: `charge ${chargeRef} has no payable instrument (status ${view.status}, local ${view.local_status}); the pay route was not called` } };
+  }
+  return paySandboxCharge(api, chargeRef, amountMinor);
+}

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

@@ -178,6 +178,8 @@ export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Recor
   // 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)]);
+  // Written onto the copy since every spend carries the actor (§2); the read calls it `actor`, the copy `sealed_actor` beside its own stamp.
+  if ("sealed_actor" in copy) expected.push(["sealed_actor", canonicalJson(copy["sealed_actor"] ?? null), canonicalJson(read["actor"] ?? null)]);
   return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
 }
 

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

@@ -154,22 +154,32 @@ export const TemplateRegistrySchema = z
   })
   .strict()
   .superRefine((registry, ctx) => {
+    // Meta approves a template per (name, language): the same name in two languages is two templates, the same pair twice is one declared twice.
     const seen = new Set<string>();
     const replyIds = new Set<string>();
+    const replyOwner = new Map<string, 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.
+      const pair = `${template.name}/${template.language}`;
+      if (seen.has(pair)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice in ${template.language}` });
+      seen.add(pair);
+      // A tap is resolved by its id in the conversation's language, so one id means one intent per language, and one template across languages.
       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);
+        if (replyIds.has(`${button.id}/${template.language}`)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice in ${template.language}` });
+        replyIds.add(`${button.id}/${template.language}`);
+        const owner = replyOwner.get(button.id);
+        if (owner !== undefined && owner !== template.name) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is offered by ${owner} and by ${template.name}` });
+        replyOwner.set(button.id, template.name);
       }
     }
   });
 
-/** 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]));
+/**
+ * Every quick reply the registry declares, by id: the only taps that can
+ * become a turn. With a `language`, only the copies declared in it: an English
+ * conversation hands the model the English intent of the button it tapped.
+ */
+export function declaredReplies(templates: readonly WhatsAppTemplate[], language?: string): Map<string, QuickReply> {
+  return new Map(templates.filter((t) => language === undefined || t.language === language).flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
 }
 
 export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;

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

@@ -14,6 +14,7 @@ import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js
 import { MandateSchema } from "./mandate.js";
 import { ToolsFileSchema } from "./tools.js";
 import { canonicalJson } from "./hash.js";
+import { LOCALES, WHATSAPP_LANGUAGE } from "./locale.js";
 import { PUBLISHED_EVENTS, isPublishedEvent } from "./events.js";
 
 export interface CheckFinding {
@@ -145,9 +146,30 @@ export function checkAgent(agentDir: string): CheckReport {
   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 names = [...new Set(registry.templates.filter((t) => t.fallback).map((t) => t.name))];
+      if (names.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${names.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
+      for (const fallback of registry.templates.filter((t) => t.fallback)) {
+        if (templateArity(fallback.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallback.name} (${fallback.language}) takes variables; it is sent when nothing specific can be said, so it takes none`);
+      }
+    }
+  }
+  // A conversation speaks the language of its locale, and either locale can be
+  // chosen per run (`--locale`), so every template exists in the language of
+  // every locale, with the same buttons and the same variables. A template
+  // missing in one language is an outcome that locale cannot tell once the
+  // 24-hour window shuts.
+  if (registry) {
+    const languages = LOCALES.map((l) => WHATSAPP_LANGUAGE[l]);
+    for (const template of registry.templates) {
+      if (!languages.includes(template.language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${template.name} is declared in ${template.language}, which no locale sends; the locales send ${languages.join(", ")}`);
+    }
+    for (const name of [...new Set(registry.templates.map((t) => t.name))]) {
+      const copies = registry.templates.filter((t) => t.name === name);
+      for (const language of languages) {
+        if (!copies.some((t) => t.language === language)) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${name} has no ${language} copy; a conversation in that locale could not send it`);
+      }
+      const shape = (t: (typeof copies)[number]) => JSON.stringify({ arity: templateArity(t.body), buttons: (t.buttons ?? []).map((b) => b.id), fallback: t.fallback ?? false });
+      if (new Set(copies.map(shape)).size > 1) error("channels_templates_locale", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: the copies of ${name} differ in variables, buttons or fallback across languages; a translation says the same thing`);
     }
   }
   if (existsSync(registryPath)) {

package/templates/checkout-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/checkout-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/checkout-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/checkout-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");
+}