@codespar/cli 0.18.1 → 0.20.0

package/templates/bills-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/bills-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/bills-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;

package/templates/bills-agent/packages/agent-core/src/strings.ts

@@ -0,0 +1,175 @@
+/**
+ * The strings every agent shares, in each locale: the approval path's lines
+ * (the batch gesture, the per-line question's hint, the waits), the words of
+ * an execution's description, how a payable instrument is shown, and the
+ * operator's lines on the WhatsApp channel. A kit's own words are in its
+ * kit's `strings`.
+ *
+ * DISPLAY ONLY. What a person may ANSWER is not here and does not depend on
+ * the locale: `[s/N]` takes s, sim, y and yes in both, and the batch gesture
+ * takes todas / all, todas exceto / all except, nenhuma / none in both
+ * (`parseBatchGesture`). A prompt shown in English and answered in Portuguese
+ * decides exactly what the same answer decides under a Portuguese prompt.
+ */
+import type { LocaleTable } from "./locale.js";
+
+const pt = {
+  // How an execution reads on the console.
+  execution: "execução",
+  totalByCore: "total (calculado pelo core)",
+  escalatedBy: "escalado por",
+  blocked: (reasons: string, notAuthorized: string) => `bloqueado: ${reasons} — ${notAuthorized}; não há o que aprovar`,
+  replayedSettlement: "já estava pago: a API respondeu com um pagamento anterior desta mesma tentativa; esta execução não moveu dinheiro",
+
+  // The approval path at the keyboard.
+  onlyDeny: "  (o único desfecho possível é negar; aperte Enter)",
+  leftAwaiting: "  deixado em awaiting_approval (rode de novo com --approve ou --deny)",
+  afterLooks: (rounds: number, seconds: number, timedOut: boolean) =>
+    ` após ${rounds} consulta(s), ${seconds}s${timedOut ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`,
+  banner: (name: string, version: string, mode: string, rail: string, mandateWord: string, mandateId: string) => `${name} ${version} — approval: ${mode} — trilho: ${rail} — ${mandateWord} ${mandateId}`,
+  bundleAt: (runId: string, dir: string) => `run ${runId} — bundle em ${dir}`,
+
+  // The batch gesture: one question for a whole list.
+  batchHeader: (ref: string, label: string, count: number, total: string, hash: string) => `  lote ${ref} — ${label}: ${count} linha(s), total ${total}, batch_hash ${hash}…`,
+  batchAlreadySettled: " (já paga; não roda de novo)",
+  batchInProgress: " (em andamento; não roda de novo)",
+  batchAttemptConflict: " (tentativa presa a outro pagamento; não roda de novo)",
+  batchQuestion: "  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] ",
+  batchUnreadable: (count: number) => `  não entendi; responda todas, todas exceto <números de 1 a ${count}> ou nenhuma`,
+  batchApprovedAll: "  -> lista aprovada inteira",
+  batchDeniedAll: "  -> lista negada inteira",
+  batchApprovedExcept: (positions: string) => `  -> lista aprovada exceto ${positions}`,
+
+  // A payable instrument, on the terminal and on WhatsApp.
+  instalmentOf: (instalment: number, count: number) => `Parcela ${instalment}/${count}: `,
+  dueOn: (date: string) => `, vence ${date}`,
+  chargeRef: (chargeId: string) => ` — cobrança ${chargeId}`,
+  pixCopyPaste: "Pix copia e cola:",
+  boletoLine: "Ou pelo boleto, linha digitável:",
+
+  // The collection-hours rule: the envelope refuses to draft outside it, the channel refuses to speak.
+  outsideCollectionHours: (window: string, timezone: string, clock: string) => `fora do horário de cobrança (${window} ${timezone}); agora são ${clock}`,
+
+  // The scenario runner.
+  scenarioReply: (text: string) => `agente: ${text}`,
+  scenarioOk: (cycleSeconds: number | null | undefined, dir: string) =>
+    `== ok — ${cycleSeconds === undefined ? "" : cycleSeconds === null ? "sem ciclo medido — " : `${cycleSeconds}s — `}bundle em ${dir}`,
+
+  // The WhatsApp channel, on the operator's console. None of these reach the person.
+  waBanner: (name: string, version: string, backend: string, mode: string, rail: string, mandateWord: string, mandateId: string) =>
+    `${name} ${version} — canal: whatsapp (${backend}) — approval: ${mode} — trilho: ${rail} — ${mandateWord} ${mandateId}`,
+  waTapIgnored: (rule: string, detail: string) => `  [whatsapp] toque ignorado (${rule}): ${detail}`,
+  waRefused: (rule: string, detail: string) => `  [whatsapp] recusado (${rule}): ${detail}`,
+  waRefusedByBackend: (rule: string, detail: string) => `  [whatsapp] recusado pelo backend (${rule}): ${detail}`,
+  waDeliveryFailed: (messageId: string, codes: string, told: string | undefined) =>
+    `  [operador] ENTREGA FALHOU da mensagem ${messageId} (${codes})${told ? ` — era o aviso de ${told}: a pessoa NÃO foi avisada` : ""}`,
+  waShop: "loja:",
+  waTap: (title: string) => `[toque: ${title}]`,
+  waTapIgnoredMark: (rule: string) => ` (ignorado: ${rule})`,
+  waNotSent: (rule: string) => `(não enviada: ${rule})`,
+  waCopyPaste: "[copia e cola]",
+  waQrImage: "[imagem: QR Pix]",
+  waYou: "  │ você> ",
+  waEmulatorOpen: "  ┌─ WhatsApp (dyvit-wa-sim, emulador local da Cloud API — sem rede externa, sem conta Meta)",
+  waEmulatorClosed: "  └─ fim da conversa",
+  waConversationSummary: (log: string, received: number | undefined, sent: number, refused: number) =>
+    `conversa em ${log} — ${received === undefined ? "" : `${received} recebida(s), `}${sent} enviada(s)${refused ? `, ${refused} recusada(s)` : ""}`,
+  waSimulatedCost: (total: string, currency: string) => `custo simulado desta conversa nas regras da Meta: ${total} ${currency} (conta do emulador, não nossa)`,
+
+  // `poll --channel whatsapp`.
+  pollNoSubject: (conversation: string) =>
+    `a conversa ${conversation} não declara subject: não dá para dizer quais execuções são dela, e mandar o desfecho de outra pessoa nesta conversa é exatamente o que a regra de sigilo proíbe`,
+  pollNothingWaiting: (conversation: string) => `nada aguardando pagador em ${conversation}`,
+  pollLocaleConflict: (conversation: string, recorded: string, asked: string) =>
+    `a conversa ${conversation} foi registrada em ${recorded}; um poll continua a conversa no idioma em que ela começou, e --locale ${asked} a mudaria no meio`,
+  pollNoBundle: (runIds: string) => `nenhum bundle encontrado para ${runIds}: a conversa não pode ser retomada sem o registro dela`,
+  pollBanner: (name: string, version: string, backend: string, conversation: string, openMinutes: number | undefined) =>
+    `${name} ${version} — poll no canal whatsapp (${backend}) — conversa ${conversation} — janela de 24h ${openMinutes === undefined ? "FECHADA: só template aprovado" : `ABERTA (${openMinutes} min restantes): mensagem livre`}`,
+  pollToldByText: "avisado por mensagem livre",
+  pollToldByTemplate: (template: string, fallback: boolean) => `avisado por template ${template}${fallback ? " (reserva: o kit não tem cópia para este desfecho)" : ""}`,
+  pollNotTold: (reason: string, detail: string | undefined) => `não avisado (${reason}${detail ? `: ${detail}` : ""})`,
+  pollNoTemplateForOutcome: (outcome: string) => `a janela de 24h está fechada e o agente não declara template para ${outcome}, nem um template de reserva`,
+  pollTemplateNotDeclared: (template: string) => `o kit pediu o template ${template}, que channels/whatsapp/templates.json não declara`,
+  pollProviderRefused: "o provedor não aceitou a mensagem",
+
+  // What a run did, counted from its executions: printed after the reply, whatever the reply says.
+  runOutcome: (settled: number, failed: number, declined: number, alreadyPaid: number, open: number) =>
+    settled + failed + declined + alreadyPaid + open === 0
+      ? "resultado deste run: nenhuma execução; nada foi pago"
+      : `resultado deste run: ${settled} liquidada(s), ${failed} com falha ou recusada(s), ${declined} negada(s) ou expirada(s), ${alreadyPaid} pulada(s) por já paga(s), ${open} em aberto`,
+};
+
+export type CoreStrings = typeof pt;
+
+const en: CoreStrings = {
+  execution: "execution",
+  totalByCore: "total (computed by the core)",
+  escalatedBy: "escalated by",
+  blocked: (reasons, notAuthorized) => `blocked: ${reasons} — ${notAuthorized}; there is nothing to approve`,
+  replayedSettlement: "already paid: the API answered with an earlier payment of this same attempt; this execution moved no money",
+
+  onlyDeny: "  (the only possible outcome is to deny; press Enter)",
+  leftAwaiting: "  left in awaiting_approval (run again with --approve or --deny)",
+  afterLooks: (rounds, seconds, timedOut) => ` after ${rounds} look(s), ${seconds}s${timedOut ? " (timed out; `npm run poll` picks up where this stopped)" : ""}`,
+  banner: (name, version, mode, rail, mandateWord, mandateId) => `${name} ${version} — approval: ${mode} — rail: ${rail} — ${mandateWord} ${mandateId}`,
+  bundleAt: (runId, dir) => `run ${runId} — bundle in ${dir}`,
+
+  batchHeader: (ref, label, count, total, hash) => `  batch ${ref} — ${label}: ${count} line(s), total ${total}, batch_hash ${hash}…`,
+  batchAlreadySettled: " (already paid; does not run again)",
+  batchInProgress: " (in progress; does not run again)",
+  batchAttemptConflict: " (attempt bound to another payment; does not run again)",
+  batchQuestion: "  Approve the list? [all / all except 3,7 / none] ",
+  batchUnreadable: (count) => `  I did not understand; answer all, all except <numbers from 1 to ${count}> or none`,
+  batchApprovedAll: "  -> list approved in full",
+  batchDeniedAll: "  -> list denied in full",
+  batchApprovedExcept: (positions) => `  -> list approved except ${positions}`,
+
+  instalmentOf: (instalment, count) => `Instalment ${instalment}/${count}: `,
+  dueOn: (date) => `, due ${date}`,
+  chargeRef: (chargeId) => ` — charge ${chargeId}`,
+  pixCopyPaste: "Pix copy and paste:",
+  boletoLine: "Or pay the boleto with this line:",
+
+  outsideCollectionHours: (window, timezone, clock) => `outside collection hours (${window} ${timezone}); it is ${clock} now`,
+
+  scenarioReply: (text) => `agent: ${text}`,
+  scenarioOk: (cycleSeconds, dir) => `== ok — ${cycleSeconds === undefined ? "" : cycleSeconds === null ? "no cycle measured — " : `${cycleSeconds}s — `}bundle in ${dir}`,
+
+  waBanner: (name, version, backend, mode, rail, mandateWord, mandateId) => `${name} ${version} — channel: whatsapp (${backend}) — approval: ${mode} — rail: ${rail} — ${mandateWord} ${mandateId}`,
+  waTapIgnored: (rule, detail) => `  [whatsapp] tap ignored (${rule}): ${detail}`,
+  waRefused: (rule, detail) => `  [whatsapp] refused (${rule}): ${detail}`,
+  waRefusedByBackend: (rule, detail) => `  [whatsapp] refused by the backend (${rule}): ${detail}`,
+  waDeliveryFailed: (messageId, codes, told) => `  [operator] DELIVERY FAILED for message ${messageId} (${codes})${told ? ` — it told ${told}: the person was NOT told` : ""}`,
+  waShop: "shop:",
+  waTap: (title) => `[tap: ${title}]`,
+  waTapIgnoredMark: (rule) => ` (ignored: ${rule})`,
+  waNotSent: (rule) => `(not sent: ${rule})`,
+  waCopyPaste: "[copy and paste]",
+  waQrImage: "[image: Pix QR]",
+  waYou: "  │ you> ",
+  waEmulatorOpen: "  ┌─ WhatsApp (dyvit-wa-sim, a local Cloud API emulator — no external network, no Meta account)",
+  waEmulatorClosed: "  └─ end of conversation",
+  waConversationSummary: (log, received, sent, refused) => `conversation in ${log} — ${received === undefined ? "" : `${received} received, `}${sent} sent${refused ? `, ${refused} refused` : ""}`,
+  waSimulatedCost: (total, currency) => `simulated cost of this conversation under Meta's rules: ${total} ${currency} (the emulator's figure, not ours)`,
+
+  pollNoSubject: (conversation) =>
+    `conversation ${conversation} declares no subject: there is no telling which executions are its own, and sending somebody else's outcome into this conversation is exactly what the secrecy rule forbids`,
+  pollNothingWaiting: (conversation) => `nothing waiting for a payer in ${conversation}`,
+  pollLocaleConflict: (conversation, recorded, asked) => `conversation ${conversation} was recorded in ${recorded}; a poll continues a conversation in the language it started in, and --locale ${asked} would switch it midway`,
+  pollNoBundle: (runIds) => `no bundle found for ${runIds}: the conversation cannot be resumed without its record`,
+  pollBanner: (name, version, backend, conversation, openMinutes) =>
+    `${name} ${version} — poll on the whatsapp channel (${backend}) — conversation ${conversation} — 24h window ${openMinutes === undefined ? "SHUT: approved template only" : `OPEN (${openMinutes} min left): free-form message`}`,
+  pollToldByText: "told by free-form message",
+  pollToldByTemplate: (template, fallback) => `told by template ${template}${fallback ? " (fallback: the kit has no copy for this outcome)" : ""}`,
+  pollNotTold: (reason, detail) => `not told (${reason}${detail ? `: ${detail}` : ""})`,
+  pollNoTemplateForOutcome: (outcome) => `the 24h window is shut and the agent declares no template for ${outcome}, nor a fallback template`,
+  pollTemplateNotDeclared: (template) => `the kit asked for template ${template}, which channels/whatsapp/templates.json does not declare`,
+  pollProviderRefused: "the provider did not accept the message",
+
+  runOutcome: (settled, failed, declined, alreadyPaid, open) =>
+    settled + failed + declined + alreadyPaid + open === 0
+      ? "result of this run: no execution; nothing was paid"
+      : `result of this run: ${settled} settled, ${failed} failed or refused, ${declined} denied or expired, ${alreadyPaid} skipped as already paid, ${open} open`,
+};
+
+export const CORE_STRINGS: LocaleTable<CoreStrings> = { "pt-BR": pt, en };

