@codespar/cli 0.14.1 → 0.17.0

package/templates/bills-agent/packages/agent-runtime/src/commands/poll.ts

@@ -0,0 +1,144 @@
+/**
+ * `codespar-agent poll [--channel terminal|whatsapp] [--wait <seconds>] [--simulate-payer] [--json]`:
+ * keeps looking at every receivable still waiting for its payer until it
+ * closes or the wait runs out. This is the loop-closer for a run that has no
+ * webhook URL; `codespar-agent webhook` is the other. Presents an instrument
+ * not yet shown, tells the payer the outcome once, fetches the paid record.
+ *
+ * `--channel` is on THIS command rather than in a second one, and the reason
+ * is that only one thing differs between the two: where the outcome message
+ * goes, and which carriers that place allows. The looking, the once-only
+ * presentation, the sandbox payer, the receipts and the terminal states are
+ * one loop — `pollUntilClosed` — and a second command would have meant a
+ * second copy of it, which is exactly how a channel ends up closing a cycle
+ * differently from the terminal.
+ */
+import { stderr, stdout } from "node:process";
+import { join } from "node:path";
+import { loadManifest, resolveFixedClock, type ChannelName } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import { setup } from "../setup.js";
+import { announceOutcome, waitForPayer } from "../terminal.js";
+import { pollWhatsApp } from "./poll-whatsapp.js";
+import type { WhatsAppBackendName } from "../channels/whatsapp/open.js";
+
+const USAGE = `codespar-agent poll [options]
+  --channel terminal|whatsapp   where the outcome is told. Default terminal.
+  --conversation <name>         which channels/whatsapp/<name>.json to come back to (--channel whatsapp)
+  --backend simulator|cloud-api default simulator, the local emulator (--channel whatsapp)
+  --wait <seconds>              how long to keep looking
+  --simulate-payer              let the sandbox payer act once the receivable is payable
+  --payer pays|expires|never    what the fixture payer does when it acts (stub rail only)
+  --now <ISO 8601>              pin the run's clock; env CODESPAR_AGENT_NOW is the same thing
+  --json                        machine output on stdout, everything else on stderr`;
+
+interface Args {
+  channel: ChannelName;
+  conversation?: string;
+  backend?: WhatsAppBackendName;
+  wait?: number;
+  simulatePayer: boolean;
+  payer?: "pays" | "expires" | "never";
+  now?: string;
+  json: boolean;
+}
+
+export function parsePollArgs(argv: string[]): Args {
+  const args: Args = { channel: "terminal", simulatePayer: false, json: 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 === "--json") args.json = true;
+    else if (a === "--simulate-payer") args.simulatePayer = true;
+    else if (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 (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 === "--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 === "--conversation") args.conversation = next();
+    else if (a === "--now") args.now = next();
+    else throw new Error(`unknown argument ${a}`);
+  }
+  if (args.channel !== "whatsapp" && (args.backend !== undefined || args.conversation !== undefined)) {
+    throw new Error("--backend and --conversation belong to --channel whatsapp");
+  }
+  return args;
+}
+
+export async function poll(agent: Agent, argv: string[]): Promise<number> {
+  const say = (l: string) => stderr.write(l + "\n");
+  let args: Args;
+  let now: (() => Date) | undefined;
+  try {
+    args = parsePollArgs(argv);
+    now = resolveFixedClock(args.now, process.env);
+  } catch (err) {
+    say(`${err instanceof Error ? err.message : String(err)}\n${USAGE}`);
+    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;
+  }
+
+  const s = setup(agent, { say, runId: `run_poll_${Date.now().toString(36)}`, ...(now ? { now } : {}) });
+  // The same flag `start` has, and it means more here: a receivable nobody
+  // paid reaches its due date BETWEEN two runs, never inside one, so "what
+  // happens when it expires" is a question only a poll can be asked.
+  if (args.payer) s.payer?.behave(args.payer);
+  try {
+    if (args.channel === "whatsapp") {
+      return await pollWhatsApp({
+        agent,
+        setup: s,
+        conversation: args.conversation,
+        backend: args.backend ?? "simulator",
+        json: args.json,
+        waitSeconds: args.wait,
+        simulatePayer: args.simulatePayer,
+        ...(args.payer ? { payer: args.payer } : {}),
+        now: now ?? (() => new Date()),
+        say,
+      });
+    }
+    // `behave` only changes the default for receivables the rail has not
+    // looked at, and by now it has looked at these; `decideFor` is what
+    // rewrites the fate of one that already exists.
+    if (args.payer) {
+      for (const open of s.engine.list({ state: "executing" })) {
+        for (const outcome of open.outcomes) if (outcome.status === "accepted") s.payer?.decideFor?.(outcome.attempt_id, args.payer);
+      }
+    }
+    const tell = (l: string) => void (args.json ? stderr : stdout).write(l + "\n");
+    const results = [];
+    for (const open of s.engine.list({ state: "executing" })) {
+      if (open.reason !== "awaiting_settlement") continue;
+      const r = await waitForPayer(open.id, { setup: s, approver: { id: s.kit.labels.defaultUser, channel: "terminal" }, say, tell, waitSeconds: args.wait, simulatePayer: args.simulatePayer });
+      announceOutcome(r.execution, s, tell);
+      if (r.execution.state !== "executing") await s.engine.collectReceipts(r.execution.id);
+      results.push({ id: r.execution.id, state: r.execution.state, reason: r.execution.reason ?? null, rounds: r.rounds, seconds: r.seconds, timed_out: r.timed_out });
+      say(`${r.execution.id}: ${r.execution.state}${r.execution.reason ? ` (${r.execution.reason})` : ""} after ${r.rounds} look(s), ${r.seconds}s`);
+    }
+    if (args.json) stdout.write(JSON.stringify({ polled: results }) + "\n");
+    else if (!results.length) say("nothing waiting for a payer");
+    return results.some((r) => r.timed_out) ? 3 : 0;
+  } finally {
+    s.close();
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/commands/reconcile.ts

@@ -0,0 +1,42 @@
+/**
+ * `codespar-agent reconcile [--json]`: compares local state with the rail.
+ * Names executions without an outcome, attempts the rail never saw, sealed
+ * outcomes the rail holds that the bundle does not. Read-only unless an
+ * execution is in `executing`, which it closes from what the rail says.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { stderr, stdout } from "node:process";
+import type { Agent } from "../agent.js";
+import { runsDir, setup } from "../setup.js";
+
+export async function reconcile(agent: Agent, argv: string[]): Promise<number> {
+  const json = argv.includes("--json");
+  const awaitsPayer = agent.settlement === "await-payer";
+  const say = (l: string) => stderr.write(l + "\n");
+  const s = setup(agent, { say, runId: `run_reconcile_${Date.now().toString(36)}` });
+  try {
+    const findings: Array<{ execution_id: string; kind: string; detail: string }> = [];
+    for (const e of s.engine.list()) {
+      if (e.state === "executing") {
+        const closed = await s.engine.reconcile(e.id);
+        const kind = closed.state === "executing" ? (awaitsPayer && closed.reason === "awaiting_settlement" ? "awaiting_payer" : "still_uncertain") : "closed_from_rail";
+        findings.push({ execution_id: e.id, kind, detail: `executing -> ${closed.state}${awaitsPayer && closed.detail ? ` (${closed.detail})` : ""}` });
+        continue;
+      }
+      for (const o of e.outcomes) {
+        if (o.receipt_id && !existsSync(join(runsDir(agent), e.run_id, "receipts", `${o.receipt_id}.json`))) {
+          findings.push({ execution_id: e.id, kind: s.kit.labels.missingReceiptKind, detail: s.kit.labels.missingReceiptDetail(o.receipt_id, e.run_id) });
+        }
+      }
+      const outbox = s.store.getOutbox(e.idempotency_key);
+      if (e.state === "settled" && outbox?.status !== "done") findings.push({ execution_id: e.id, kind: "outbox_mismatch", detail: `settled but outbox is ${outbox?.status ?? "absent"}` });
+    }
+    for (const f of findings) say(`${f.kind} ${f.execution_id}: ${f.detail}`);
+    if (json) stdout.write(JSON.stringify({ executions: s.engine.list().length, findings }) + "\n");
+    else say(findings.length ? `${findings.length} finding(s)` : "local state and rail agree");
+    return 0;
+  } finally {
+    s.close();
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/commands/rerun.ts

@@ -0,0 +1,86 @@
+/**
+ * `codespar-agent rerun <run-id> [--json]`: replays a recorded run against
+ * the deterministic provider and the stub rail, with no network, in a fresh
+ * state, and compares the sequence of states with the original bundle. The
+ * model's outputs are the recording; every decision of the core is recomputed.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stderr, stdout } from "node:process";
+import { ProofBundle, type ApprovalMode, type Execution } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import { runsDir, setup } from "../setup.js";
+import { handleExecution } from "../terminal.js";
+
+export async function rerun(agent: Agent, argv: string[]): Promise<number> {
+  const json = argv.includes("--json");
+  const runId = argv.find((a) => !a.startsWith("--"));
+  const say = (l: string) => stderr.write(l + "\n");
+  if (!runId) {
+    say("usage: npm run rerun <run-id> [--json]");
+    return 2;
+  }
+  const original = ProofBundle.open(runsDir(agent), runId);
+  if (!original) {
+    say(`no bundle at runs/${runId}`);
+    return 1;
+  }
+  const meta = original.readMeta() ?? {};
+  const mode = (meta["mode"] as ApprovalMode | undefined) ?? "human";
+  const events = original.readEvents();
+  const originalTrail = events.filter((e) => e["type"] === "execution.transition").map((e) => (e["payload"] as { to: string }).to);
+  const originalDecisions = events.filter((e) => e["type"] === "approval.created").map((e) => ((e["payload"] as { approver: { type: string } }).approver.type === "person" ? "approve" : "mandate"));
+  const userTurns = original.readTranscript().filter((l) => l.kind === "user").map((l) => l["text"] as string);
+  const transcriptPath = join(original.dir, "transcript.jsonl");
+  const plan = agent.kit.rerunPlan?.(events) ?? {};
+
+  const s = setup(agent, {
+    mode,
+    rail: "stub",
+    provider: "replay",
+    transcript: transcriptPath,
+    runId: `${runId}_rerun_${Date.now().toString(36)}`,
+    stateDir: mkdtempSync(join(tmpdir(), `${agent.slug}-rerun-`)),
+    stubRail: plan.stubRail,
+    say,
+  });
+  try {
+    let decisionIndex = 0;
+    const runtime = s.makeRuntime();
+    const loop = s.makeLoop(runtime, (execution: Execution) => {
+      const decision = execution.state === "awaiting_approval" ? (originalDecisions[decisionIndex++] === "approve" ? "approve" : "deny") : "none";
+      return handleExecution(execution, {
+        setup: s,
+        approver: { id: "usr_rerun", channel: "terminal" },
+        decision,
+        say,
+        ...(agent.settlement === "await-payer" ? { tell: () => undefined, simulatePayer: plan.simulatePayer ?? false } : {}),
+      });
+    });
+    for (const text of userTurns) await loop.turn(text);
+    const trail = s.store.listEvents({ run_id: s.runId }).filter((e) => e.type === "execution.transition").map((e) => (e.payload as { to: string }).to);
+    const outcomesOf = (list: Record<string, unknown>[]) => list.filter((e) => e["type"] === "rail.outcome").map((e) => (e["payload"] as { status: string }).status);
+    const originalOutcomes = outcomesOf(events);
+    const rerunOutcomes = outcomesOf(s.bundle.readEvents());
+    const sameTrail = JSON.stringify(trail) === JSON.stringify(originalTrail);
+    const same = agent.kit.rerunComparesOutcomes ? sameTrail && JSON.stringify(rerunOutcomes) === JSON.stringify(originalOutcomes) : sameTrail;
+    if (json) {
+      stdout.write(
+        JSON.stringify({
+          run_id: runId,
+          rerun_id: s.runId,
+          same_states: same,
+          original: originalTrail,
+          rerun: trail,
+          ...(agent.kit.rerunComparesOutcomes ? { original_outcomes: originalOutcomes, rerun_outcomes: rerunOutcomes } : {}),
+          bundle_dir: s.bundle.dir,
+        }) + "\n",
+      );
+    }
+    say(same ? `rerun ok: ${trail.length} transition(s), same sequence as ${runId}` : `rerun DIFFERS: original ${JSON.stringify(originalTrail)} vs rerun ${JSON.stringify(trail)}`);
+    return same ? 0 : 1;
+  } finally {
+    s.close();
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/commands/resume.ts

@@ -0,0 +1,43 @@
+/**
+ * `codespar-agent resume [--json]`: after a crash or a restart. Executions
+ * left in `executing` are reconciled against the rail (idempotent on
+ * attempt_id), never repeated; stale open ones expire.
+ */
+import { stderr, stdout } from "node:process";
+import type { Execution } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import { setup } from "../setup.js";
+
+export async function resume(agent: Agent, argv: string[]): Promise<number> {
+  const json = argv.includes("--json");
+  const awaitsPayer = agent.settlement === "await-payer";
+  const say = (l: string) => stderr.write(l + "\n");
+  const s = setup(agent, { say, runId: `run_resume_${Date.now().toString(36)}` });
+  try {
+    const closed: Execution[] = [];
+    // Only resume dispatches, and only what the outbox proves was never sent; everything else is reconciled from the rail.
+    for (const stuck of s.engine.list({ state: "executing" })) {
+      const e = await s.engine.resumePending(stuck.id);
+      closed.push(e);
+      say(e.state === "executing" ? s.kit.labels.stillExecuting(e) : `${e.id}: executing -> ${e.state}`);
+    }
+    const expired = s.engine.expireStale().map((e) => ({ id: e.id, state: e.state }));
+    for (const e of expired) say(`${e.id}: -> expired`);
+    const open = s.engine.list({ state: ["awaiting_approval", "approved"] }).map((e) => ({ id: e.id, state: e.state }));
+    for (const e of open) say(`${e.id}: still ${e.state}; decide it with npm run approve ${e.id} / npm run deny ${e.id}`);
+    if (json) {
+      const resumed = closed.map((e) => ({
+        id: e.id,
+        state: e.state,
+        ...(awaitsPayer ? { reason: e.reason ?? null } : {}),
+        detail: e.detail ?? null,
+        ...(awaitsPayer ? { charge_ids: e.outcomes.map((o) => o.transaction_id ?? null) } : {}),
+        receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+      }));
+      stdout.write(JSON.stringify({ resumed, expired, open, bundle_dir: s.bundle.dir }) + "\n");
+    } else say(closed.length || expired.length ? "resume done" : "nothing to resume");
+    return closed.some((e) => e.state === "executing" && (!awaitsPayer || e.reason !== "awaiting_settlement")) ? 3 : 0;
+  } finally {
+    s.close();
+  }
+}

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