@strayl/agent 0.1.0

package/hello.txt

@@ -0,0 +1,4 @@
+Hello World!
+This is a test file with multiple lines.
+Line 2.
+Line 3.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@strayl/agent",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --format=esm --outfile=dist/agent.js --external:fsevents",
+    "dev": "tsx watch src/index.ts"
+  },
+  "dependencies": {
+    "openai": "^5.8.0",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.5",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "@types/node": "^22.15.31"
+  }
+}

package/run.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+# Strayl Agent Runner
+# Usage: ./run.sh "your prompt here"
+# Options:
+#   ./run.sh "prompt"                    - raw JSON output
+#   ./run.sh "prompt" --pretty           - human-readable output
+#   ./run.sh "prompt" --model deep       - use specific model (auto|light|pro|deep)
+#   ./run.sh "prompt" --work-dir /path   - set working directory
+
+# Direct mode: SDK calls providers directly with API keys (for local dev only)
+# In production, STRAYL_LLM_DIRECT is NOT set — all calls go through api.strayl.dev
+export STRAYL_LLM_DIRECT="1"
+export GOOGLE_GENERATIVE_AI_API_KEY="AIzaSyBLeK4sA6RjoAk1f1011nvtaS0OxFO6nas"
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROMPT=""
+MODEL="auto"
+PRETTY=false
+EXTRA_ARGS=()
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --pretty) PRETTY=true; shift ;;
+    --model) MODEL="$2"; shift 2 ;;
+    --work-dir|--blocked-tools|--max-iterations|--extra-prompt-file|--skills-dir)
+      EXTRA_ARGS+=("$1" "$2"); shift 2 ;;
+    *)
+      if [[ -z "$PROMPT" ]]; then
+        PROMPT="$1"
+      fi
+      shift ;;
+  esac
+done
+
+if [[ -z "$PROMPT" ]]; then
+  echo "Usage: ./run.sh \"your prompt\" [--pretty] [--model auto|light|pro|deep]"
+  exit 1
+fi
+
+if $PRETTY; then
+  node "$SCRIPT_DIR/dist/agent.js" --model "$MODEL" --prompt "$PROMPT" "${EXTRA_ARGS[@]}" 2>&1 | while IFS= read -r line; do
+    type=$(echo "$line" | jq -r '.type // empty' 2>/dev/null)
+    case "$type" in
+      session-start)
+        model=$(echo "$line" | jq -r '.model')
+        echo -e "\033[36m▶ Session started (model: $model)\033[0m"
+        ;;
+      text-delta)
+        echo -n "$(echo "$line" | jq -r '.text')"
+        ;;
+      reasoning-delta)
+        echo -ne "\033[2m$(echo "$line" | jq -r '.text')\033[0m"
+        ;;
+      tool-call-start)
+        name=$(echo "$line" | jq -r '.name')
+        args=$(echo "$line" | jq -c '.args')
+        echo -e "\n\033[33m🔧 $name\033[0m $args"
+        ;;
+      tool-result)
+        echo -e "\033[32m✅ done\033[0m"
+        ;;
+      exec-log)
+        echo -ne "\033[2m$(echo "$line" | jq -r '.data')\033[0m"
+        ;;
+      usage-update)
+        left=$(echo "$line" | jq -r '.context_left_percent')
+        cost=$(echo "$line" | jq -r '.cost // 0')
+        ;;
+      session-end)
+        reason=$(echo "$line" | jq -r '.exit_reason')
+        input=$(echo "$line" | jq -r '.usage.input_tokens')
+        output=$(echo "$line" | jq -r '.usage.output_tokens')
+        echo -e "\n\033[36m■ Done ($reason) | tokens: ${input}in/${output}out\033[0m"
+        ;;
+      error)
+        msg=$(echo "$line" | jq -r '.message')
+        echo -e "\033[31m✖ $msg\033[0m"
+        ;;
+    esac
+  done
+else
+  node "$SCRIPT_DIR/dist/agent.js" --model "$MODEL" --prompt "$PROMPT" "${EXTRA_ARGS[@]}" 2>&1
+fi

package/src/agent.ts

