@codespar/cli 0.14.0 → 0.16.0

package/templates/hello-agent/packages/agent-runtime/src/commands/start-whatsapp.ts

@@ -0,0 +1,131 @@
+/**
+ * `codespar-agent start --channel whatsapp`: wiring, and only wiring.
+ *
+ * It picks a backend, binds the conversation, hands the channel the rules the
+ * agent's own guardrails declare, and runs the loop — all of that through
+ * `channels/whatsapp/open.ts`, which `poll --channel whatsapp` goes through
+ * too, so the two commands cannot end up enforcing different rules. The
+ * decisions are elsewhere: the rules in `channels/rules.ts`, the session
+ * window in `channels/whatsapp/session.ts`, the gates in `terminal.ts`, which
+ * this path reuses unchanged so the two channels cannot drift on what may
+ * execute.
+ */
+import { stdout } from "node:process";
+import { relative } from "node:path";
+import type { ConversationScript } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import type { Setup } from "../setup.js";
+import { defaultAsk } from "../terminal.js";
+import { converse } from "../channels/whatsapp/run.js";
+import { buildWhatsApp, simulatedCost, type WhatsAppBackendName } from "../channels/whatsapp/open.js";
+import { EmulatorUnreachableError } from "../channels/whatsapp/emulator.js";
+
+export type { WhatsAppBackendName };
+
+export interface StartWhatsAppOptions {
+  agent: Agent;
+  setup: Setup;
+  script: ConversationScript;
+  backend: WhatsAppBackendName;
+  /** Replay the conversation's turns; otherwise the person is at the keyboard. */
+  scripted: boolean;
+  approver: { id: string; channel: string };
+  json: boolean;
+  startedAt: number;
+  say: (line: string) => void;
+  decision?: "approve" | "deny" | "none";
+  waitSeconds?: number | undefined;
+  simulatePayer?: boolean | undefined;
+  now?: (() => Date) | undefined;
+}
+
+export async function startWhatsApp(options: StartWhatsAppOptions): Promise<number> {
+  const { agent, setup: s, script, say } = options;
+  const now = options.now ?? (() => new Date());
+  const conversation = { contact: script.contact, subject: script.subject };
+
+  // A scripted conversation has nobody at a keyboard, and in `human` mode
+  // somebody has to decide. Refused rather than left waiting on a stdin that
+  // will never answer: a gate that hangs teaches nothing.
+  if (options.scripted && s.mode === "human" && !options.decision) {
+    say("--scripted has nobody at the keyboard and approval: human needs a decision: add --approve or --deny, or run --mode mandate");
+    return 2;
+  }
+
+  const built = buildWhatsApp({
+    agent,
+    setup: s,
+    conversation,
+    backend: options.backend,
+    now,
+    say,
+    bundle: s.bundle,
+    ...(options.scripted ? { script } : { ask: defaultAsk }),
+    // A run that STARTS a conversation pins the emulator's clock to its own instant.
+    ...(options.now ? { pinAt: options.now() } : {}),
+  });
+  if ("refusal" in built) {
+    for (const line of built.refusal) say(line);
+    return 1;
+  }
+  const { channel, driver, sessionKey } = built;
+
+  // The channel is opened here, which is where an emulator that is not
+  // running has to be reported: after this the run has already started.
+  try {
+    await channel.open();
+  } catch (err) {
+    if (err instanceof EmulatorUnreachableError) {
+      say(err.message);
+      return 1;
+    }
+    throw err;
+  }
+
+  const result = await converse({
+    setup: s,
+    channel,
+    approver: options.approver,
+    say,
+    ...(options.decision ? { decision: options.decision } : {}),
+    ...(options.scripted ? {} : { ask: defaultAsk }),
+    ...(options.waitSeconds !== undefined ? { waitSeconds: options.waitSeconds } : {}),
+    ...(options.simulatePayer !== undefined ? { simulatePayer: options.simulatePayer } : {}),
+  });
+
+  // What the emulator is actually for, and the one number this repo cannot
+  // compute: what the conversation would have cost under Meta's rules. Read for
+  // the console only — never asserted on, because it is their engine's answer
+  // and not a contract of ours.
+  const cost = await simulatedCost(driver, sessionKey);
+
+  const log = channel.log();
+  const refused = log.filter((l) => l.refused).map((l) => ({ rule: l.refused!.rule, detail: l.refused!.detail }));
+  const channelSummary = {
+    name: "whatsapp",
+    backend: channel.backend,
+    conversation: script.name,
+    turns: result.turns,
+    messages_in: log.filter((l) => l.direction === "in").length,
+    messages_out: log.filter((l) => l.direction === "out" && !l.refused).length,
+    refused,
+    log: relative(process.cwd(), `${s.bundle.dir}/channel.jsonl`),
+    ...(cost ? { simulated_cost: cost } : {}),
+  };
+
+  if (options.json) {
+    const payload = s.kit.oneShotPayload({
+      setup: s,
+      reply: result.replies[result.replies.length - 1] ?? "",
+      toolCalls: result.toolCalls,
+      executions: result.executions,
+      startedAt: options.startedAt,
+    });
+    stdout.write(JSON.stringify({ ...payload, channel: channelSummary }) + "\n");
+  } else {
+    say(`conversa em ${channelSummary.log} — ${channelSummary.messages_in} recebida(s), ${channelSummary.messages_out} enviada(s)${refused.length ? `, ${refused.length} recusada(s)` : ""}`);
+    if (cost) say(`custo simulado desta conversa nas regras da Meta: ${cost.total.toFixed(4)} ${cost.currency} (conta do emulador, nao nossa)`);
+  }
+
+  return result.executions.some((e) => e.state === "executing") ? 3 : 0;
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/start.ts

@@ -0,0 +1,245 @@
+/**
+ * `codespar-agent start`                              interactive terminal
+ * `codespar-agent start --input "..."`                one turn, no prompt
+ * `codespar-agent start --scenario happy-path`        a scenario pack, every mode it declares
+ * `codespar-agent start --channel whatsapp`           the conversation channel
+ *
+ * `--json` puts machine data on stdout (valid JSON, nothing else) and the
+ * human messages on stderr.
+ */
+import { stderr, stdout } from "node:process";
+import { relative, resolve } from "node:path";
+import { NotATestKeyError, isTestKey, loadManifest, resolveFixedClock, type ApprovalMode, type ChannelName } from "@codespar/agent-core";
+import { join } from "node:path";
+import type { Agent } from "../agent.js";
+import type { RailKind } from "../kit.js";
+import { resolveProvider, resolveRailKind, setup, type ProviderKind } from "../setup.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, scenariosDir } from "../scenarios.js";
+import { closeTerminal, defaultAsk, handleExecution, interactive } from "../terminal.js";
+import { resolveConversation } from "../channels/index.js";
+import { startWhatsApp, type WhatsAppBackendName } from "./start-whatsapp.js";
+
+interface Args {
+  input?: string;
+  scenario?: string;
+  mode?: ApprovalMode;
+  json: boolean;
+  decision?: "approve" | "deny";
+  provider?: ProviderKind;
+  transcript?: string;
+  rail?: RailKind;
+  user?: string;
+  wait?: number;
+  simulatePayer: boolean;
+  payer?: "pays" | "expires" | "never";
+  /** ISO 8601 instant the run is pinned to (the guardrails read it instead of the wall clock). */
+  now?: string;
+  /** Which channel the person is on. `terminal` is every agent's; `whatsapp` needs a conversation. */
+  channel: ChannelName;
+  backend?: WhatsAppBackendName;
+  conversation?: string;
+  /** Replay the conversation's turns instead of reading them from the keyboard. */
+  scripted: boolean;
+  help: boolean;
+}
+
+export function parseArgs(argv: string[], awaitsPayer: boolean): Args {
+  const args: Args = { json: false, simulatePayer: false, help: false, channel: "terminal", scripted: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    const next = () => {
+      const v = argv[i + 1];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      i += 1;
+      return v;
+    };
+    if (a === "--input") args.input = next();
+    else if (a === "--scenario") args.scenario = next();
+    else if (a === "--mode") {
+      const v = next();
+      if (v !== "human" && v !== "mandate") throw new Error("--mode must be human or mandate");
+      args.mode = v;
+    } else if (a === "--json") args.json = true;
+    else if (a === "--approve") args.decision = "approve";
+    else if (a === "--deny") args.decision = "deny";
+    else if (a === "--provider") {
+      const v = next();
+      if (v !== "anthropic" && v !== "replay") throw new Error("--provider must be anthropic or replay");
+      args.provider = v;
+    } else if (a === "--transcript") args.transcript = next();
+    else if (a === "--rail") {
+      const v = next();
+      if (v !== "stub" && v !== "api") throw new Error("--rail must be stub or api");
+      args.rail = v;
+    } else if (a === "--user") args.user = next();
+    else if (awaitsPayer && a === "--wait") {
+      const v = Number(next());
+      if (!Number.isFinite(v) || v < 0) throw new Error("--wait must be a number of seconds");
+      args.wait = v;
+    } else if (awaitsPayer && a === "--simulate-payer") args.simulatePayer = true;
+    else if (awaitsPayer && a === "--payer") {
+      const v = next();
+      if (v !== "pays" && v !== "expires" && v !== "never") throw new Error("--payer must be pays, expires or never");
+      args.payer = v;
+    } else if (a === "--now") args.now = next();
+    else if (a === "--channel") {
+      const v = next();
+      if (v !== "terminal" && v !== "whatsapp") throw new Error("--channel must be terminal or whatsapp");
+      args.channel = v;
+    } else if (a === "--backend") {
+      const v = next();
+      if (v !== "simulator" && v !== "cloud-api") throw new Error("--backend must be simulator or cloud-api");
+      args.backend = v;
+    } else if (a === "--conversation") args.conversation = next();
+    else if (a === "--scripted") args.scripted = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return args;
+}
+
+export async function start(agent: Agent, argv: string[]): Promise<number> {
+  const awaitsPayer = agent.settlement === "await-payer";
+  const usage = agent.kit.usage(loadManifest(join(agent.dir, "agent.yaml")));
+  let args: Args;
+  try {
+    args = parseArgs(argv, awaitsPayer);
+  } catch (err) {
+    stderr.write(`${err instanceof Error ? err.message : String(err)}\n${usage}\n`);
+    return 2;
+  }
+  if (args.help) {
+    stderr.write(usage + "\n");
+    return 0;
+  }
+  const say = (line: string) => stderr.write(line + "\n");
+
+  // A pinned instant makes the guardrails deterministic: the CI runs the fixture inside the declared hours whatever the hour is.
+  let now: (() => Date) | undefined;
+  try {
+    now = resolveFixedClock(args.now, process.env);
+  } catch (err) {
+    stderr.write(`${err instanceof Error ? err.message : String(err)}\n${usage}\n`);
+    return 2;
+  }
+
+  // Sandbox by construction: a live key dies here, before anything else runs.
+  const railKind = resolveRailKind(process.env, args.rail);
+  if (railKind === "api" && !isTestKey(process.env["CODESPAR_API_KEY"])) {
+    say(new NotATestKeyError().message);
+    return 1;
+  }
+
+  if (args.scenario) return runScenarioCommand(agent, args, railKind, say);
+
+  // A channel is a conversation, so the flags a one-shot and a scenario pack use have no meaning on one.
+  if (args.channel === "whatsapp" && (args.input !== undefined || args.scenario !== undefined)) {
+    say("--channel whatsapp is a conversation: it takes its turns from channels/whatsapp/, not from --input or --scenario");
+    return 2;
+  }
+  if (args.channel !== "whatsapp" && (args.backend !== undefined || args.conversation !== undefined || args.scripted)) {
+    say("--backend, --conversation and --scripted belong to --channel whatsapp");
+    return 2;
+  }
+  if (args.channel === "whatsapp" && !loadManifest(join(agent.dir, "agent.yaml")).manifest.channels.includes("whatsapp")) {
+    say(`${agent.slug} does not declare the whatsapp channel in agent.yaml`);
+    return 2;
+  }
+
+  if (agent.kit.ensureMandate) {
+    const ok = await agent.kit.ensureMandate({ agentDir: agent.dir, argv, say, railKind, oneShot: args.input !== undefined, ask: defaultAsk });
+    if (!ok) return 1;
+  }
+
+  // The first thing the person says: the `--input` of a one-shot, or the first scripted turn of a conversation.
+  let conversationScript;
+  try {
+    conversationScript = args.channel === "whatsapp" ? resolveConversation(agent, args.conversation) : undefined;
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+  const firstInput = args.input ?? (args.scripted ? conversationScript?.turns[0].text : undefined);
+
+  // No model: replay the recorded scenario whose first turn is what the person said first.
+  let transcript = args.transcript;
+  const provider = resolveProvider(process.env, args.provider);
+  if (provider === "replay" && !transcript && firstInput) {
+    const match = listScenarios(agent).map((n) => loadScenario(agent, n)).find((s) => s.turns[0].input === firstInput);
+    if (match) transcript = resolve(scenariosDir(agent), match.transcript);
+    else {
+      say(`no ANTHROPIC_API_KEY and no recorded transcript for that input. Set the key, pass --transcript, or use one of: ${listScenarios(agent).map((n) => `"${loadScenario(agent, n).turns[0].input}"`).join(", ")}`);
+      return 1;
+    }
+  }
+
+  const s = setup(agent, { mode: args.mode, rail: railKind, provider, transcript, now, say });
+  if (args.payer) s.payer?.behave(args.payer);
+  const approver = { id: args.user ?? s.kit.labels.defaultUser, channel: "terminal" };
+  const startedAt = Date.now();
+  try {
+    if (args.channel === "whatsapp") {
+      return await startWhatsApp({
+        agent,
+        setup: s,
+        script: conversationScript!,
+        backend: args.backend ?? "simulator",
+        scripted: args.scripted,
+        approver: { id: approver.id, channel: "whatsapp" },
+        json: args.json,
+        startedAt,
+        say,
+        ...(args.decision ? { decision: args.decision } : {}),
+        ...(args.wait !== undefined ? { waitSeconds: args.wait } : {}),
+        simulatePayer: args.simulatePayer,
+        now,
+      });
+    }
+    const runtime = s.makeRuntime();
+    if (!args.input) {
+      await interactive({ setup: s, approver, runtime, say, waitSeconds: args.wait, simulatePayer: args.simulatePayer });
+      return 0;
+    }
+    const loop = s.makeLoop(runtime, (execution) =>
+      handleExecution(execution, { setup: s, approver, decision: args.decision ?? "none", say, waitSeconds: args.wait, simulatePayer: args.simulatePayer, ...(args.json ? { tell: say } : {}) }),
+    );
+    const result = await loop.turn(args.input);
+    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    const payload = s.kit.oneShotPayload({ setup: s, reply: result.reply, toolCalls: result.tool_calls, executions, startedAt });
+    if (args.json) stdout.write(JSON.stringify(payload) + "\n");
+    else stdout.write(result.reply + "\n");
+    return executions.some((e) => e.state === "executing") ? 3 : 0;
+  } finally {
+    closeTerminal();
+    s.close();
+  }
+}
+
+async function runScenarioCommand(agent: Agent, args: Args, railKind: RailKind, say: (l: string) => void): Promise<number> {
+  const scenario = loadScenario(agent, args.scenario!);
+  const picksRail = agent.kit.scenarioRail === "requested";
+  const rail: RailKind = picksRail ? railKind : "stub";
+  if (picksRail && !scenario.rails.includes(rail)) {
+    say(`scenario ${scenario.name} runs on ${scenario.rails.join("/")} only (asked: ${rail})`);
+    return 2;
+  }
+  const modes = args.mode ? [args.mode] : scenario.modes;
+  const results = [];
+  for (const mode of modes) {
+    say(`== scenario ${scenario.name} — approval: ${mode}${picksRail ? ` — rail: ${rail}` : ""}`);
+    say(scenario.description);
+    const run = await runScenario(agent, scenario, {
+      mode,
+      rail,
+      say: args.json ? () => undefined : say,
+      ...(picksRail ? { tell: args.json ? () => undefined : (l: string) => void stdout.write(l + "\n") } : {}),
+      waitSeconds: args.wait,
+    });
+    const check = checkScenario(scenario, run);
+    for (const reply of run.replies) say(`agente: ${reply}`);
+    say(check.ok ? `== ok — ${agent.settlement === "await-payer" ? `${run.cycle_seconds}s — ` : ""}bundle em ${relative(process.cwd(), run.bundle_dir)}` : `== FAIL: ${check.failures.join("; ")}`);
+    results.push({ mode, ok: check.ok, failures: check.failures, run });
+  }
+  if (args.json) stdout.write(JSON.stringify({ scenario: scenario.name, ...(picksRail ? { rail } : {}), results }) + "\n");
+  return results.every((r) => r.ok) ? 0 : 1;
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/verify.ts

@@ -0,0 +1,129 @@
+/**
+ * `codespar-agent verify <receipt-file> [--json] [--keys <file>] [--url <url>]`:
+ * the wave-5 gate — someone outside verifies a receipt without access to
+ * CodeSpar.
+ *
+ * It takes a receipt JSON, fetches the public key set over plain HTTPS (or
+ * reads a copy off disk, for a machine with no network), and checks the
+ * Ed25519 signature with stock `node:crypto`. No CodeSpar key, no API key, no
+ * SDK call: the verifier holds nothing, and that is what makes the answer
+ * worth anything. It is the one command here that does NOT need an agent —
+ * `cli.ts` dispatches it before it looks for an `agent.yaml` — because the
+ * file it reads has usually been copied off the machine that produced it.
+ *
+ * `--json` follows the rule of section 14.5: machine data on stdout, valid
+ * JSON and nothing else, human sentences on stderr. The exit code is the
+ * verdict (`VERDICT_EXIT_CODES`), so a script branches on WHICH answer it got
+ * rather than on "did it fail" — an unsigned receipt is not a failure and must
+ * not exit 0 either.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stderr, stdout } from "node:process";
+import { DEFAULT_RECEIPT_KEYS_URL, VERDICT_EXIT_CODES, verifyReceipt, type KeySource, type ReceiptVerification } from "@codespar/agent-core";
+
+const USAGE = "usage: npm run verify <receipt-file> [--json] [--keys <key-set.json>] [--url <https://.../.well-known/codespar-receipt-keys.json>]";
+
+/** The fetcher the module is given. The only network in this feature, and it
+ *  lives here rather than in the core so a unit test injects its own. */
+async function fetchKeyDocument(url: string): Promise<unknown> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const response = await fetch(url, { signal: controller.signal, headers: { accept: "application/jwk-set+json, application/json" } });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return (await response.json()) as unknown;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function verify(argv: string[]): Promise<number> {
+  const say = (line: string) => stderr.write(line + "\n");
+  let json = false;
+  let keysFile: string | undefined;
+  let url: string | undefined;
+  let receiptFile: string | undefined;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === "--json") json = true;
+    else if (a === "--keys" || a === "--url") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        say(`${a} needs a value\n${USAGE}`);
+        return 2;
+      }
+      if (a === "--keys") keysFile = value;
+      else url = value;
+      i += 1;
+    } else if (a === "--help" || a === "-h") {
+      say(USAGE);
+      say(`the key set is public and needs no credential; its default is ${DEFAULT_RECEIPT_KEYS_URL}`);
+      say("--keys reads a saved copy of that document instead, so the check runs with no network at all");
+      return 0;
+    } else if (a.startsWith("-")) {
+      say(`unknown argument ${a}\n${USAGE}`);
+      return 2;
+    } else if (receiptFile === undefined) receiptFile = a;
+    else {
+      say(`verify takes one receipt file (got ${receiptFile} and ${a})\n${USAGE}`);
+      return 2;
+    }
+  }
+
+  if (!receiptFile) {
+    say(USAGE);
+    say("the receipt is the JSON the API returns from GET /v1/consumers/receipts/{id}, or a copy from a run's runs/<run-id>/receipts/");
+    return 2;
+  }
+  if (keysFile && url) {
+    say(`--keys and --url name two different key sets; pass one\n${USAGE}`);
+    return 2;
+  }
+
+  const receipt = readJson(receiptFile, say);
+  if (receipt === undefined) return 2;
+
+  let source: KeySource;
+  if (keysFile) {
+    const document = readJson(keysFile, say);
+    if (document === undefined) return 2;
+    source = { document, label: resolve(keysFile) };
+  } else {
+    source = { url: url ?? DEFAULT_RECEIPT_KEYS_URL, fetch: fetchKeyDocument };
+  }
+
+  const report = await verifyReceipt(receipt, source);
+  if (json) stdout.write(JSON.stringify(report) + "\n");
+  else stdout.write(render(report));
+  say(report.message);
+  return VERDICT_EXIT_CODES[report.verdict];
+}
+
+/** A file that is missing or is not JSON is a refusal a person can act on, never a stack trace. */
+function readJson(path: string, say: (line: string) => void): unknown {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    say(`could not read ${resolve(path)}: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (err) {
+    say(`${resolve(path)} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+}
+
+/** The terminal rendering: the verdict first, then what it is about. */
+function render(report: ReceiptVerification): string {
+  const lines = [`${report.verdict.toUpperCase()}  ${report.receipt_id ?? "(no receipt id)"}`];
+  if (report.kid) lines.push(`  key          ${report.kid}${report.key_status ? ` (${report.key_status})` : ""}`);
+  if (report.keys_from) lines.push(`  key set      ${report.keys_from}`);
+  if (report.signing_string) lines.push(`  signed       ${report.signing_string}`);
+  lines.push(`  reason       ${report.reason}`);
+  return lines.join("\n") + "\n";
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/webhook.ts

@@ -0,0 +1,39 @@
+/**
+ * `codespar-agent webhook [--port <n>] [--secret <trigger secret>]`: starts
+ * the receiving end of the webhook channel on localhost. A stub for the
+ * developer who has a URL the API can reach; the terminal's default is
+ * `codespar-agent poll`. Reads `<PREFIX>_WEBHOOK_PORT` and
+ * `<PREFIX>_TRIGGER_SECRET` when the flags are absent.
+ */
+import { stderr, stdout } from "node:process";
+import { envName, type Agent } from "../agent.js";
+import { setup } from "../setup.js";
+import { announceOutcome } from "../terminal.js";
+import { startWebhookServer } from "../webhook.js";
+
+export async function webhook(agent: Agent, argv: string[]): Promise<number> {
+  const port = Number(argv.includes("--port") ? argv[argv.indexOf("--port") + 1] : process.env[envName(agent, "WEBHOOK_PORT")] ?? "8787");
+  const secret = argv.includes("--secret") ? argv[argv.indexOf("--secret") + 1] : process.env[envName(agent, "TRIGGER_SECRET")];
+  const say = (l: string) => stderr.write(l + "\n");
+  const s = setup(agent, { say, runId: `run_webhook_${Date.now().toString(36)}` });
+  const server = startWebhookServer(
+    port,
+    {
+      engine: s.engine,
+      secret,
+      onClosed: (execution) => {
+        announceOutcome(execution, s, (l) => void stdout.write(l + "\n"));
+      },
+    },
+    say,
+  );
+  const stop = () => {
+    server.close();
+    s.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  // The receiver runs until a signal stops it.
+  return new Promise<number>(() => undefined);
+}

package/templates/hello-agent/packages/agent-runtime/src/default-kit.ts

@@ -0,0 +1,83 @@
+/**
+ * What an agent gets when it declares nothing: the stub payment rail over the
+ * example mandate, the generic console words, and no tools. A read-only agent
+ * spreads this and adds its handlers; a payer or a collector replaces the rail.
+ */
+import { StubRail, loadMandate, type Execution } from "@codespar/agent-core";
+import { relative } from "node:path";
+import type { AgentKit } from "./kit.js";
+
+export function formatMinor(minor: number): string {
+  const sign = minor < 0 ? "-" : "";
+  const abs = Math.abs(minor);
+  return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${String(abs % 100).padStart(2, "0")}`;
+}
+
+export const defaultKit: AgentKit = {
+  settlement: "immediate",
+  scenarioRail: "stub",
+  labels: {
+    defaultUser: "usr_terminal",
+    evalUser: "usr_demo_titular",
+    mandateWord: "mandato",
+    receiptWord: "recibo",
+    intro: 'Diga o que precisa. Ctrl+D ou "sair" encerra.',
+    prompt: "> ",
+    approveQuestion: "  Aprovar? [s/N] ",
+    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a operacao)",
+    missingReceiptKind: "receipt_missing_locally",
+    missingReceiptDetail: (receiptId, runId) => `receipt ${receiptId} is not in runs/${runId}/receipts`,
+    stillExecuting: (e) => `${e.id}: still executing — ${e.detail}; nothing was re-sent`,
+  },
+  usage: (manifest) => `${manifest.manifest.name}
+  npm start                              interactive terminal
+  npm start -- --input "..."             one turn (add --approve/--deny to decide, --json for machine output)
+  npm start -- --scenario <name>         run a scenario pack (see scenarios/)
+options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>  --json
+         --now <ISO 8601>  pin the run to that instant; env CODESPAR_AGENT_NOW is the same thing`,
+  buildRail: (ctx) => {
+    // A read-only agent has no rail to reach: the stub answers offline, whatever key the environment carries.
+    const killAfterDispatch = ctx.envVar("KILL_AFTER_DISPATCH") === "1" ? { afterDispatch: () => process.exit(137) } : {};
+    const refuse = ctx.envVar("STUB_REFUSE") ? { refusePayees: ctx.envVar("STUB_REFUSE")!.split(",").map((p) => p.trim()).filter(Boolean) } : {};
+    return {
+      rail: new StubRail(ctx.store, { ...(ctx.now ? { clock: ctx.now } : {}), ...killAfterDispatch, ...refuse, ...(ctx.stubRail ?? {}) }),
+      mandate: ctx.mandate ?? loadMandate(ctx.manifest.resolvePath(ctx.manifest.manifest.mandate_schema)),
+    };
+  },
+  handlers: () => ({}),
+  describeExecution: (execution, setup) => {
+    const lines: string[] = [];
+    lines.push(`  execucao ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
+    for (const item of execution.items) lines.push(`    - ${item.beneficiary}: ${formatMinor(item.amount)}${item.description ? ` — ${item.description}` : ""}`);
+    lines.push(`    total (calculado pelo core): ${formatMinor(execution.total)}`);
+    if (execution.escalation) lines.push(`    escalado por: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
+    if (execution.blocking_reasons.length) lines.push(`    bloqueado: ${execution.blocking_reasons.join(", ")} — o mandato nao autoriza; nao ha o que aprovar`);
+    if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
+    for (const outcome of execution.outcomes) {
+      if (outcome.receipt_id) lines.push(`    recibo: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+    }
+    return lines;
+  },
+  oneShotPayload: ({ setup: s, reply, toolCalls, executions }) => ({
+    run_id: s.runId,
+    agent: `${s.manifest.manifest.name}@${s.manifest.manifest.version}`,
+    mode: s.mode,
+    rail: s.railKind,
+    mandate_id: s.mandate.id,
+    actor: s.engine.agentActor,
+    reply,
+    tool_calls: toolCalls,
+    executions: executions.map((e: Execution) => ({
+      id: e.id,
+      state: e.state,
+      reason: e.reason ?? null,
+      escalation: e.escalation ?? null,
+      total_minor: e.total,
+      items: e.items.map((i) => ({ beneficiary: i.beneficiary, amount_minor: i.amount })),
+      approval_id: e.approval_id ?? null,
+      receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+    })),
+    receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
+    bundle_dir: relative(process.cwd(), s.bundle.dir),
+  }),
+};

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

@@ -0,0 +1,12 @@
+export * from "./agent.js";
+export * from "./kit.js";
+export * from "./default-kit.js";
+export * from "./setup.js";
+export * from "./terminal.js";
+export * from "./channels/index.js";
+export * from "./poll.js";
+export * from "./webhook.js";
+export * from "./scenarios.js";
+export * from "./adversarial.js";
+export * from "./inspect.js";
+export { main } from "./cli.js";