@codespar/cli 0.14.1 → 0.17.0

package/templates/bills-agent/{agents/bills-agent → packages/agent-runtime}/src/setup.ts

@@ -1,75 +1,82 @@
 /**
- * Wires the core for this agent: manifest, guardrails, mandate, state,
- * rail, status source, signer, bundle, provider. Everything the commands
- * and the terminal channel share.
+ * Wires the core for one agent: manifest, guardrails, mandate, state, rail,
+ * status source, signer, bundle, provider. Everything the commands and the
+ * terminal channel share, whatever the agent is; what the agent brings is the
+ * rail, the tool handlers and the policy extension, through its kit.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import {
-  LocalMandateStatusStub,
   AgentLoop,
-  ApiMandateStatusSource,
-  CodeSparRail,
   ExecutionEngine,
+  LocalMandateStatusStub,
   ProofBundle,
   ReplayRuntime,
   StateStore,
-  StubRail,
-  createCodeSparClient,
-  isTestKey,
   loadGuardrails,
   loadManifest,
-  loadMandate,
   loadOrCreateLocalApprovalKey,
   loadToolsFile,
   newRunId,
-  NotATestKeyError,
+  resolveFixedClock,
   type AgentRuntime,
   type ApprovalMode,
   type Execution,
+  type Guardrails,
   type LoadedManifest,
   type Mandate,
   type MandateStatusSource,
   type PaymentRail,
+  type StubChargeRailOptions,
   type StubRailOptions,
   type ToolHandler,
 } from "@codespar/agent-core";
 import { AnthropicRuntime } from "@codespar/agent-core/providers/anthropic";
 import type { ApiClient } from "@codespar/sdk";
-import { codesparLedger, codesparPay, listBills } from "./modules/pix-out.js";
-import { loadLocalMandate } from "./modules/embedded-consent.js";
+import { envName, type Agent } from "./agent.js";
+import type { AgentKit, RailKind, SandboxPayer, Settlement } from "./kit.js";
 
-export const AGENT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-export const STATE_DIR = join(AGENT_DIR, ".codespar");
-export const RUNS_DIR = join(AGENT_DIR, "runs");
-export const MANDATE_PATH = join(STATE_DIR, "mandate.json");
+/** The `.env.example` placeholder counts as no key: a copied example must replay, not call Anthropic with a fake key. */
+export const ANTHROPIC_KEY_PLACEHOLDER = "sk-ant-your_key_here";
+export const CODESPAR_KEY_PLACEHOLDER = "csk_test_your_key_here";
 
