@codespar/cli 0.14.0 → 0.16.0

package/templates/supplier-payments-agent/packages/agent-core/src/channels.ts

@@ -0,0 +1,140 @@
+/**
+ * The channels an agent can be reached on, and the one artifact an agent
+ * ships per channel.
+ *
+ * The NAMES live here because `agent.yaml` declares them and `npm run check`
+ * has to confirm the declaration against what the agent ships; the BEHAVIOUR
+ * lives in `@codespar/agent-runtime`, which owns the runner. That split is
+ * the same one `tools.json` and `guardrails.json` already have: the core
+ * owns the shape, the runtime owns what happens.
+ *
+ * `terminal` is every agent's: `npm start` opens it and needs no account.
+ * `whatsapp` is the second channel, and an agent that declares it ships the
+ * conversations the local Cloud API emulator drives, under
+ * `channels/whatsapp/`.
+ */
+import { z } from "zod";
+
+export const CHANNELS = ["terminal", "whatsapp"] as const;
+export type ChannelName = (typeof CHANNELS)[number];
+
+/** E.164, the only contact shape WhatsApp addresses. */
+export const E164 = /^\+[1-9]\d{6,14}$/;
+
+/**
+ * A scripted conversation, which is what an agent ships for a channel whose
+ * other side is a person rather than a keyboard.
+ *
+ * It exists for two readers. A local emulator of the Cloud API drives it with
+ * no Meta account, which is what makes the WhatsApp gate runnable in the CI;
+ * and `npm run check` parses it, so a conversation that no longer names a
+ * contact or an agreement fails the manifest gate instead of failing a run.
+ *
+ * It scripts ONE side. What the agent answers comes from the model or from a
+ * recorded transcript, never from here, for the same reason a scenario pack
+ * asserts a final state and not a wording.
+ */
+export const ConversationScriptSchema = z
+  .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string().min(1),
+    channel: z.literal("whatsapp"),
+    /** The contact the conversation is bound to: the person who owes, and nobody else. */
+    contact: z.string().regex(E164, "contact must be E.164, e.g. +5511987654321"),
+    /**
+     * What this conversation is allowed to be about — an agreement alias for a
+     * collections agent. The channel refuses an outbound message that names a
+     * different one, which is the secrecy rule as code rather than as prose.
+     */
+    subject: z.string().min(1).optional(),
+    /** The person's turns, in order. */
+    turns: z
+      .array(
+        z
+          .object({
+            text: z.string().min(1),
+            /** Seconds after the previous inbound turn, on the run's clock. Keeps a scripted run deterministic. */
+            after_seconds: z.number().int().nonnegative().default(0),
+          })
+          .strict(),
+      )
+      .nonempty(),
+  })
+  .strict();
+
+export type ConversationScript = z.infer<typeof ConversationScriptSchema>;
+
+export function parseConversationScript(text: string): ConversationScript {
+  return ConversationScriptSchema.parse(JSON.parse(text));
+}
+
+/**
+ * The reserved file name inside `channels/whatsapp/`: the template registry,
+ * which is not a conversation. Everything else in that directory is one, so
+ * a conversation may not be called `templates`.
+ */
+export const TEMPLATE_REGISTRY_FILE = "templates.json";
+
+/**
+ * One template the agent declares it sends.
+ *
+ * `body` is here for a reader, not for a sender: it is the text AS SUBMITTED
+ * to Meta, and it is the only way somebody opening this repository can tell
+ * what `{{1}}` means. Nothing composes a message from it — Meta holds the
+ * approved copy and renders it — but the number of placeholders in it IS
+ * checked against the variables a send carries, because a count that does not
+ * match is a `132000` from the Cloud API and there is no reason to learn that
+ * in production.
+ */
+export const WhatsAppTemplateSchema = z
+  .object({
+    /** Meta's own naming rule for a template. */
+    name: z.string().regex(/^[a-z0-9_]+$/, "a template name is lower-case letters, digits and underscores"),
+    /** Meta's language code, e.g. `pt_BR`. A template approved in one language does not exist in another. */
+    language: z.string().regex(/^[a-z]{2}(_[A-Z]{2})?$/, 'expected a language code, e.g. "pt_BR"'),
+    description: z.string().min(1),
+    body: z.string().min(1),
+  })
+  .strict();
+
+export type WhatsAppTemplate = z.infer<typeof WhatsAppTemplateSchema>;
+
+/**
+ * `channels/whatsapp/templates.json`: the LOCAL registry of the templates an
+ * agent uses.
+ *
+ * Outside the 24 hours that follow the person's last message WhatsApp carries
+ * an approved template and nothing else, so an agent that ever speaks after
+ * that has to own one. Whether META approved it is NOT knowable from here —
+ * it is a status inside a Business account, and this repository has none — so
+ * what this file proves is narrower and worth stating exactly: the agent
+ * declared the name, so a send of a name nobody declared is refused here
+ * instead of 400-ing at Meta. Registering the template and getting it approved
+ * stays the developer's, and the README says so.
+ */
+export const TemplateRegistrySchema = z
+  .object({
+    channel: z.literal("whatsapp"),
+    templates: z.array(WhatsAppTemplateSchema).nonempty(),
+  })
+  .strict()
+  .superRefine((registry, ctx) => {
+    const seen = new Set<string>();
+    for (const [i, template] of registry.templates.entries()) {
+      if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
+      seen.add(template.name);
+    }
+  });
+
+export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;
+
+export function parseTemplateRegistry(text: string): TemplateRegistry {
+  return TemplateRegistrySchema.parse(JSON.parse(text));
+}
+
+/** The highest `{{n}}` in a template body, which is how many variables a send of it must carry. */
+export function templateArity(body: string): number {
+  let highest = 0;
+  for (const match of body.matchAll(/\{\{\s*(\d+)\s*\}\}/g)) highest = Math.max(highest, Number(match[1]));
+  return highest;
+}