@@ -0,0 +1,440 @@
+import type { AgentConfig, ToolCall, ToolContext, Middleware, Message, AgentMode, ActivityType } from "./types.js";
+import { Emitter } from "./emitter.js";
+import { LLMClient } from "./llm/client.js";
+import { getModelLimits, resolveModel } from "./llm/models.js";
+import { ContextManager } from "./context/manager.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { executeTool } from "./tools/executor.js";
+import { HITLManager } from "./hitl/manager.js";
+import { SubAgentManager } from "./subagents/manager.js";
+import { TodoManager } from "./todos/manager.js";
+import { buildSystemPrompt } from "./prompts/system.js";
+import { loadSkills } from "./skills/loader.js";
+import { StdinListener } from "./stdin-listener.js";
+import { CheckpointManager } from "./checkpoints/manager.js";
+
+// Builtin tools
+import { execTool, getLogsTool } from "./tools/builtin/exec.js";
+import { readFileTool } from "./tools/builtin/read.js";
+import { writeFileTool } from "./tools/builtin/write.js";
+import { editFileTool } from "./tools/builtin/edit.js";
+import { lsTool } from "./tools/builtin/ls.js";
+import { grepTool } from "./tools/builtin/grep.js";
+import { globTool } from "./tools/builtin/glob.js";
+import { deleteFileTool } from "./tools/builtin/delete.js";
+import { moveFileTool } from "./tools/builtin/move.js";
+
+// External tools
+import { webSearchTool } from "./tools/external/web-search.js";
+import { webFetchTool } from "./tools/external/web-fetch.js";
+import { previewTool } from "./tools/external/preview.js";
+import { waitTool } from "./tools/external/wait.js";
+import { generateImageTool } from "./tools/external/generate-image.js";
+import { createTaskTool } from "./tools/external/task.js";
+import { enterPlanModeTool } from "./tools/external/enter-plan-mode.js";
+import { askUserTool, writePlanTool, requestEnvVarTool } from "./tools/external/hitl-tools.js";
+import { createDatabaseTool, listDatabasesTool, runDatabaseQueryTool, prepareDatabaseMigrationTool, completeDatabaseMigrationTool } from "./tools/external/database.js";
+
+// Middleware
+import { forbiddenPackagesMiddleware } from "./middleware/forbidden-packages.js";
+import { toolCompressionMiddleware } from "./middleware/tool-compression.js";
+import { createToolFilterMiddleware } from "./middleware/tool-filter.js";
+import { createPromptCachingMiddleware } from "./middleware/prompt-caching.js";
+import { credentialScrubbingMiddleware } from "./middleware/credential-scrubbing.js";
+import { createPlanModeMiddleware, resetContextForImplementation } from "./middleware/plan-mode.js";
+
+export async function runAgent(config: AgentConfig): Promise<void> {
+  const emitter = new Emitter();
+  const stdin = new StdinListener();
+  stdin.start();
+  const modelName = resolveModel(config.model);
+  const limits = getModelLimits(modelName);
+
+  // Mode state — mutable, changes on enterPlanMode tool or confirm-plan stdin command
+  let currentMode: AgentMode = config.mode ?? "normal";
+
+  const client = new LLMClient({
+    modelTier: config.model,
+    env: config.env,
+    sessionId: config.sessionId,
+  });
+
+  const context = new ContextManager({
+    maxInputTokens: limits.maxInputTokens,
+    summarizationThreshold: config.summarizationThreshold,
+    preSummarizationRatio: config.preSummarizationRatio,
+    previousSummary: config.previousSummary,
+  });
+
+  const registry = new ToolRegistry();
+  const hitl = new HITLManager(config.hitlDir);
+  await hitl.init();
+  const subAgentManager = new SubAgentManager(emitter);
+  const todoManager = new TodoManager(emitter);
+  const checkpoints = new CheckpointManager(config.workDir, config.sessionId);
+  await checkpoints.init();
+
+  // Register all tools
+  const builtinTools = [execTool, getLogsTool, readFileTool, writeFileTool, editFileTool, lsTool, grepTool, globTool, deleteFileTool, moveFileTool];
+  const databaseTools = [createDatabaseTool, listDatabasesTool, runDatabaseQueryTool, prepareDatabaseMigrationTool, completeDatabaseMigrationTool];
+  const externalTools = [webSearchTool, webFetchTool, previewTool, waitTool, generateImageTool, enterPlanModeTool, ...databaseTools];
+  const hitlTools = [askUserTool, writePlanTool, requestEnvVarTool];
+
+  for (const tool of [...builtinTools, ...externalTools, ...hitlTools]) {
+    registry.register(tool);
+  }
+  registry.register(createTaskTool(subAgentManager));
+  for (const tool of todoManager.createTools()) {
+    registry.register(tool);
+  }
+
+  // Build middleware
+  const middleware: Middleware[] = [
+    toolCompressionMiddleware,
+    forbiddenPackagesMiddleware,
+    credentialScrubbingMiddleware,
+    createToolFilterMiddleware(config.blockedTools ?? []),
+    createPlanModeMiddleware(() => currentMode),
+    createPromptCachingMiddleware(modelName),
+  ];
+
+  emitter.emit({ type: "session-start", model: modelName, session_id: config.sessionId });
+
+  // Load skills and build system prompt
+  const skills = await loadSkills(config.skillsDir ?? "./skills");
+  const systemPrompt = buildSystemPrompt({
+    workDir: config.workDir,
+    skills,
+    systemPromptExtra: config.systemPromptExtra,
+    mode: currentMode,
+  });
+
+  let iteration = 0;
+  const maxIterations = config.maxIterations ?? 200;
+
+  // Restore from checkpoint or start fresh
+  if (config.restoreCheckpoint) {
+    const cp = config.restoreCheckpoint;
+    context.restoreMessages(cp.messages);
+    todoManager.restore(cp.todos);
+    iteration = cp.iteration;
+    emitter.emit({ type: "checkpoint-restored", id: cp.id, iteration: cp.iteration });
+
+    // Inject new user message as continuation
+    context.addUser(config.userMessage);
+  } else {
+    context.addSystem(systemPrompt);
+    context.addUser(config.userMessage, config.images);
+  }
+
+  while (iteration < maxIterations) {
+    iteration++;
+
+    // Process stdin commands (inject, cancel, hitl-response, rollback)
+    for (const cmd of stdin.drain()) {
+      switch (cmd.type) {
+        case "inject":
+          context.addUser(cmd.text, cmd.images);
+          emitter.emit({ type: "inject-received", text: cmd.text });
+          break;
+        case "hitl-response":
+          // Forward to file-based HITL (stdin is an alternative transport)
+          await hitl.writeResponse(cmd.id, { decision: cmd.decision, data: cmd.data });
+          break;
+        case "confirm-plan": {
+          if (currentMode !== "plan") break;
+          const prevMode = currentMode;
+          currentMode = "implement";
+
+          // Context reset: extract plan, clear planning messages, inject plan as system context
+          const { newMessages, planContent } = resetContextForImplementation(context.messages());
+          context.restoreMessages(newMessages);
+
+          // Save confirmed plan to disk
+          if (planContent) {
+            const planDir = `${config.workDir}/.strayl/plans`;
+            const fs = await import("node:fs/promises");
+            const path = await import("node:path");
+            await fs.mkdir(planDir, { recursive: true });
+            const planFile = path.join(planDir, `${config.sessionId}-${Date.now()}.md`);
+            await fs.writeFile(planFile, planContent);
+            emitter.emit({ type: "plan-confirmed", plan: planContent });
+          }
+
+          emitter.emit({ type: "mode-changed", from: prevMode, to: currentMode });
+
+          // Inject implementation mode prompt into context
+          const { IMPLEMENTATION_MODE_PROMPT } = await import("./prompts/system.js");
+          context.addUser(`[System] The plan has been confirmed. Switch to implementation mode.\n\n${IMPLEMENTATION_MODE_PROMPT}`);
+          break;
+        }
+        case "rollback": {
+          const cp = cmd.checkpoint_id
+            ? checkpoints.get(cmd.checkpoint_id)
+            : cmd.iteration != null
+              ? checkpoints.getByIteration(cmd.iteration)
+              : checkpoints.latest();
+          if (cp) {
+            context.restoreMessages(cp.messages);
+            todoManager.restore(cp.todos);
+            iteration = cp.iteration;
+            emitter.emit({ type: "checkpoint-restored", id: cp.id, iteration: cp.iteration });
+          } else {
+            emitter.emit({ type: "error", message: "Checkpoint not found", recoverable: true });
+          }
+          break;
+        }
+      }
+    }
+
+    // Check cancellation (stdin or file-based)
+    if (stdin.isCancelled() || await hitl.isCancelled()) {
+      stdin.stop();
+      emitter.emit({ type: "session-end", usage: context.totalUsage(), exit_reason: "cancelled" });
+      return;
+    }
+
+    // Pre-summarization (non-blocking)
+    context.maybeTriggerPreSummarization(client, emitter);
+
+    // Apply pending summary if ready
+    await context.applyPendingSummary(emitter);
+
+    // Hard summarization (blocking)
+    if (context.shouldSummarize()) {
+      emitter.emit({
+        type: "summarizing",
+        token_count: context.estimateTokens(),
+        threshold: config.summarizationThreshold ?? 140_000,
+      });
+      await context.summarize(client, emitter);
+    }
+
+    // Hard trim if still over limit
+    if (context.estimateTokens() > context.maxInputTokens) {
+      context.applyTrim();
+    }
+
+    // Prepare messages + tools
+    let messages = context.messages();
+    let tools = registry.toOpenAITools(new Set(config.blockedTools));
+
+    // Apply middleware
+    for (const mw of middleware) {
+      if (mw.beforeModel) messages = mw.beforeModel(messages);
+      if (mw.filterTools) tools = mw.filterTools(tools);
+    }
+
+    // Stream LLM response
+    let assistantText = "";
+    const completedToolCalls: ToolCall[] = [];
+    const partialArgs = new Map<number, { id: string; name: string; args: string }>();
+
+    try {
+      for await (const chunk of client.stream(messages, tools)) {
+        switch (chunk.type) {
+          case "text":
+            assistantText += chunk.text;
+            emitter.emit({ type: "text-delta", text: chunk.text });
+            break;
+
+          case "reasoning":
+            emitter.emit({ type: "reasoning-delta", text: chunk.text });
+            break;
+
+          case "tool_call_delta": {
+            const partial = partialArgs.get(chunk.index) ?? { id: "", name: "", args: "" };
+            if (chunk.id) partial.id = chunk.id;
+            if (chunk.name) partial.name = chunk.name;
+            partial.args += chunk.arguments;
+            partialArgs.set(chunk.index, partial);
+            break;
+          }
+
+          case "tool_call_complete":
+            completedToolCalls.push({
+              id: chunk.id,
+              type: "function",
+              function: { name: chunk.name, arguments: chunk.arguments },
+            });
+            break;
+
+          case "usage": {
+            context.recordUsage(chunk);
+            const used = context.estimateTokens();
+            const max = context.maxInputTokens;
+            const leftPercent = Math.max(0, Math.round((1 - used / max) * 100));
+            emitter.emit({
+              type: "usage-update",
+              input_tokens: chunk.input_tokens,
+              output_tokens: chunk.output_tokens,
+              cost: chunk.cost,
+              peak_input_tokens: context.peakInputTokens(),
+              context_left_percent: leftPercent,
+            });
+            break;
+          }
+        }
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      emitter.emit({ type: "error", message: `LLM error: ${msg}`, recoverable: true });
+
+      // Add error as assistant message so loop can continue
+      context.addAssistant(`[Error communicating with model: ${msg}]`);
+      continue;
+    }
+
+    // Add assistant message to context
+    context.addAssistant(assistantText, completedToolCalls.length > 0 ? completedToolCalls : undefined);
+
+    // Emit context status after each LLM call
+    {
+      const used = context.estimateTokens();
+      const max = context.maxInputTokens;
+      const leftPercent = Math.max(0, Math.round((1 - used / max) * 100));
+      const usage = context.totalUsage();
+      emitter.emit({
+        type: "usage-update",
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        cost: usage.cost,
+        peak_input_tokens: context.peakInputTokens(),
+        context_left_percent: leftPercent,
+      });
+    }
+
+    // No tool calls = agent is done
+    if (completedToolCalls.length === 0) break;
+
+    // Execute tool calls
+    for (const tc of completedToolCalls) {
+      let parsedArgs: unknown;
+      try {
+        parsedArgs = JSON.parse(tc.function.arguments);
+      } catch {
+        parsedArgs = {};
+      }
+
+      // Emit semantic activity for UI indicators
+      const activity = toolToActivity(tc.function.name, parsedArgs);
+      if (activity) {
+        emitter.emit({ type: "activity", ...activity });
+      }
+
+      emitter.emit({ type: "tool-call-start", id: tc.id, name: tc.function.name, args: parsedArgs });
+
+      // HITL interrupt check
+      const toolDef = registry.get(tc.function.name);
+      if (toolDef?.hitl) {
+        emitter.emit({ type: "hitl-request", id: tc.id, safe_id: hitl.safeId(tc.id), tool: tc.function.name, args: parsedArgs });
+        const response = await hitl.waitForResponse(tc.id);
+
+        if (response.decision === "reject") {
+          const rejectResult = JSON.stringify({ error: "User rejected this action." });
+          emitter.emit({ type: "tool-result", id: tc.id, name: tc.function.name, output: rejectResult });
+          context.addToolResult(tc.id, tc.function.name, rejectResult);
+          continue;
+        }
+
+        if (response.decision === "edit" && response.data && typeof response.data === "object") {
+          parsedArgs = { ...(parsedArgs as Record<string, unknown>), ...(response.data as Record<string, unknown>) };
+        }
+
+        emitter.emit({ type: "hitl-response", id: tc.id, decision: response.decision, data: response.data });
+      }
+
+      // Execute with middleware chain
+      const toolCtx: ToolContext = {
+        emitter,
+        workDir: config.workDir,
+        env: config.env,
+        sessionId: config.sessionId,
+        toolCallId: tc.id,
+      };
+
+      const modifiedTc: ToolCall = {
+        ...tc,
+        function: { ...tc.function, arguments: JSON.stringify(parsedArgs) },
+      };
+
+      const result = await executeTool(registry, modifiedTc, toolCtx, middleware);
+
+      emitter.emit({ type: "tool-result", id: tc.id, name: tc.function.name, output: result });
+      context.addToolResult(tc.id, tc.function.name, result);
+
+      // Mode transition: enterPlanMode tool → switch to plan mode
+      if (tc.function.name === "enterPlanMode" && currentMode === "normal") {
+        const prevMode = currentMode;
+        currentMode = "plan";
+        emitter.emit({ type: "mode-changed", from: prevMode, to: currentMode });
+      }
+    }
+
+    // Save checkpoint after each complete iteration (LLM response + all tool results)
+    await checkpoints.save(iteration, context.messages(), todoManager.read(), context.totalUsage(), emitter);
+  }
+
+  if (iteration >= maxIterations) {
+    emitter.emit({
+      type: "error",
+      message: `Agent exceeded maximum iterations (${maxIterations})`,
+      recoverable: false,
+    });
+  }
+
+  stdin.stop();
+  emitter.emit({
+    type: "session-end",
+    usage: context.totalUsage(),
+    exit_reason: iteration >= maxIterations ? "max_iterations" : "complete",
+  });
+}
+
+/** Map tool name → semantic activity for UI indicators */
+function toolToActivity(
+  name: string,
+  args: unknown,
+): { activity: ActivityType; message?: string } | null {
+  const a = args as Record<string, unknown> | undefined;
+  switch (name) {
+    case "write_todos": {
+      const todos = a?.todos as unknown[] | undefined;
+      if (!todos || todos.length === 0) return { activity: "clearing-todos" };
+      return { activity: "creating-todos" };
+    }
+    case "update_todo":
+      return { activity: "updating-todos" };
+    case "askUser":
+      return { activity: "asking-user", message: a?.question as string };
+    case "writePlan":
+      return { activity: "planning", message: a?.title as string };
+    case "enterPlanMode":
+      return { activity: "planning", message: a?.reason as string };
+    case "create_database":
+      return { activity: "creating-database", message: a?.name as string };
+    case "run_database_query":
+      return { activity: "running-query" };
+    case "prepare_database_migration":
+    case "complete_database_migration":
+      return { activity: "running-migration" };
+    case "web_search":
+      return { activity: "searching-web", message: a?.query as string };
+    case "web_fetch":
+      return { activity: "fetching-page", message: a?.url as string };
+    case "generate_image":
+      return { activity: "generating-image" };
+    case "read_file":
+      return { activity: "reading-file", message: a?.path as string };
+    case "write_file":
+      return { activity: "writing-file", message: a?.path as string };
+    case "edit_file":
+      return { activity: "editing-file", message: a?.path as string };
+    case "exec":
+      return { activity: "running-command", message: (a?.command as string)?.slice(0, 80) };
+    case "task":
+      return { activity: "delegating-task", message: a?.description as string };
+    default:
+      return null;
+  }
+}

package/src/checkpoints/manager.ts

@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Message, TodoItem, Usage, CheckpointData } from "../types.js";
+import type { Emitter } from "../emitter.js";
+
+export type Checkpoint = CheckpointData;
+
+export class CheckpointManager {
+  private dir: string;
+  private checkpoints: Map<string, Checkpoint> = new Map();
+
+  constructor(workDir: string, sessionId: string) {
+    this.dir = path.join(workDir, ".strayl", "checkpoints", sessionId);
+  }
+
+  async init(): Promise<void> {
+    await fs.mkdir(this.dir, { recursive: true });
+
+    // Load existing checkpoints from disk
+    try {
+      const files = await fs.readdir(this.dir);
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        try {
+          const content = await fs.readFile(path.join(this.dir, file), "utf-8");
+          const cp = JSON.parse(content) as Checkpoint;
+          this.checkpoints.set(cp.id, cp);
+        } catch {
+          // Corrupted checkpoint — skip
+        }
+      }
+    } catch {
+      // No checkpoints dir yet — fine
+    }
+  }
+
+  async save(
+    iteration: number,
+    messages: Message[],
+    todos: TodoItem[],
+    usage: Usage,
+    emitter: Emitter,
+  ): Promise<string> {
+    const id = `cp_${iteration}_${Date.now()}`;
+    const checkpoint: Checkpoint = {
+      id,
+      iteration,
+      timestamp: Date.now(),
+      messages: structuredClone(messages),
+      todos: structuredClone(todos),
+      usage: { ...usage },
+    };
+
+    this.checkpoints.set(id, checkpoint);
+
+    // Write atomically: tmp → rename
+    const tmpPath = path.join(this.dir, `${id}.tmp`);
+    const finalPath = path.join(this.dir, `${id}.json`);
+    await fs.writeFile(tmpPath, JSON.stringify(checkpoint));
+    await fs.rename(tmpPath, finalPath);
+
+    emitter.emit({ type: "checkpoint-saved", id, iteration, checkpoint });
+
+    // Keep only last 50 checkpoints on disk
+    await this.pruneOld(50);
+
+    return id;
+  }
+
+  get(id: string): Checkpoint | undefined {
+    return this.checkpoints.get(id);
+  }
+
+  /** Get the most recent checkpoint at or before the given iteration */
+  getByIteration(iteration: number): Checkpoint | undefined {
+    let best: Checkpoint | undefined;
+    for (const cp of this.checkpoints.values()) {
+      if (cp.iteration <= iteration) {
+        if (!best || cp.iteration > best.iteration) {
+          best = cp;
+        }
+      }
+    }
+    return best;
+  }
+
+  /** Get the latest checkpoint */
+  latest(): Checkpoint | undefined {
+    let best: Checkpoint | undefined;
+    for (const cp of this.checkpoints.values()) {
+      if (!best || cp.timestamp > best.timestamp) {
+        best = cp;
+      }
+    }
+    return best;
+  }
+
+  list(): Checkpoint[] {
+    return [...this.checkpoints.values()].sort((a, b) => a.iteration - b.iteration);
+  }
+
+  private async pruneOld(keep: number): Promise<void> {
+    const sorted = this.list();
+    if (sorted.length <= keep) return;
+
+    const toRemove = sorted.slice(0, sorted.length - keep);
+    for (const cp of toRemove) {
+      this.checkpoints.delete(cp.id);
+      await fs.unlink(path.join(this.dir, `${cp.id}.json`)).catch(() => {});
+    }
+  }
+}