-/** The runs folder in use: the agent's own, or the scratch one the restart test points at. */
-export function runsDir(env: NodeJS.ProcessEnv = process.env): string {
-  return env["BILLS_RUNS_DIR"] ?? RUNS_DIR;
+export type ProviderKind = "anthropic" | "replay";
+
+export function stateDirOf(agent: Agent): string {
+  return join(agent.dir, ".codespar");
 }
 
-export type RailKind = "stub" | "api";
+export function mandatePathOf(agent: Agent): string {
+  return join(stateDirOf(agent), "mandate.json");
+}
+
+/** The runs folder in use: the agent's own, or the scratch one the restart test points at. */
+export function runsDir(agent: Agent, env: NodeJS.ProcessEnv = process.env): string {
+  return env[envName(agent, "RUNS_DIR")] ?? join(agent.dir, "runs");
+}
 
 export interface SetupOptions {
   mode?: ApprovalMode | undefined;
   rail?: RailKind | undefined;
-  provider?: "anthropic" | "replay" | undefined;
+  provider?: ProviderKind | undefined;
   transcript?: string | undefined;
   runId?: string | undefined;
   runsDir?: string | undefined;
   stateDir?: string | undefined;
   now?: (() => Date) | undefined;
-  stubRail?: StubRailOptions | undefined;
-  /** Use this mandate instead of the local or example one (scenarios). */
+  stubRail?: StubRailOptions | StubChargeRailOptions | undefined;
+  /** Use this mandate instead of the local or the example one (scenarios, tests). */
   mandate?: Mandate | undefined;
   env?: NodeJS.ProcessEnv;
   say?: ((line: string) => void) | undefined;
 }
 
 export interface Setup {
+  agent: Agent;
+  kit: AgentKit;
+  settlement: Settlement;
   manifest: LoadedManifest;
+  guardrails: Guardrails;
   mode: ApprovalMode;
   mandate: Mandate;
   store: StateStore;
@@ -78,6 +85,10 @@ export interface Setup {
   railKind: RailKind;
   api: ApiClient | undefined;
   status: MandateStatusSource;
+  /** `await-payer` agents only: who plays the counterparty in the sandbox. */
+  payer: SandboxPayer | undefined;
+  /** Milliseconds between two looks at an issued receivable: 0 on the stub. */
+  pollIntervalMs: number;
   bundle: ProofBundle;
   runId: string;
   engine: ExecutionEngine;
@@ -89,7 +100,7 @@ export interface Setup {
   close(): void;
 }
 
-export function readDotEnv(agentDir = AGENT_DIR): void {
+export function readDotEnv(agentDir: string): void {
   const path = join(agentDir, ".env");
   if (!existsSync(path)) return;
   for (const line of readFileSync(path, "utf8").split("\n")) {
@@ -100,58 +111,62 @@ export function readDotEnv(agentDir = AGENT_DIR): void {
   }
 }
 
+export function resolveProvider(env: NodeJS.ProcessEnv, requested: ProviderKind | undefined): ProviderKind {
+  if (requested) return requested;
+  const key = env["ANTHROPIC_API_KEY"]?.trim();
+  return key && key !== ANTHROPIC_KEY_PLACEHOLDER ? "anthropic" : "replay";
+}
+
 export function resolveRailKind(env: NodeJS.ProcessEnv, requested: RailKind | undefined): RailKind {
   if (requested) return requested;
   const key = env["CODESPAR_API_KEY"];
-  if (!key || key === "csk_test_your_key_here") return "stub";
+  if (!key || key === CODESPAR_KEY_PLACEHOLDER) return "stub";
   return "api";
 }
 
-export function setup(options: SetupOptions = {}): Setup {
+export function setup(agent: Agent, options: SetupOptions = {}): Setup {
   const env = options.env ?? process.env;
   const say = options.say ?? ((line: string) => process.stderr.write(line + "\n"));
-  const manifest = loadManifest(join(AGENT_DIR, "agent.yaml"));
+  // `--now` on the one-shot, or CODESPAR_AGENT_NOW for every command: the clock the engine, the stubs, the gate and the loop read (#16).
+  const now = options.now ?? resolveFixedClock(undefined, env);
+  const manifest = loadManifest(join(agent.dir, "agent.yaml"));
   const guardrails = loadGuardrails(manifest.resolvePath(manifest.manifest.guardrails));
   const tools = loadToolsFile(manifest.resolvePath(manifest.manifest.tools));
-  const system = readFileSync(join(AGENT_DIR, "SYSTEM_PROMPT.md"), "utf8");
+  const system = readFileSync(join(agent.dir, "SYSTEM_PROMPT.md"), "utf8");
   const mode: ApprovalMode = options.mode ?? manifest.manifest.default_approval;
   if (!manifest.manifest.approval.includes(mode)) throw new Error(`agent.yaml does not support approval: ${mode}`);
 
-  // BILLS_STATE_DIR / BILLS_RUNS_DIR exist for the restart test, which drives a child process over a scratch state.
-  const stateDir = options.stateDir ?? env["BILLS_STATE_DIR"] ?? STATE_DIR;
-  const runs = options.runsDir ?? runsDir(env);
+  // <PREFIX>_STATE_DIR / <PREFIX>_RUNS_DIR exist for the restart test, which drives a child process over a scratch state.
+  const stateDir = options.stateDir ?? env[envName(agent, "STATE_DIR")] ?? stateDirOf(agent);
+  const runs = options.runsDir ?? runsDir(agent, env);
   const store = new StateStore(join(stateDir, "state.db"));
-  const gate = new LocalMandateStatusStub(store, options.now);
+  const gate = new LocalMandateStatusStub(store, now);
   const signer = loadOrCreateLocalApprovalKey(stateDir);
 
   const railKind = resolveRailKind(env, options.rail);
-  let api: ApiClient | undefined;
-  let rail: PaymentRail;
-  let status: MandateStatusSource = gate;
-  let mandate: Mandate;
-  if (railKind === "api") {
-    if (!isTestKey(env["CODESPAR_API_KEY"])) throw new NotATestKeyError();
-    api = createCodeSparClient({ apiKey: env["CODESPAR_API_KEY"], baseUrl: env["CODESPAR_API_URL"], projectId: env["CODESPAR_PROJECT_ID"] });
-    const local = options.mandate ?? loadLocalMandate(MANDATE_PATH);
-    if (!local) throw new NoMandateError();
-    mandate = local;
-    rail = new CodeSparRail(api, { canonical: mandate.canonical, signature: mandate.signature });
-    // Section 4.7 against the real status: the local stub answers only runs without a key.
-    status = new ApiMandateStatusSource(api, options.now);
-  } else {
-    // BILLS_KILL_AFTER_DISPATCH=1 simulates a crash right after the rail accepted the attempt and before the outcome was recorded.
-    const killAfterDispatch = env["BILLS_KILL_AFTER_DISPATCH"] === "1" ? { afterDispatch: () => process.exit(137) } : {};
-    // BILLS_STUB_REFUSE=<payee,payee>: the stub rail refuses these payees, to drive a partial failure from a test process.
-    const refuse = env["BILLS_STUB_REFUSE"] ? { refusePayees: env["BILLS_STUB_REFUSE"].split(",").map((p) => p.trim()).filter(Boolean) } : {};
-    rail = new StubRail(store, { ...(options.now ? { clock: options.now } : {}), ...killAfterDispatch, ...refuse, ...(options.stubRail ?? {}) });
-    mandate = options.mandate ?? loadMandate(manifest.resolvePath(manifest.manifest.mandate_schema));
-  }
+  const built = agent.kit.buildRail({
+    kind: railKind,
+    env,
+    agentDir: agent.dir,
+    stateDir,
+    manifest,
+    store,
+    gate,
+    now,
+    mandate: options.mandate,
+    stubRail: options.stubRail,
+    envVar: (name) => env[envName(agent, name)],
+  });
+  const { rail, mandate } = built;
+  const status = built.status ?? gate;
 
   const runId = options.runId ?? newRunId(mode);
   const bundle = new ProofBundle(runs, runId);
   bundle.mandateSnapshot(mandate);
-  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, started_at: (options.now ?? (() => new Date()))().toISOString() });
+  // Section 11: mode, rail and mandate id. The VERSION rides with the id, so a reader knows which signing of the mandate authorised the run without opening the snapshot.
+  bundle.meta({ run_id: runId, agent: `${manifest.manifest.name}@${manifest.manifest.version}`, mode, rail: railKind, mandate_id: mandate.id, mandate_version: mandate.version, started_at: (now ?? (() => new Date()))().toISOString() });
 
+  const policyExtension = agent.kit.policyExtension?.({ agentDir: agent.dir, manifest, guardrails });
   const engine = new ExecutionEngine({
     store,
     rail,
@@ -164,44 +179,51 @@ export function setup(options: SetupOptions = {}): Setup {
     mode,
     runId,
     onBehalfOf: mandate.consumer_id,
-    ...(options.now ? { clock: options.now } : {}),
+    ...(policyExtension ? { policyExtension } : {}),
+    ...(now ? { clock: now } : {}),
   });
 
-  const handlers: Record<string, ToolHandler> = { codespar_pay: codesparPay, codespar_ledger: codesparLedger, list_bills: listBills };
-
   const makeRuntime = (): AgentRuntime => {
-    const provider = options.provider ?? (env["ANTHROPIC_API_KEY"] && env["ANTHROPIC_API_KEY"] !== "sk-ant-your_key_here" ? "anthropic" : "replay");
+    const provider = resolveProvider(env, options.provider);
     if (provider === "anthropic") return new AnthropicRuntime({ apiKey: env["ANTHROPIC_API_KEY"] });
     if (!options.transcript) throw new Error("the replay provider needs a transcript (--transcript <file> or --scenario <name>)");
     say(`[replay] no ANTHROPIC_API_KEY: replaying ${options.transcript}`);
     return ReplayRuntime.fromFile(options.transcript);
   };
 
-  return {
+  const s: Setup = {
+    agent,
+    kit: agent.kit,
+    settlement: agent.settlement,
     manifest,
+    guardrails,
     mode,
     mandate,
     store,
     gate,
     rail,
     railKind,
-    api,
+    api: built.api,
     status,
+    payer: built.payer,
+    pollIntervalMs: built.pollIntervalMs ?? 0,
     bundle,
     runId,
     engine,
     system,
-    handlers,
+    handlers: {},
     tools,
     makeRuntime,
-    makeLoop: (runtime, onExecution) => new AgentLoop({ runtime, tools, handlers, system, bundle, engine, onExecution, ...(options.now ? { clock: options.now } : {}) }),
+    makeLoop: (runtime, onExecution) => new AgentLoop({ runtime, tools, handlers: s.handlers, system, bundle, engine, onExecution, ...(now ? { clock: now } : {}) }),
     close: () => store.close(),
   };
+  s.handlers = agent.kit.handlers(s);
+  return s;
 }
 
 export class NoMandateError extends Error {
   constructor() {
-    super("no signed mandate yet: run `npm run consent` (or `npm start`, which starts the consent when a test key is present)");
+    super("no signed mandate yet: run `npm run consent -- --yes` first (or `npm start` without --input, which starts the consent when a test key is present)");
     this.name = "NoMandateError";
   }
 }

package/templates/bills-agent/packages/agent-runtime/src/terminal.ts

@@ -0,0 +1,154 @@
+/**
+ * The terminal channel: what `codespar-agent start` opens. No account, no
+ * server. It shows what the core decided, asks the person when an execution
+ * is awaiting approval, and prints where the sealed outcome landed. The
+ * words are the agent's (`kit.labels`, `kit.describeExecution`); the order
+ * of the gates is the runner's and is the same for every agent.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin, stderr, stdout } from "node:process";
+import { relative } from "node:path";
+import type { AgentRuntime, ChargeInstrument, Execution } from "@codespar/agent-core";
+import { pollUntilClosed, type PollResult } from "./poll.js";
+import type { Setup } from "./setup.js";
+
+export interface TerminalOptions {
+  setup: Setup;
+  approver: { id: string; channel: string };
+  /** Non-interactive decision for a one-shot: approve, deny, or leave it awaiting. */
+  decision?: "approve" | "deny" | "none";
+  /** `await-payer` only: seconds to wait for the payer after issuing. */
+  waitSeconds?: number | undefined;
+  /** `await-payer` only: let the sandbox payer act once the receivable is payable. */
+  simulatePayer?: boolean | undefined;
+  say?: ((line: string) => void) | undefined;
+  ask?: ((question: string) => Promise<string>) | undefined;
+  /** Where the lines for the counterparty go (the conversation); `say` is the operator's console. */
+  tell?: ((line: string) => void) | undefined;
+  /**
+   * How a payable receivable is put in front of the counterparty. Defaults to
+   * the kit's own, which writes lines to a console. A channel overrides it,
+   * because a QR on WhatsApp is an image and the copy-and-paste is its own
+   * message, and neither of those is a line of text.
+   */
+  presentInstrument?: ((execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void) => void | Promise<void>) | undefined;
+}
+
+export function describeExecution(execution: Execution, setup: Setup): string[] {
+  return setup.kit.describeExecution(execution, setup);
+}
+
+/** The one message per outcome, recorded so a duplicate event never sends it twice. */
+export function announceOutcome(execution: Execution, setup: Setup, tell: (line: string) => void): boolean {
+  return setup.kit.announceOutcome?.(execution, setup, tell) ?? false;
+}
+
+function receiptLines(execution: Execution, setup: Setup, say: (line: string) => void): void {
+  for (const outcome of execution.outcomes) {
+    if (outcome.receipt_id) say(`  ${setup.kit.labels.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+  }
+}
+
+/** Decides an `awaiting_approval` execution and runs an `approved` one. Returns the final execution of this pass. */
+export async function handleExecution(execution: Execution, options: TerminalOptions): Promise<Execution> {
+  const { setup, approver } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
+  const labels = setup.kit.labels;
+  const engine = setup.engine;
+
+  for (const line of describeExecution(execution, setup)) say(line);
+
+  let current = execution;
+  if (current.state === "awaiting_approval") {
+    let decision = options.decision;
+    if (!decision) {
+      if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
+      const ask = options.ask ?? defaultAsk;
+      const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
+      decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
+    }
+    if (decision === "approve") current = engine.approve(current.id, approver);
+    else if (decision === "deny") current = engine.deny(current.id, approver);
+    else {
+      say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
+      return current;
+    }
+    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+  }
+
+  if (current.state === "approved") {
+    current = await engine.execute(current.id);
+    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    if (setup.settlement === "immediate") {
+      receiptLines(current, setup, say);
+      if (current.state === "executing") say(labels.uncertainDispatch);
+    }
+  }
+
+  if (setup.settlement === "await-payer") {
+    if (current.state === "executing" && current.reason === "awaiting_settlement") {
+      const result = await waitForPayer(current.id, options);
+      current = result.execution;
+      say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""} apos ${result.rounds} consulta(s), ${result.seconds}s${result.timed_out ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`);
+      receiptLines(current, setup, say);
+    } else if (current.state === "executing") {
+      say(labels.uncertainDispatch);
+    }
+    announceOutcome(current, setup, tell);
+  }
+  return current;
+}
+
+export async function waitForPayer(executionId: string, options: TerminalOptions): Promise<PollResult> {
+  const { setup } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
+  const waitSeconds = options.waitSeconds ?? (setup.railKind === "api" ? 60 : 0);
+  return pollUntilClosed(setup.engine, executionId, {
+    intervalMs: setup.pollIntervalMs,
+    timeoutMs: waitSeconds * 1000,
+    payer: options.simulatePayer ? setup.payer : undefined,
+    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell),
+    onWait: (_e, round) => {
+      const line = setup.kit.labels.waitingForPayer?.(round);
+      if (setup.railKind === "api" && line !== undefined && round % 5 === 0) say(line);
+    },
+  });
+}
+
+let rl: ReturnType<typeof createInterface> | undefined;
+
+export function defaultAsk(question: string): Promise<string> {
+  rl ??= createInterface({ input: stdin, output: stderr });
+  return rl.question(question);
+}
+
+export function closeTerminal(): void {
+  rl?.close();
+  rl = undefined;
+}
+
+export async function interactive(options: TerminalOptions & { runtime: AgentRuntime }): Promise<void> {
+  const { setup } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const labels = setup.kit.labels;
+  const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, options));
+  say(`${setup.manifest.manifest.name} ${setup.manifest.manifest.version} — approval: ${setup.mode} — trilho: ${setup.railKind} — ${labels.mandateWord} ${setup.mandate.id}`);
+  say(`run ${setup.runId} — bundle em ${relative(process.cwd(), setup.bundle.dir)}`);
+  say(labels.intro);
+  for (;;) {
+    let text: string;
+    try {
+      text = await defaultAsk(labels.prompt);
+    } catch {
+      break;
+    }
+    const trimmed = text.trim();
+    if (!trimmed) continue;
+    if (["sair", "exit", "quit"].includes(trimmed.toLowerCase())) break;
+    const result = await loop.turn(trimmed);
+    stdout.write(result.reply + "\n");
+  }
+  closeTerminal();
+}

package/templates/{collections-agent/agents/collections-agent/channels/webhook/index.ts → bills-agent/packages/agent-runtime/src/webhook.ts}

@@ -1,7 +1,7 @@
 /**
  * The webhook channel: the OTHER way the cycle closes. The CodeSpar API
  * delivers `commerce.charge.*` to a trigger's URL; a terminal kit has no
- * URL the API can reach, so the default is the poll (`src/poll.ts`) and this
+ * URL the API can reach, so the default is the poll (`poll.ts`) and this
  * receiver is what a developer wires when they do have one.
  *
  * STUB, on purpose: it does not register a trigger (that is