package/templates/bills-agent/packages/agent-core/src/stubs/charge-rail.ts

@@ -6,7 +6,7 @@
  * "the charge was issued" finds it again on `resume`.
  *
  * The fixture payer lives in the lookups: the first look after issuance
- * finds the instrument registered (a cobranca com vencimento answers
+ * finds the instrument registered (a cobrança com vencimento answers
  * PROCESSING at create and PENDING once the clearing house has it), the
  * second look finds what the payer did: paid (default), let it expire, or
  * nothing yet. With a real key the scenario runner calls the sandbox pay
@@ -29,6 +29,13 @@ export interface StubChargeRailOptions {
   uncertainOnce?: string[];
   /** Test hook: called after the issuance is persisted and before the outcome is returned. */
   afterDispatch?: (attemptId: string) => void;
+  /** Debtor documents whose registration the issuer ends in `ERROR` at the first look: no instrument, ever (staging, 2026-09-27, OPEN_QUESTIONS §63). */
+  issuerErrorPayees?: string[];
+  /**
+   * Debtor documents whose charge never becomes payable and is settled anyway at the second look: what the API's test
+   * pay route did to a charge in `ERROR` on staging (ent#1816). Here so the scenario gate can be shown refusing it.
+   */
+  settlesUnpayablePayees?: string[];
 }
 
 interface PayerState {
@@ -100,8 +107,14 @@ export class StubChargeRail implements PaymentRail {
     const looks = state.looks + 1;
     this.savePayerState(attemptId, { ...state, looks });
 
+    if (this.options.issuerErrorPayees?.includes(payment.payee)) {
+      const failed: RailOutcome = { status: "failed", code: "charge_issuer_error", message: `stub: the issuer ended charge ${outcome.transaction_id}'s registration in ERROR: no Pix, no boleto, nothing a payer can pay`, raw: { stub: true } };
+      this.replace(attemptId, payment, failed);
+      return failed;
+    }
+    if (this.options.settlesUnpayablePayees?.includes(payment.payee) && looks === 1) return this.update(attemptId, payment, "PROCESSING", false);
     // First look: the clearing house registered the instrument. It is payable from here.
-    if (looks === 1 || !outcome.instrument.payable) {
+    if ((looks === 1 || !outcome.instrument.payable) && !this.options.settlesUnpayablePayees?.includes(payment.payee)) {
       return this.update(attemptId, payment, "PENDING", true);
     }
     if (state.fate === "pays") {

package/templates/bills-agent/packages/agent-core/src/stubs/rail.ts

@@ -12,7 +12,7 @@
  */
 import { canonicalJson, sha256Hex } from "../hash.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, type WireActor } from "../rail.js";
 import type { StateStore } from "../state/store.js";
 import type { Actor } from "../types.js";
 
@@ -98,9 +98,11 @@ export class StubRail implements PaymentRail {
     if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
     const approval = checkSpendApproval(payment);
     if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
-    const { actor: _actor, ...request } = payment;
+    const { actor, ...asked } = payment;
+    // Like the API: the actor the spend declared is recorded with it and read back on the receipt, and is not part of the attempt tuple.
+    const request = { ...asked, sealed_actor: wireActorOf(actor) };
     const existing = this.store.stubRailGet(payment.attempt_id);
-    if (existing) return this.repeat(payment.attempt_id, existing.request as Omit<RailPayment, "actor">, existing.outcome as Recorded, request);
+    if (existing) return this.repeat(payment.attempt_id, existing.request as Omit<RailPayment, "actor">, existing.outcome as Recorded, asked);
 
     const uncertainPayee = this.options.uncertainPayees?.includes(payment.payee) === true && !this.uncertainAnswered.has(payment.attempt_id);
     if (this.uncertainArmed || this.uncertainPending.has(payment.attempt_id) || uncertainPayee) {
@@ -169,7 +171,7 @@ export class StubRail implements PaymentRail {
   async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
     const sealed = this.store.stubRailFindByReceipt(receiptId);
     if (!sealed) return undefined;
-    const req = sealed.request as Omit<RailPayment, "actor">;
+    const req = sealed.request as Omit<RailPayment, "actor"> & { sealed_actor?: WireActor };
     const out = sealed.outcome as Extract<RailOutcome, { status: "settled" }>;
     // Like the API: the payee on the receipt is the one the quote sealed, and none when the spend carried no quote.
     const body = {
@@ -192,6 +194,7 @@ export class StubRail implements PaymentRail {
       receipt_sig_ed25519: null,
       receipt_sig_kid: null,
       actor,
+      sealed_actor: req.sealed_actor ?? null,
       raw: { stub: true, transaction_id: out.transaction_id },
     };
   }

package/templates/bills-agent/packages/agent-core/src/types.ts

@@ -122,6 +122,11 @@ export type ExecutionReason =
   | "awaiting_settlement"
   | "charge_expired"
   | "charge_cancelled"
+  /**
+   * The issuer ended the receivable's registration in an error state (`ERROR`): no Pix, no boleto, nothing a payer can
+   * pay, and nothing will be. Terminal, and nothing was collected. Measured on staging on 2026-09-27 (OPEN_QUESTIONS §63).
+   */
+  | "charge_issuer_error"
   /**
    * An ISSUED receivable whose read now answers that its reference matches more than one charge. Terminal for the
    * execution, but not "nothing moved": the charge exists and may still be paid. Reconcile it by the charge id; never
@@ -166,16 +171,24 @@ export interface ItemOutcome {
   transaction_id?: string;
   /** The rail's code on a failed outcome (`charge_expired`, `charge_cancelled`, a provider code). */
   code?: string;
+  /** The rail's own message on a failed outcome, verbatim: for the CodeSpar rail, the API's `error.message`. */
+  message?: string;
   /** A failed outcome because the attempt id is held for another payment or another project (`RailOutcome.held`). */
   held?: "conflict" | "unavailable";
-  /** A settled outcome the rail answered from its record of an earlier presentation (`RailOutcome.replayed`). */
+  /**
+   * A settled outcome the rail answered, at dispatch, from its record of an
+   * earlier presentation (`RailOutcome.replayed`): the first time THIS
+   * execution presented the attempt, it was already paid, so this execution
+   * moved nothing for it. Never set by reconcile, whose lookup re-presents an
+   * attempt this execution already sent and cannot tell whose payment it reads.
+   */
   replayed?: true;
   error?: string;
   /** What the payer is shown for an accepted receivable, as the rail handed it back. Presentation only; nothing here decides money. */
   instrument?: ChargeInstrument;
 }
 
-/** The payable legs of a receivable. Null until the issuer registers the instrument (a cobranca com vencimento answers PROCESSING first). */
+/** The payable legs of a receivable. Null until the issuer registers the instrument (a cobrança com vencimento answers PROCESSING first). */
 export interface ChargeInstrument {
   payable: boolean;
   pix_copy_paste: string | null;

package/templates/bills-agent/packages/agent-core/test/actor-on-the-wire.test.ts

@@ -0,0 +1,144 @@
+/**
+ * OPEN_QUESTIONS §2: every spend carries the kit's `actor` on the wire, in the
+ * API's `PaymentActor` shape (@codespar/sdk 0.16.10); the receipt reads it
+ * back; the engine compares what came back with what was sent, and a
+ * different actor, or none, is an event in the bundle.
+ */
+import type { ApiClient } from "@codespar/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { CodeSparRail } from "../src/api/rail.js";
+import { copyDisagreesWithRead } from "../src/bundle.js";
+import { sameWireActor, wireActorOf, type PaymentRail, type RailPayment, type WireActor } from "../src/rail.js";
+import type { Actor } from "../src/types.js";
+import { ESCOLA, harness } from "./helpers.js";
+
+const approver = { id: "usr_demo", channel: "terminal" };
+const agentActor: Actor = { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" };
+const ITEMS_HASH = `sha256:${"1".repeat(64)}`;
+
+function payment(over: Partial<RailPayment> = {}): RailPayment {
+  return {
+    attempt_id: "att_actor_0",
+    mandate_id: "mdt_test_0001",
+    amount_minor: 185000,
+    currency: "BRL",
+    payee: ESCOLA,
+    purpose: "contas do mes",
+    agent_id: "bills-agent",
+    quote: { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, at: "2026-09-23T18:00:00.000Z" },
+    approval: { items_hash: ITEMS_HASH },
+    actor: agentActor,
+    ...over,
+  };
+}
+
+function fakeApi(receiptBody?: unknown) {
+  const post = vi.fn(async (_path: string, _init: { body: Record<string, unknown> }) => ({ payment: { transactionId: "tx_1", moneyMoved: false }, receipt: { id: "rcpt_1" } }));
+  return { api: { post, get: vi.fn(async () => receiptBody) } as unknown as ApiClient, post };
+}
+
+/** The stub rail, but the receipt it hands back records whatever actor the test says. */
+function recordingActor(sealed: WireActor | null) {
+  return (inner: PaymentRail): PaymentRail => ({
+    name: inner.name,
+    pay: (p) => inner.pay(p),
+    lookup: (id, p, tx) => inner.lookup(id, p, tx),
+    receipt: async (id, a) => {
+      const r = await inner.receipt(id, a);
+      return r && { ...r, sealed_actor: sealed };
+    },
+  });
+}
+
+describe("the actor, in the API's shape", () => {
+  it("an agent is its identifier and the consumer it acts for; a person is an id and the channel they acted from", () => {
+    expect(wireActorOf(agentActor)).toEqual({ type: "agent", id: "bills-agent@0.1.0", on_behalf_of: "usr_demo" });
+    expect(wireActorOf({ type: "human", id: "usr_ana", channel: "whatsapp" })).toEqual({ type: "human", id: "usr_ana", channel: "whatsapp" });
+  });
+
+  it("the same actor is the same on every field, and the channel counts", () => {
+    const person: WireActor = { type: "human", id: "usr_ana", channel: "whatsapp" };
+    expect(sameWireActor(person, { ...person })).toBe(true);
+    expect(sameWireActor(person, { ...person, channel: "dashboard" })).toBe(false);
+    expect(sameWireActor(wireActorOf(agentActor), { type: "agent", id: "bills-agent@0.1.0", on_behalf_of: "usr_other" })).toBe(false);
+    expect(sameWireActor(wireActorOf(agentActor), person)).toBe(false);
+    expect(sameWireActor(null, wireActorOf(agentActor))).toBe(false);
+    expect(sameWireActor(null, null)).toBe(true);
+  });
+});
+
+describe("the CodeSpar rail sends it and reads it back", () => {
+  it("both spend routes carry the actor, not only agent_id", async () => {
+    const byEnvelope = fakeApi();
+    await new CodeSparRail(byEnvelope.api, { canonical: { any: "envelope" } as never, signature: "a".repeat(64) }).pay(payment());
+    expect(byEnvelope.post.mock.calls[0]![0]).toBe("/v1/consumer-payments/execute");
+    expect(byEnvelope.post.mock.calls[0]![1].body["actor"]).toEqual({ type: "agent", id: "bills-agent@0.1.0", on_behalf_of: "usr_demo" });
+    const byId = fakeApi();
+    await new CodeSparRail(byId.api).pay(payment({ actor: { type: "human", id: "usr_ana", channel: "whatsapp" } }));
+    expect(byId.post.mock.calls[0]![0]).toBe("/v1/consumers/mandates/{id}/spend");
+    expect(byId.post.mock.calls[0]![1].body["actor"]).toEqual({ type: "human", id: "usr_ana", channel: "whatsapp" });
+    // agent_id still goes: it names who the mandate was signed for, which is an authority and not the event.
+    expect(byId.post.mock.calls[0]![1].body["agent_id"]).toBe("bills-agent");
+  });
+
+  it("the receipt read gives back the actor the API recorded, and null when it recorded none", async () => {
+    const read = {
+      receipt_id: "rcpt_1",
+      state: "paid",
+      chain_version: 4,
+      actor: { type: "agent", id: "bills-agent@0.1.0", on_behalf_of: "usr_demo" },
+      mandate: { id: "cm_1", nonce: "n", scope: "s", currency: "BRL", sig: "x", sig_sha256: "d".repeat(64) },
+      quote: { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: ESCOLA, session_id: null, sig: "q", at: "2026-09-23T18:00:00.000Z" },
+      approval: { items_hash: ITEMS_HASH, batch_hash: null },
+      payment: { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_actor_0", money_moved: false, at: "2026-09-23T18:00:01.000Z" },
+      delivery: null,
+      chain: "c".repeat(64),
+      receipt_sig: "s",
+      exceptions: [],
+    };
+    const receipt = await new CodeSparRail(fakeApi(read).api).receipt("rcpt_1", agentActor);
+    expect(receipt?.sealed_actor).toEqual({ type: "agent", id: "bills-agent@0.1.0", on_behalf_of: "usr_demo" });
+    // The local stamp stays the kit's own: the two are compared, never merged.
+    expect(receipt?.actor).toEqual(agentActor);
+    expect((await new CodeSparRail(fakeApi({ ...read, actor: null }).api).receipt("rcpt_1", agentActor))?.sealed_actor).toBeNull();
+  });
+});
+
+describe("the engine compares what came back with what was sent", () => {
+  const run = async (wrap?: (inner: PaymentRail) => PaymentRail) => {
+    const h = harness({ mode: "human", ...(wrap ? { wrapRail: wrap } : {}) });
+    const d = await h.engine.draft({ items: [{ payee: "escola", amount: 185000 }] });
+    if (!d.ok) throw new Error("refused");
+    const done = await h.engine.execute(h.engine.approve(d.execution.id, approver).id);
+    return { h, done };
+  };
+
+  it("the same actor back: nothing to say, and the bundle's receipt copy carries both the stamp and what the API recorded", async () => {
+    const { h, done } = await run();
+    expect(done.state).toBe("settled");
+    expect(h.bundle.readEvents().some((e) => e["type"] === "receipt.actor_mismatch")).toBe(false);
+    const copy = h.bundle.readReceipt(h.bundle.listReceipts()[0]!)!;
+    expect(copy["sealed_actor"]).toEqual(wireActorOf(h.engine.agentActor));
+    expect(copy["actor"]).toEqual(h.engine.agentActor);
+  });
+
+  for (const [name, sealed] of [
+    ["another actor", { type: "human", id: "usr_intruso", channel: "dashboard" } as WireActor],
+    ["no actor at all", null],
+  ] as const) {
+    it(`a receipt that records ${name} is a receipt.actor_mismatch event; the payment stands`, async () => {
+      const { h, done } = await run(recordingActor(sealed));
+      expect(done.state).toBe("settled");
+      const mismatch = h.bundle.readEvents().find((e) => e["type"] === "receipt.actor_mismatch");
+      expect(mismatch?.["payload"]).toMatchObject({ sealed_actor: sealed, sent_actor: wireActorOf(h.engine.agentActor) });
+      expect(mismatch?.["actor"]).toBeDefined();
+    });
+  }
+
+  it("verify's copy check flags a copy whose recorded actor is not the read's", () => {
+    const read = { receipt_id: "r", chain: "c", mandate: { id: "m" }, payment: { amount_minor: 1, attempt_id: "a", money_moved: false, at: "t" }, actor: { type: "agent", id: "x", on_behalf_of: "u" } };
+    const copy = { receipt_id: "r", chain: "c", mandate: { id: "m" }, payment: { amount_minor: 1, attempt_id: "a", money_moved: false, at: "t", payee: null }, sealed_actor: { type: "agent", id: "y", on_behalf_of: "u" } };
+    expect(copyDisagreesWithRead(copy, read)).toEqual(["sealed_actor"]);
+    expect(copyDisagreesWithRead({ ...copy, sealed_actor: read.actor }, read)).toEqual([]);
+  });
+});

package/templates/bills-agent/packages/agent-core/test/attempt-replay.test.ts

@@ -65,8 +65,8 @@ beforeEach(() => {
 });
 
 function rail(): CodeSparRail {
-  // The placeholder passes the `csk_test_` guard and is the one test-key-shaped string the secret scan allows.
-  return new CodeSparRail(createCodeSparClient({ apiKey: "csk_test_your_key_here", baseUrl, timeoutMs: 5_000 }));
+  // Not the placeholder, which the guard refuses (#50); the underscore keeps it below the secret scan's key shape.
+  return new CodeSparRail(createCodeSparClient({ apiKey: "csk_test_unit_0000", baseUrl, timeoutMs: 5_000 }));
 }
 
 function refusal(code: string, details?: Record<string, unknown>): Answer {