@codespar/cli 0.13.0 → 0.14.1

package/templates/bills-agent/agents/bills-agent/test/cli.test.ts

@@ -0,0 +1,177 @@
+/**
+ * The contracts that need a real process: `--json` on stdout and nothing
+ * else, the restart in `executing` followed by `resume`, and `rerun`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+
+function run(script: string, args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, ["--disable-warning=ExperimentalWarning", "--import", "tsx", script, ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+describe("npm start -- --input ... --json", () => {
+  it("prints valid JSON on stdout and nothing else; people go to stderr", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-json-"));
+    const out = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") });
+    expect(out.code).toBe(0);
+    const lines = out.stdout.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    const payload = JSON.parse(lines[0]!) as { run_id: string; mode: string; actor: { type: string }; executions: Array<{ state: string; receipt_ids: string[] }>; receipts: string[] };
+    expect(payload.mode).toBe("human");
+    expect(payload.actor.type).toBe("agent");
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+    expect(payload.receipts).toHaveLength(1);
+    expect(out.stderr).toContain("replay");
+  });
+
+  it("refuses a key outside csk_test_ before anything else", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-live-"));
+    const out = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: ["csk", "live", "0000000000"].join("_") });
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("csk_test_");
+  });
+});
+
+describe("section 10: restart in executing, then resume", () => {
+  it("one payment, one receipt, never two", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-restart-"));
+    const runsDir = join(stateDir, "runs");
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
+
+    const killed = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], { ...env, BILLS_KILL_AFTER_DISPATCH: "1" });
+    expect(killed.code).toBe(137);
+    expect(killed.stdout).toBe("");
+
+    const db = new DatabaseSync(join(stateDir, "state.db"));
+    const stuck = db.prepare("SELECT state FROM executions").all() as Array<{ state: string }>;
+    expect(stuck).toEqual([{ state: "executing" }]);
+    expect((db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(1);
+    db.close();
+
+    const resumed = run("src/commands/resume.ts", ["--json"], env);
+    expect(resumed.code).toBe(0);
+    const payload = JSON.parse(resumed.stdout.trim()) as { resumed: Array<{ state: string; receipt_ids: string[] }> };
+    expect(payload.resumed).toHaveLength(1);
+    expect(payload.resumed[0]?.state).toBe("settled");
+    expect(payload.resumed[0]?.receipt_ids).toHaveLength(1);
+
+    const db2 = new DatabaseSync(join(stateDir, "state.db"));
+    expect((db2.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(1);
+    expect((db2.prepare("SELECT COUNT(*) AS n FROM events WHERE type = 'commerce.payment.succeeded'").get() as { n: number }).n).toBe(1);
+    expect(db2.prepare("SELECT state FROM executions").all()).toEqual([{ state: "settled" }]);
+    db2.close();
+
+    const receipts = readdirSync(runsDir).flatMap((r) => (existsSync(join(runsDir, r, "receipts")) ? readdirSync(join(runsDir, r, "receipts")) : []));
+    expect(receipts).toHaveLength(1);
+
+    const again = run("src/commands/resume.ts", ["--json"], env);
+    expect(JSON.parse(again.stdout.trim())).toMatchObject({ resumed: [] });
+  });
+});
+
+describe("npm run rerun <run-id>", () => {
+  it("reproduces a recorded run without network, with the same state sequence", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-rerun-"));
+    const runsDir = join(stateDir, "runs");
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
+    const first = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], env);
+    expect(first.code).toBe(0);
+    const { run_id } = JSON.parse(first.stdout.trim()) as { run_id: string };
+    const rerun = run("src/commands/rerun.ts", [run_id, "--json"], env);
+    expect(rerun.code).toBe(0);
+    const payload = JSON.parse(rerun.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[] };
+    expect(payload.same_states).toBe(true);
+    expect(payload.original).toEqual(["awaiting_approval", "approved", "executing", "settled"]);
+    expect(readFileSync(join(runsDir, run_id, "transcript.jsonl"), "utf8")).toContain("assistant_step");
+  });
+});
+
+describe("npm run check", () => {
+  it("is green for the shipped agent and prints JSON with --json", () => {
+    const out = run("src/commands/check.ts", ["--json"], {});
+    expect(out.code).toBe(0);
+    const report = JSON.parse(out.stdout.trim()) as { ok: boolean; agent: string; findings: unknown[] };
+    expect(report).toMatchObject({ ok: true, agent: "bills-agent" });
+    expect(report.findings.filter((f) => (f as { level: string }).level === "error")).toEqual([]);
+  });
+});
+
+describe("npm run approve / deny <execution-id>", () => {
+  it("decides an execution left awaiting, produces the artifact and runs it through the last gate", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-decide-"));
+    const runsDir = join(stateDir, "runs");
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
+    const left = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], env);
+    expect(left.code).toBe(0);
+    const payload = JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string; state: string }> };
+    expect(payload.executions[0]?.state).toBe("awaiting_approval");
+    const id = payload.executions[0]!.id;
+
+    const denied = run("src/commands/deny.ts", ["nope_unknown", "--json"], env);
+    expect(denied.code).toBe(1);
+
+    const approved = run("src/commands/approve.ts", [id, "--user", "usr_titular", "--json"], env);
+    expect(approved.code).toBe(0);
+    const out = JSON.parse(approved.stdout.trim()) as { state: string; approval_id: string | null; receipt_ids: string[]; bundle_dir: string };
+    expect(out.state).toBe("settled");
+    expect(out.approval_id).toMatch(/^apr_/);
+    expect(out.receipt_ids).toHaveLength(1);
+    const artifacts = JSON.parse(readFileSync(join(AGENT_DIR, out.bundle_dir, "approval.json"), "utf8")) as Array<{ approver: { type: string; id: string } }>;
+    expect(artifacts[0]?.approver).toEqual({ type: "person", id: "usr_titular", channel: "terminal" });
+
+    const again = run("src/commands/approve.ts", [id, "--json"], env);
+    expect(again.code).toBe(1);
+    expect(again.stderr).toContain("not awaiting_approval");
+  });
+
+  it("deny leaves a terminal denied execution and sends nothing", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-deny-"));
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+    const left = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], env);
+    const id = (JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string }> }).executions[0]!.id;
+    const denied = run("src/commands/deny.ts", [id, "--json"], env);
+    expect(denied.code).toBe(0);
+    expect(JSON.parse(denied.stdout.trim())).toMatchObject({ state: "denied", reason: "denied_by_approver", receipt_ids: [] });
+    const db = new DatabaseSync(join(stateDir, "state.db"));
+    expect((db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(0);
+    db.close();
+  });
+});
+
+describe("partial failure of a multi-item execution, and rerun reproducing it", () => {
+  it("names what settled and what failed, and rerun replays the rail's refusal", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-partial-"));
+    const runsDir = join(stateDir, "runs");
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir, BILLS_STUB_REFUSE: "+5511999990001" };
+    const first = run("src/main.ts", ["--input", "libera o lote do mes", "--transcript", "evals/adversarial/false-authority.transcript.jsonl", "--approve", "--json"], env);
+    expect(first.code).toBe(0);
+    const payload = JSON.parse(first.stdout.trim()) as { run_id: string; executions: Array<{ state: string; receipt_ids: string[] }>; receipts: string[] };
+    expect(payload.executions[0]?.state).toBe("failed");
+    expect(payload.executions[0]?.receipt_ids).toHaveLength(1);
+    expect(payload.receipts).toHaveLength(1);
+    const events = readFileSync(join(runsDir, payload.run_id, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; payload: { status?: string } });
+    expect(events.filter((e) => e.type === "rail.outcome").map((e) => e.payload.status)).toEqual(["settled", "failed"]);
+
+    const rerun = run("src/commands/rerun.ts", [payload.run_id, "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir });
+    expect(rerun.code).toBe(0);
+    const r = JSON.parse(rerun.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[]; original_outcomes: string[]; rerun_outcomes: string[] };
+    expect(r.same_states).toBe(true);
+    expect(r.original).toEqual(["awaiting_approval", "approved", "executing", "failed"]);
+    expect(r.original_outcomes).toEqual(["settled", "failed"]);
+    expect(r.rerun_outcomes).toEqual(["settled", "failed"]);
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/scenarios.test.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "../src/scenarios.js";
+
+const runsDir = mkdtempSync(join(tmpdir(), "bills-runs-"));
+
+describe("section 12: scenario packs, on the replay provider", () => {
+  const required = ["happy-path", "cap-exceeded", "beneficiary-not-allowed", "prompt-injection", "escalated-above-threshold", "mandate-revoked"];
+
+  it("ships every scenario the spec asks for", () => {
+    for (const name of required) expect(listScenarios()).toContain(name);
+  });
+
+  for (const name of required) {
+    const scenario = loadScenario(name);
+    for (const mode of scenario.modes) {
+      it(`${name} [${mode}] ends in the states the pack declares`, async () => {
+        const run = await runScenario(scenario, { mode, runsDir });
+        const check = checkScenario(scenario, run);
+        expect(check.failures).toEqual([]);
+        expect(check.ok).toBe(true);
+        // Every event of the bundle carries an actor.
+        const events = readFileSync(join(run.bundle_dir, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { actor?: unknown });
+        expect(events.length).toBeGreaterThan(0);
+        for (const e of events) expect(e.actor).toBeDefined();
+        // Every receipt carries an actor and no raw payee.
+        for (const file of readdirSync(join(run.bundle_dir, "receipts"))) {
+          const receipt = JSON.parse(readFileSync(join(run.bundle_dir, "receipts", file), "utf8")) as { actor?: unknown; payment: { payee: string | null } };
+          expect(receipt.actor).toBeDefined();
+          expect(receipt.payment.payee ?? "").toContain("***");
+        }
+      });
+    }
+  }
+
+  it("happy-path: the same trail and the same receipts in human and in mandate", async () => {
+    const scenario = loadScenario("happy-path");
+    const human = await runScenario(scenario, { mode: "human", runsDir });
+    const mandate = await runScenario(scenario, { mode: "mandate", runsDir });
+    expect(human.executions.map((e) => e.trail)).toEqual(mandate.executions.map((e) => e.trail));
+    expect(normalizeReceipts(human)).toEqual(normalizeReceipts(mandate));
+    // In human, the artifact is a person's; in mandate the person still decided because the amount escalated.
+    const approvals = (run: ScenarioRun) => JSON.parse(readFileSync(join(run.bundle_dir, "approval.json"), "utf8")) as Array<{ approver: { type: string }; items_hash: string; escalation?: { trigger: string } }>;
+    expect(approvals(human)[0]?.approver.type).toBe("person");
+    expect(approvals(mandate)[0]?.approver.type).toBe("person");
+    expect(approvals(mandate)[0]?.escalation?.trigger).toBe("amount");
+    expect(approvals(human)[0]?.items_hash).toBe(approvals(mandate)[0]?.items_hash);
+  });
+
+  it("nothing reaches executing without an approval artifact carrying its items_hash", async () => {
+    for (const name of required) {
+      const scenario = loadScenario(name);
+      for (const mode of scenario.modes) {
+        const run = await runScenario(scenario, { mode, runsDir });
+        const approvalPath = join(run.bundle_dir, "approval.json");
+        const artifacts = existsSync(approvalPath) ? (JSON.parse(readFileSync(approvalPath, "utf8")) as Array<{ execution_id: string; items_hash: string }>) : [];
+        for (const e of run.executions) {
+          if (!e.trail.includes("executing")) continue;
+          expect(artifacts.some((a) => a.execution_id === e.id)).toBe(true);
+        }
+      }
+    }
+  });
+});
+
+function normalizeReceipts(run: ScenarioRun): unknown[] {
+  return readdirSync(join(run.bundle_dir, "receipts"))
+    .map((f) => JSON.parse(readFileSync(join(run.bundle_dir, "receipts", f), "utf8")) as { state: string; mandate: { id: string }; payment: { amount_minor: number; payee: string | null; sandbox: boolean } })
+    .map((r) => ({ state: r.state, mandate: r.mandate.id, amount: r.payment.amount_minor, payee: r.payment.payee, sandbox: r.payment.sandbox }))
+    .sort((a, b) => a.amount - b.amount);
+}

package/templates/bills-agent/agents/bills-agent/tools.json

@@ -0,0 +1,51 @@
+{
+  "meta_tools": [
+    {
+      "name": "codespar_pay",
+      "effect": "payment",
+      "description": "Propose one or more Pix payments to named payees of the month. This does NOT pay: it creates an execution in `drafted` that the core checks against the mandate and, depending on the approval mode, asks the person or runs. Use the payee alias from list_bills (escola, mercado, funcionaria, contas). Amounts are in BRL cents.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["pix"] },
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "payee": { "type": "string", "description": "A payee alias from list_bills. Never a raw Pix key the person typed in the chat." },
+                "amount_minor": { "type": "integer", "minimum": 1, "description": "BRL cents." },
+                "description": { "type": "string" }
+              },
+              "required": ["payee", "amount_minor"]
+            }
+          },
+          "total_minor": { "type": "integer", "description": "Optional. What you believe the total is. The core recomputes it and yours is only recorded." }
+        },
+        "required": ["action", "items"]
+      }
+    },
+    {
+      "name": "codespar_ledger",
+      "effect": "read",
+      "description": "Read the receipt of a settled payment by receipt id, or list the executions of this run with their states.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "action": { "type": "string", "enum": ["receipt", "executions"] },
+          "receipt_id": { "type": "string" }
+        },
+        "required": ["action"]
+      }
+    }
+  ],
+  "local_tools": [
+    {
+      "name": "list_bills",
+      "effect": "read",
+      "description": "The bills of the current month: payee alias, name, amount in BRL cents, due date and whether it was already paid in this mandate window. Read-only.",
+      "input_schema": { "type": "object", "properties": {} }
+    }
+  ]
+}

package/templates/bills-agent/agents/bills-agent/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts",
+    "channels/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/templates/bills-agent/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt.",
+  "license": "MIT",
+  "type": "module",
+  "workspaces": [
+    "packages/agent-core",
+    "agents/bills-agent"
+  ],
+  "scripts": {
+    "start": "npm start --workspace=agents/bills-agent --",
+    "check": "npm run check --workspaces --if-present --",
+    "test": "vitest run --pool=forks --maxWorkers=1",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p agents/bills-agent/tsconfig.json",
+    "approve": "npm run approve --workspace=agents/bills-agent --",
+    "consent": "npm run consent --workspace=agents/bills-agent --",
+    "deny": "npm run deny --workspace=agents/bills-agent --",
+    "eval": "npm run eval --workspace=agents/bills-agent --",
+    "reconcile": "npm run reconcile --workspace=agents/bills-agent --",
+    "rerun": "npm run rerun --workspace=agents/bills-agent --",
+    "resume": "npm run resume --workspace=agents/bills-agent --"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.4",
+    "tsx": "4.20.5",
+    "typescript": "5.9.2",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}

package/templates/bills-agent/packages/agent-core/README.md

@@ -0,0 +1,19 @@
+# @codespar/agent-core
+
+The primitives every CodeSpar starter-kit agent inherits (spec v5.1.1, section 4): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract and the two providers.
+
+## The state machine, and what the types do and do not prove
+
+`transition(execution, to, input)` accepts only a `to` that the table in `state-machine.ts` lists for `execution.state`. On a **narrowed** value (`Execution<"drafted">`, `Execution<"executing">`, ...) a transition outside the table is a compile error, and `test/transitions.type-test.ts` keeps that true with `@ts-expect-error` lines that `tsc` refuses to leave unused. An **un-narrowed** `Execution` (the union, which is what a row read back from SQLite is) compiles for any target; the engine narrows with casts at its call sites. So the guard that always holds is the runtime one: `transition()` throws `IllegalTransitionError` on any pair the table does not list, whatever the static type said. The type test proves the table is closed; the runtime check enforces it.
+
+## The one policy, three gates
+
+`ExecutionEngine.policy()` runs at draft, at a human's approval and again immediately before `executing`, inside the transaction that writes the outbox row. Mandate status, allowlist, per-transaction cap, the window cap (counting settled, in flight AND awaiting executions as reservations), `escalate_above` and the artifact's `items_hash` are all re-checked at the last gate. A person's approval satisfies `escalate_above` and nothing else.
+
+## Reconcile never re-dispatches
+
+An execution left in `executing` is looked up on the rail, attempt by attempt. A recorded settled or failed outcome closes it; `in_flight`, `uncertain` or unknown leaves it in `executing` with `reason: rail_uncertain` for a human. The single exception is an outbox row still `pending` (the state changed, no call was ever made): those attempts go out once, under the same ids.
+
+## Stubs
+
+`stubs/mandate-status.ts` (the section 4.7 status source for runs without a key: revocation, pause and the organization kill switch, over the local state.db) and `stubs/rail.ts` (the sandbox rail) are stand-ins for the CI, the scenarios and `rerun`, marked as such. With a test key the engine reads the mandate status from the API instead (`api/mandate-status.ts`, `GET /v1/mandates/{id}`), fail-closed: anything but `active` refuses `executing`, and a read that does not answer is `mandate_status_unavailable`, never "assume active". The approval artifact is signed with a local development key (`approval.ts`); the API does not sign approval lists.

package/templates/bills-agent/packages/agent-core/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@codespar/agent-core",
+  "version": "0.1.0",
+  "description": "The primitives every CodeSpar starter-kit agent inherits: the execution state machine, the approval artifact, the agent.yaml manifest, escalate_above, actor, local state and providers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./providers/anthropic": "./src/providers/anthropic.ts",
+    "./providers/replay": "./src/providers/replay.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --pool=forks --maxWorkers=1 --root ../.. packages/agent-core"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.128.0",
+    "@codespar/sdk": "0.16.4",
+    "yaml": "2.9.1",
+    "zod": "3.25.76"
+  }
+}

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

@@ -0,0 +1,125 @@
+/**
+ * The tool-use loop. The provider says what the model wants; this file
+ * dispatches only the tools `tools.json` names, records every step in the
+ * transcript, and hands payment tools to the engine, which is the only
+ * thing that can move an execution past `drafted`.
+ */
+import type { ProofBundle } from "./bundle.js";
+import type { ExecutionEngine } from "./engine.js";
+import type { AgentRuntime, ConversationMessage, ToolCall, ToolSpec } from "./providers/types.js";
+import { isReply } from "./providers/types.js";
+import type { Execution } from "./state-machine.js";
+import type { ToolsFile } from "./tools.js";
+import { allowedToolNames, toolSpecs } from "./tools.js";
+
+export interface ToolContext {
+  engine: ExecutionEngine;
+  /** Fires when a payment tool created an execution; the channel decides what to do with it (ask, or run). */
+  onExecution: (execution: Execution) => Promise<Execution>;
+}
+
+export type ToolHandler = (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+
+export interface AgentLoopOptions {
+  runtime: AgentRuntime;
+  tools: ToolsFile;
+  handlers: Record<string, ToolHandler>;
+  system: string;
+  bundle: ProofBundle;
+  engine: ExecutionEngine;
+  onExecution: ToolContext["onExecution"];
+  /** A hard stop on tool round-trips per turn, so a looping model cannot run forever. */
+  maxSteps?: number;
+  clock?: () => Date;
+}
+
+export interface TurnResult {
+  reply: string;
+  tool_calls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+export class AgentLoop {
+  private readonly messages: ConversationMessage[] = [];
+  private readonly allowed: Set<string>;
+  private readonly specs: ToolSpec[];
+  private readonly clock: () => Date;
+
+  constructor(private readonly options: AgentLoopOptions) {
+    this.allowed = allowedToolNames(options.tools);
+    this.specs = toolSpecs(options.tools);
+    this.clock = options.clock ?? (() => new Date());
+  }
+
+  get history(): readonly ConversationMessage[] {
+    return this.messages;
+  }
+
+  async turn(userText: string): Promise<TurnResult> {
+    const { runtime, bundle } = this.options;
+    const maxSteps = this.options.maxSteps ?? 8;
+    const calls: TurnResult["tool_calls"] = [];
+    const executions: Execution[] = [];
+
+    this.messages.push({ role: "user", content: userText });
+    bundle.transcript({ at: this.now(), kind: "user", text: userText });
+
+    for (let step = 0; step < maxSteps; step += 1) {
+      const out = await runtime.step({ system: this.options.system, messages: this.messages }, this.specs);
+      if (isReply(out)) {
+        this.messages.push({ role: "assistant", content: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant_step", reply: out.text });
+        bundle.transcript({ at: this.now(), kind: "assistant", text: out.text });
+        return { reply: out.text, tool_calls: calls, executions };
+      }
+
+      this.messages.push({ role: "assistant", content: "", tool_calls: out });
+      bundle.transcript({ at: this.now(), kind: "assistant_step", tool_calls: out });
+
+      for (const call of out) {
+        const result = await this.dispatch(call, executions);
+        calls.push({ name: call.name, refused: result.refused });
+        this.messages.push({ role: "tool", tool_call_id: call.id, name: call.name, content: JSON.stringify(result.content), ...(result.refused ? { is_error: true } : {}) });
+        bundle.transcript({ at: this.now(), kind: "tool_result", tool_call_id: call.id, name: call.name, refused: result.refused, content: result.content });
+      }
+    }
+
+    const text = "I stopped: too many tool steps in one turn. Nothing was paid beyond what the trail shows.";
+    this.messages.push({ role: "assistant", content: text });
+    bundle.transcript({ at: this.now(), kind: "assistant", text, truncated: true });
+    return { reply: text, tool_calls: calls, executions };
+  }
+
+  private async dispatch(call: ToolCall, executions: Execution[]): Promise<{ refused: boolean; content: unknown }> {
+    const { bundle, handlers, engine, onExecution } = this.options;
+    bundle.transcript({ at: this.now(), kind: "tool_call", tool_call_id: call.id, name: call.name, input: call.input });
+
+    if (!this.allowed.has(call.name)) {
+      // Section 15, closed tools: a tool outside tools.json is refused, and the refusal is in the trail.
+      bundle.event({ at: this.now(), type: "tool.refused", tool: call.name, reason: "tool_not_allowed", actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_not_allowed", message: `${call.name} is not in this agent's tools.json` } };
+    }
+    const handler = handlers[call.name];
+    if (!handler) return { refused: true, content: { error: "tool_not_implemented", message: `${call.name} has no handler` } };
+
+    try {
+      const content = await handler(call.input, {
+        engine,
+        onExecution: async (execution) => {
+          const settledOrNot = await onExecution(execution);
+          executions.push(settledOrNot);
+          return settledOrNot;
+        },
+      });
+      return { refused: false, content };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      bundle.event({ at: this.now(), type: "tool.error", tool: call.name, message, actor: engine.agentActor });
+      return { refused: true, content: { error: "tool_failed", message } };
+    }
+  }
+
+  private now(): string {
+    return this.clock().toISOString();
+  }
+}