package/templates/supplier-payments-agent/packages/agent-core/src/check.ts

@@ -0,0 +1,253 @@
+/**
+ * `npm run check`: the manifest is the index, and the files it points to
+ * must agree with it. Fails on a contradiction between `agent.yaml` and
+ * `SYSTEM_PROMPT.md`, `tools.json`, `guardrails.json` or `channels/`, on
+ * `AGENTS.md` and `CLAUDE.md` diverging, and on a missing `mcp`, `cli` or
+ * `schema`.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, templateArity } from "./channels.js";
+import { GuardrailsSchema } from "./guardrails.js";
+import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js";
+import { MandateSchema } from "./mandate.js";
+import { ToolsFileSchema } from "./tools.js";
+import { canonicalJson } from "./hash.js";
+import { PUBLISHED_EVENTS, isPublishedEvent } from "./events.js";
+
+export interface CheckFinding {
+  level: "error" | "warning";
+  code: string;
+  message: string;
+}
+
+export interface CheckReport {
+  ok: boolean;
+  agent: string | null;
+  findings: CheckFinding[];
+}
+
+export function checkAgent(agentDir: string): CheckReport {
+  const findings: CheckFinding[] = [];
+  const error = (code: string, message: string) => findings.push({ level: "error", code, message });
+  const warning = (code: string, message: string) => findings.push({ level: "warning", code, message });
+
+  const manifestPath = join(agentDir, "agent.yaml");
+  if (!existsSync(manifestPath)) {
+    error("manifest_missing", `${manifestPath} does not exist`);
+    return { ok: false, agent: null, findings };
+  }
+
+  // Pinned versions and schema are checked on the raw document, so the message names the field instead of a Zod path.
+  const raw = parseYaml(readFileSync(manifestPath, "utf8")) as Record<string, unknown> | null;
+  for (const field of ["schema", "mcp", "cli"]) {
+    if (!raw || raw[field] === undefined) error("manifest_field_missing", `agent.yaml has no \`${field}\``);
+  }
+  // The events an agent declares must be ones the API publishes; the list is the core's (events.ts), the manifest only names entries of it.
+  for (const name of Array.isArray(raw?.["events"]) ? raw["events"] : []) {
+    if (typeof name === "string" && !isPublishedEvent(name)) error("events_unknown", `agent.yaml declares the event \`${name}\`, which the API does not publish; known: ${PUBLISHED_EVENTS.join(", ")}`);
+  }
+
+  let loaded: LoadedManifest;
+  try {
+    loaded = loadManifest(manifestPath);
+  } catch (err) {
+    error("manifest_invalid", err instanceof Error ? err.message : String(err));
+    return { ok: false, agent: typeof raw?.["name"] === "string" ? (raw["name"] as string) : null, findings };
+  }
+  const { manifest } = loaded;
+
+  // tools.json
+  let toolNames: string[] = [];
+  // Hoisted: the receipt-verification rule below needs it, and only a payment
+  // seals a receipt.
+  let hasPayment = false;
+  const toolsPath = loaded.resolvePath(manifest.tools);
+  if (!existsSync(toolsPath)) error("tools_missing", `${manifest.tools} does not exist`);
+  else {
+    const parsed = ToolsFileSchema.safeParse(JSON.parse(readFileSync(toolsPath, "utf8")));
+    if (!parsed.success) error("tools_invalid", parsed.error.message);
+    else {
+      toolNames = [...parsed.data.meta_tools, ...parsed.data.local_tools].map((t) => t.name);
+      hasPayment = parsed.data.meta_tools.some((t) => t.effect === "payment");
+      const declaresPixOut = manifest.maturity["pix-out"] !== undefined;
+      if (declaresPixOut && !hasPayment) error("tools_contradict_manifest", "agent.yaml declares pix-out maturity but tools.json has no payment meta-tool");
+      if (!declaresPixOut && hasPayment) error("tools_contradict_manifest", "tools.json has a payment meta-tool but agent.yaml declares no pix-out maturity");
+      const hasCharge = parsed.data.meta_tools.some((t) => t.effect === "charge");
+      const declaresReceivables = manifest.maturity["bolepix-receivables"] !== undefined;
+      if (declaresReceivables && !hasCharge) error("tools_contradict_manifest", "agent.yaml declares bolepix-receivables maturity but tools.json has no charge meta-tool");
+      if (!declaresReceivables && hasCharge) error("tools_contradict_manifest", "tools.json has a charge meta-tool but agent.yaml declares no bolepix-receivables maturity");
+    }
+  }
+
+  // guardrails.json
+  const guardrailsPath = loaded.resolvePath(manifest.guardrails);
+  if (!existsSync(guardrailsPath)) error("guardrails_missing", `${manifest.guardrails} does not exist`);
+  else {
+    const parsed = GuardrailsSchema.safeParse(JSON.parse(readFileSync(guardrailsPath, "utf8")));
+    if (!parsed.success) error("guardrails_invalid", parsed.error.message);
+    else {
+      if (parsed.data.approval !== manifest.default_approval) {
+        error("guardrails_contradict_manifest", `guardrails.approval is ${parsed.data.approval}; agent.yaml default_approval is ${manifest.default_approval}`);
+      }
+      if (canonicalJson(parsed.data.escalate_above ?? null) !== canonicalJson(manifest.escalate_above ?? null)) {
+        error("guardrails_contradict_manifest", "guardrails.escalate_above differs from agent.yaml escalate_above");
+      }
+    }
+  }
+
+  // channels: the declaration and what the agent ships, checked BOTH ways.
+  //
+  // A channel is the runner's, but the conversations are the agent's, so
+  // `channels: [terminal, whatsapp]` is a claim about files. Declaring
+  // whatsapp without shipping a conversation gives a reader a channel that
+  // cannot be driven; shipping one without declaring it hides a surface the
+  // agent answers on. Both are errors, and a script that no longer parses is
+  // one too, because the simulator and this check read the same schema.
+  if (!manifest.channels.includes("terminal")) {
+    error("channels_terminal_missing", "agent.yaml must declare the terminal channel: `npm start` opens it and it needs no account");
+  }
+  // `templates.json` is the one file in there that is NOT a conversation: it
+  // is the local registry of the templates the agent declares it sends, which
+  // is what makes "this name was never registered here" a refusal the channel
+  // can make instead of a 400 from Meta. A conversation therefore cannot be
+  // called `templates`, and this is the only place that says so.
+  const whatsappDir = join(agentDir, "channels", "whatsapp");
+  const scripts = existsSync(whatsappDir) ? readdirSync(whatsappDir).filter((f) => f.endsWith(".json") && f !== TEMPLATE_REGISTRY_FILE).sort() : [];
+  if (manifest.channels.includes("whatsapp") && scripts.length === 0) {
+    error("channels_not_shipped", "agent.yaml declares the whatsapp channel but channels/whatsapp/ ships no conversation for the simulator to drive");
+  }
+  if (!manifest.channels.includes("whatsapp") && scripts.length > 0) {
+    error("channels_undeclared", `channels/whatsapp/ ships ${scripts.length} conversation(s) but agent.yaml does not declare the whatsapp channel`);
+  }
+  for (const file of scripts) {
+    const parsed = ConversationScriptSchema.safeParse(JSON.parse(readFileSync(join(whatsappDir, file), "utf8")));
+    if (!parsed.success) error("channels_script_invalid", `channels/whatsapp/${file}: ${parsed.error.message}`);
+    else if (parsed.data.name !== file.replace(/\.json$/, "")) error("channels_script_invalid", `channels/whatsapp/${file} declares name ${parsed.data.name}`);
+  }
+  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
+  if (existsSync(registryPath)) {
+    const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
+    if (!parsed.success) error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${parsed.error.message}`);
+    else {
+      // A body with no placeholder takes no variables, and one with `{{3}}`
+      // and no `{{2}}` cannot be filled: Meta numbers them from 1 without
+      // gaps, and a send that skips one is a 132000 nobody sees until the
+      // first real message goes out.
+      for (const template of parsed.data.templates) {
+        const arity = templateArity(template.body);
+        for (let n = 1; n <= arity; n += 1) {
+          if (!new RegExp(`\\{\\{\\s*${n}\\s*\\}\\}`).test(template.body)) {
+            error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${template.name} uses {{${arity}}} but never {{${n}}}; Meta numbers variables from 1 with no gaps`);
+          }
+        }
+      }
+    }
+  }
+
+  // mandate.example.json
+  const mandatePath = loaded.resolvePath(manifest.mandate_schema);
+  if (!existsSync(mandatePath)) error("mandate_missing", `${manifest.mandate_schema} does not exist`);
+  else {
+    const parsed = MandateSchema.safeParse(JSON.parse(readFileSync(mandatePath, "utf8")));
+    if (!parsed.success) error("mandate_invalid", parsed.error.message);
+    else if (parsed.data.agent_id !== manifest.name) error("mandate_contradicts_manifest", `mandate.example.json agent_id is ${parsed.data.agent_id}; agent.yaml name is ${manifest.name}`);
+  }
+
+  // SYSTEM_PROMPT.md: must exist, must name the agent, must not name a tool tools.json does not have, must not promise third-party verification.
+  const promptPath = join(agentDir, "SYSTEM_PROMPT.md");
+  if (!existsSync(promptPath)) error("prompt_missing", "SYSTEM_PROMPT.md does not exist");
+  else {
+    const prompt = readFileSync(promptPath, "utf8");
+    if (!prompt.includes(manifest.name)) error("prompt_contradicts_manifest", `SYSTEM_PROMPT.md never names ${manifest.name}`);
+    for (const named of prompt.match(/\bcodespar_[a-z_]+\b/g) ?? []) {
+      if (!toolNames.includes(named)) error("prompt_contradicts_tools", `SYSTEM_PROMPT.md names ${named}, which tools.json does not list`);
+    }
+    for (const mode of ["human", "mandate"] as const) {
+      if (prompt.includes(`approval: ${mode}`) && !manifest.approval.includes(mode)) error("prompt_contradicts_manifest", `SYSTEM_PROMPT.md mentions approval: ${mode}, which agent.yaml does not support`);
+    }
+  }
+
+  // AGENTS.md and CLAUDE.md identical.
+  const agentsMd = join(agentDir, "AGENTS.md");
+  const claudeMd = join(agentDir, "CLAUDE.md");
+  if (!existsSync(agentsMd)) error("agents_md_missing", "AGENTS.md does not exist");
+  if (!existsSync(claudeMd)) error("claude_md_missing", "CLAUDE.md does not exist");
+  if (existsSync(agentsMd) && existsSync(claudeMd) && readFileSync(agentsMd, "utf8") !== readFileSync(claudeMd, "utf8")) {
+    error("agents_md_diverges", "AGENTS.md and CLAUDE.md differ");
+  }
+  if (loaded.resolvePath(manifest.agents_md) !== agentsMd) error("manifest_agents_md", `agent.yaml agents_md must point at ./AGENTS.md`);
+
+  // Directories and the eval config.
+  for (const [field, rel] of [["scenarios", manifest.scenarios], ["evals", manifest.evals]] as const) {
+    if (!existsSync(loaded.resolvePath(rel))) error(`${field}_missing`, `${rel} does not exist`);
+  }
+  const evalPath = join(loaded.resolvePath(manifest.evals), "eval.yaml");
+  if (!existsSync(evalPath)) error("eval_missing", "evals/eval.yaml does not exist");
+  else {
+    const evalDoc = parseYaml(readFileSync(evalPath, "utf8")) as Record<string, unknown> | null;
+    if (evalDoc?.["extends"] !== "../agent.yaml") error("eval_extends", 'evals/eval.yaml must start with `extends: ../agent.yaml`');
+    for (const key of Object.keys(evalDoc ?? {})) {
+      if (key !== "extends" && key in ManifestSchema.innerType().shape) error("eval_redeclares_manifest", `evals/eval.yaml redeclares \`${key}\`; only cases and metrics belong there`);
+    }
+  }
+
+  // Wording the docs must not carry UNQUALIFIED (section 6).
+  //
+  // Until ent#1633 the phrase was forbidden outright, because nothing in the
+  // product supported it. A receipt sealed since then carries an Ed25519
+  // signature over `codespar-receipt:v1:<id>:<chain>` that anybody can check
+  // against the published key set, so the claim is now true — of that, and of
+  // nothing else here. Every receipt sealed BEFORE the change carries no such
+  // signature and never will, and the approval artifact is still HMAC with a
+  // local development key.
+  //
+  // So the rule is no longer "never write it". It is two conditions, and an
+  // agent has to meet both. The agent must actually MINT a receipt that
+  // carries the seal — only a payment does, and `maturity` is where the agent
+  // says so — and the doc must NAME the mechanism, which is the word that
+  // tells a reader which of the two claims is being made.
+  const verificationMaturity = manifest.maturity["receipt-verification"];
+  const sealsVerifiableReceipts = hasPayment && verificationMaturity !== undefined && verificationMaturity !== "blocked";
+  for (const file of ["README.md", "runbook.md", "SYSTEM_PROMPT.md"]) {
+    const path = join(agentDir, file);
+    if (!existsSync(path)) {
+      if (file !== "SYSTEM_PROMPT.md") error("doc_missing", `${file} does not exist`);
+      continue;
+    }
+    const text = readFileSync(path, "utf8").toLowerCase();
+    const claims = text.includes("verificável por terceiro") || text.includes("verifiable by a third party") || text.includes("third-party verifiable");
+    if (!claims) continue;
+    if (!sealsVerifiableReceipts) {
+      error("doc_overclaims", `${file} claims third-party verifiability, and this agent seals nothing that carries it: only a payment receipt gets an Ed25519 signature, and agent.yaml declares receipt-verification as \`${verificationMaturity ?? "absent"}\``);
+    } else if (!text.includes("ed25519")) {
+      error("doc_overclaims", `${file} claims third-party verifiability without naming Ed25519; the receipt's asymmetric seal is the only thing here a third party can check, and receipts sealed before it — and the approval artifact — are HMAC`);
+    }
+  }
+
+  const envExample = join(agentDir, ".env.example");
+  if (!existsSync(envExample)) error("env_example_missing", ".env.example does not exist");
+  else {
+    const keys = readFileSync(envExample, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"))
+      .map((l) => l.split("=")[0]);
+    const extra = keys.filter((k) => k !== "CODESPAR_API_KEY" && k !== "ANTHROPIC_API_KEY");
+    if (extra.length) error("env_example_extra", `.env.example declares more than the two keys: ${extra.join(", ")}`);
+    if (!keys.includes("CODESPAR_API_KEY") || !keys.includes("ANTHROPIC_API_KEY")) error("env_example_incomplete", ".env.example must declare CODESPAR_API_KEY and ANTHROPIC_API_KEY");
+  }
+
+  // `receipt-verification` used to be a warning at `live`, because Ed25519 did
+  // not exist. It does (ent#1633), so what is left to check is the coherence
+  // the other maturity rules check: only a PAYMENT seals a receipt. A paid
+  // charge is reported by the API with no chain and no signature, so an agent
+  // that issues receivables and declares this capability beyond `blocked` is
+  // claiming a verification its records cannot carry.
+  if (verificationMaturity !== undefined && verificationMaturity !== "blocked" && !hasPayment) {
+    error("maturity_overclaims", "agent.yaml declares receipt-verification beyond `blocked` and tools.json has no payment meta-tool; only a payment seals a receipt, and a paid charge carries no signature to verify");
+  }
+
+  return { ok: findings.every((f) => f.level !== "error"), agent: manifest.name, findings };
+}

package/templates/supplier-payments-agent/packages/agent-core/src/clock.ts

@@ -0,0 +1,42 @@
+/**
+ * A clock pinned to an instant the caller chose, for a run whose outcome must
+ * not depend on the hour it happens to execute at (the CI, a demo, a test).
+ * `ExecutionEngine`, the stubs, the status gate and the loop all take a
+ * `clock` dependency; this is the one the one-shot runner hands them when
+ * `--now` or `CODESPAR_AGENT_NOW` is set. The scenario runner freezes its own
+ * clock the same way.
+ *
+ * The clock advances one second per read so no two events share an instant,
+ * which is what the scenario runner does too.
+ */
+
+export const FIXED_CLOCK_ENV = "CODESPAR_AGENT_NOW";
+
+export class InvalidFixedClockError extends Error {
+  constructor(value: string, source: string) {
+    super(`${source} must be an ISO 8601 instant (e.g. 2026-09-23T14:00:00-03:00), got "${value}"`);
+    this.name = "InvalidFixedClockError";
+  }
+}
+
+/** A clock that starts at `iso` and ticks one second per read. Throws on a value `Date` cannot parse. */
+export function fixedClock(iso: string, source = "--now"): () => Date {
+  const start = new Date(iso);
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(iso.trim()) || Number.isNaN(start.getTime())) throw new InvalidFixedClockError(iso, source);
+  let current = start.getTime() - 1000;
+  return () => {
+    current += 1000;
+    return new Date(current);
+  };
+}
+
+/**
+ * The clock a command runs with: the `--now` flag, else `CODESPAR_AGENT_NOW`
+ * from the environment, else `undefined` (the wall clock, the caller's default).
+ */
+export function resolveFixedClock(flag: string | undefined, env: NodeJS.ProcessEnv = process.env): (() => Date) | undefined {
+  if (flag !== undefined) return fixedClock(flag, "--now");
+  const fromEnv = env[FIXED_CLOCK_ENV];
+  if (fromEnv !== undefined && fromEnv.trim() !== "") return fixedClock(fromEnv, FIXED_CLOCK_ENV);
+  return undefined;
+}