even-pf 0.4.1 → 0.5.0

package/bun.lock

@@ -5,48 +5,48 @@
     "": {
       "name": "tools",
       "dependencies": {
-        "@openrouter/sdk": "^0.5.1",
+        "@openrouter/sdk": "^0.12.79",
         "chalk": "^5.6.2",
-        "smol-toml": "^1.6.0",
+        "smol-toml": "^1.6.1",
         "zod-defaults": "^0.2.3",
       },
       "devDependencies": {
-        "@types/bun": "latest",
+        "@types/bun": "1.3.14",
       },
       "optionalDependencies": {
-        "even-pf-darwin-arm64": "0.3.4",
-        "even-pf-darwin-x64": "0.3.4",
-        "even-pf-linux-arm64": "0.3.4",
-        "even-pf-linux-x64": "0.3.4",
-        "even-pf-windows-x64": "0.3.4",
+        "even-pf-darwin-arm64": "0.4.2",
+        "even-pf-darwin-x64": "0.4.2",
+        "even-pf-linux-arm64": "0.4.2",
+        "even-pf-linux-x64": "0.4.2",
+        "even-pf-windows-x64": "0.4.2",
       },
       "peerDependencies": {
-        "typescript": "^5.9.3",
+        "typescript": "^6.0.3",
       },
     },
   },
   "packages": {
-    "@openrouter/sdk": ["@openrouter/sdk@0.5.1", "", { "dependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-Kl0N1jIj7A3lnkM5dO3SGP8JP3jAozzs6JWcHVuZUBt5DsGKxFGNH1Y15bCfsJiLNA2ylAQpCN3aNcgEYkkL5Q=="],
+    "@openrouter/sdk": ["@openrouter/sdk@0.12.79", "", { "dependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-0ZpwtnuHh3/B1piW9kHCUIQy6PAsaK/vjFdZuHxmCdAenCyUNsLA2mFpmfHNWRNb+bOO3yBc4IALa264UyzmBA=="],
 
-    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
     "@types/node": ["@types/node@24.10.1", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-GNWcUTRBgIRJD5zj+Tq0fKOJ5XZajIiBroOF0yvj2bSU1WvNdYS/dn9UxwsujGW4JX06dnHyjV2y9rRaybH0iQ=="],
 
-    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
     "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
 
-    "even-pf-darwin-arm64": ["even-pf-darwin-arm64@0.3.4", "", { "os": "darwin", "cpu": "arm64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-x2vTM0ogvlFhUiHqb13kXJTKPRPU/VdoZa1G51c3IHsZz7wdDpkD/DxcEvxAmO28MbJtfjxig8nRFMvld5J6jg=="],
+    "even-pf-darwin-arm64": ["even-pf-darwin-arm64@0.4.2", "", { "os": "darwin", "cpu": "arm64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-W1W1EhdqZmUW6wJi+bCuS537MWvMUO6ryRgOErG38tFGs1h91JXT/upiuoRv5L245tKrKLMM5HkVZ88qNVrTUQ=="],
 
-    "even-pf-darwin-x64": ["even-pf-darwin-x64@0.3.4", "", { "os": "darwin", "cpu": "x64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-L2hzBvSLFcWMB/MJQeZTQHI8mqpGMQ7T0tSPXjv4S1tFglF8ZtdxggDAhmItEyyqVfsAT6LY+HyOpJnUAga9tg=="],
+    "even-pf-darwin-x64": ["even-pf-darwin-x64@0.4.2", "", { "os": "darwin", "cpu": "x64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-mysyZkNdQvlqOjM/gpEfoGZZJ5H2b7MT4Z7jwbJhZpy4XCwWO98x3MpMWlUqJW+wEAMea+PwPJVJ314hkeQEgw=="],
 
-    "even-pf-linux-arm64": ["even-pf-linux-arm64@0.3.4", "", { "os": "linux", "cpu": "arm64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-/5nLtKs+8xvTHEkrVPQQ5XQBTKROmF42z6+fo4AOkOj/TbDGwCher6RYYMHQ6pD7M0jjF5AdSlj5HLEGf/N9Qg=="],
+    "even-pf-linux-arm64": ["even-pf-linux-arm64@0.4.2", "", { "os": "linux", "cpu": "arm64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-rIh+SDDN3oDAyNN94SDm3dDiJ7jarkelZoh3c3ibvLJ5+WHA4XFhiBIRQjPBv+VX49TFooPmjqPMH8X5pkUc8w=="],
 
-    "even-pf-linux-x64": ["even-pf-linux-x64@0.3.4", "", { "os": "linux", "cpu": "x64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-UN0wz2svjcjckugzFyc4tHxllrTM7IScSmnLDq5z9AB5cplHZrvAg8cYcvz20YEcHsr7aUkxrhA7iDv5KKYhkA=="],
+    "even-pf-linux-x64": ["even-pf-linux-x64@0.4.2", "", { "os": "linux", "cpu": "x64", "bin": { "even-pf": "bin/even-pf" } }, "sha512-WhE5k5se/vgLlfHTVtsU4mXa094pTmuPKps6l+Gctak+toPaGtmOlr+KpDT3CDOnMRvEwnJWMrx8QA1mpfzyuQ=="],
 
-    "even-pf-windows-x64": ["even-pf-windows-x64@0.3.4", "", { "os": "win32", "cpu": "x64", "bin": { "even-pf": "bin/even-pf.exe" } }, "sha512-ni84uLUdo95TlACDUyz7Ia7+4wigSByvUuR+IrXbLzkN90mZTsJoZVbAoJMR8CnOlPPEClcPHqkTcYl1lbLOwA=="],
+    "even-pf-windows-x64": ["even-pf-windows-x64@0.4.2", "", { "os": "win32", "cpu": "x64", "bin": { "even-pf": "bin/even-pf.exe" } }, "sha512-CkYMt99VWmZixbXKxR2301lxiKKCr6XF3QxU2f9HO2z6vSBzWNbT70JsuBc8UtKJqeuxg4MW8LONYpAxfuaKgg=="],
 
-    "smol-toml": ["smol-toml@1.6.0", "", {}, "sha512-4zemZi0HvTnYwLfrpk/CF9LOd9Lt87kAt50GnqhMpyF9U3poDAP2+iukq2bZsO/ufegbYehBkqINbsWxj4l4cw=="],
+    "smol-toml": ["smol-toml@1.6.1", "", {}, "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg=="],
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 

package/epf.example.toml

@@ -12,6 +12,8 @@ top_p = 1
 frequency_penalty = 0
 presence_penalty = 0
 reasoning_effort = "high"
+max_retries = 1
+retry_delay_ms = 1000
 
 [llm.models.output_comparison]
 sdk = "openrouter"
@@ -22,6 +24,8 @@ top_p = 1
 frequency_penalty = 0
 presence_penalty = 0
 reasoning_effort = "high"
+max_retries = 1
+retry_delay_ms = 1000
 
 [llm.prompt_replacement]
 role = "role_placeholder"

package/package.json

@@ -1,41 +1,42 @@
 {
   "name": "even-pf",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "AI-assisted responsible grading tool for programming assignments",
-  "module": "src/cli.ts",
+  "module": "src/hosts/cli-host.ts",
   "type": "module",
   "license": "UNLICENSED",
   "scripts": {
-    "start": "bun run src/cli.ts",
-    "build:dev": "bun build src/cli.ts --compile --outfile build/epf",
+    "start": "bun run src/hosts/cli-host.ts",
+    "build:dev": "bun build src/hosts/cli-host.ts --compile --outfile build/epf",
     "build:all": "bun scripts/build-all.ts",
     "publish:all": "bun scripts/publish-all.ts",
     "publish:dry": "bun scripts/publish-all.ts --dry-run",
     "bump": "bun scripts/bump-version.ts",
-    "config-gen": "bun run --console-depth 6 src/generate-config.ts"
+    "config-gen": "bun run --console-depth 6 src/generate-config.ts",
+    "check": "bun x tsc --noEmit"
   },
   "bin": {
     "even-pf": "bin/even-pf.js",
-    "e-pf": "src/cli.ts"
+    "e-pf": "src/hosts/cli-host.ts"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "1.3.14"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@openrouter/sdk": "^0.5.1",
+    "@openrouter/sdk": "^0.12.79",
     "chalk": "^5.6.2",
-    "smol-toml": "^1.6.0",
+    "smol-toml": "^1.6.1",
     "zod-defaults": "^0.2.3"
   },
   "optionalDependencies": {
-    "even-pf-linux-x64": "0.4.1",
-    "even-pf-linux-arm64": "0.4.1",
-    "even-pf-windows-x64": "0.4.1",
-    "even-pf-darwin-x64": "0.4.1",
-    "even-pf-darwin-arm64": "0.4.1"
+    "even-pf-linux-x64": "0.5.0",
+    "even-pf-linux-arm64": "0.5.0",
+    "even-pf-windows-x64": "0.5.0",
+    "even-pf-darwin-x64": "0.5.0",
+    "even-pf-darwin-arm64": "0.5.0"
   },
   "files": [
     "bin/even-pf.js",

package/src/api-server.ts

@@ -0,0 +1,105 @@
+import type { Engine } from "./engine/index.ts";
+import { parseAndExecute } from "./command-handler.ts";
+
+const CORS_HEADERS: Record<string, string> = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+};
+
+function jsonResponse(data: unknown, status = 200): Response {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: {
+            "Content-Type": "application/json",
+            ...CORS_HEADERS,
+        },
+    });
+}
+
+function corsPreflightResponse(): Response {
+    return new Response(null, { status: 204, headers: CORS_HEADERS });
+}
+
+type ApiServerHandle = {
+    url: string;
+    stop: () => void;
+};
+
+/**
+ * HTTP server that serves both file-data routes (migrated from OutputViewer)
+ * and command routes (POST /api/commands).  Both use the same Engine instance
+ * that the CLI REPL also talks to.
+ */
+export function startApiServer(engine: Engine, port: number): ApiServerHandle {
+    const server = Bun.serve({
+        port,
+        routes: {
+            // --- File data routes (migrated from OutputViewer.serve) ---
+            "/": (req) => {
+                if (req.method === "OPTIONS") {
+                    return corsPreflightResponse();
+                }
+                const files = engine.outputViewer.getFileList().map((f) => ({
+                    name: f.name,
+                    type: f.type,
+                    modification_time: f.modification_time,
+                }));
+                return jsonResponse({ files });
+            },
+
+            // --- Command route ---
+            "/api/commands": async (req) => {
+                if (req.method === "OPTIONS") {
+                    return corsPreflightResponse();
+                }
+                if (req.method !== "POST") {
+                    return jsonResponse({ error: "Method Not Allowed. Use POST." }, 405);
+                }
+                try {
+                    const body = await req.json() as { command?: string };
+                    const command = body?.command?.trim() ?? "";
+                    if (command.length === 0) {
+                        return jsonResponse({ error: "Missing 'command' field in request body." }, 400);
+                    }
+                    const result = await parseAndExecute(engine, command);
+                    return jsonResponse(result);
+                } catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return jsonResponse({ kind: "error", message: `Server error: ${message}` }, 500);
+                }
+            },
+
+            // --- Single file data route ---
+            "/:slug": (req) => {
+                if (req.method === "OPTIONS") {
+                    return corsPreflightResponse();
+                }
+                const slug = req.params.slug;
+                const record = engine.outputViewer.getFile(slug);
+                if (!record) {
+                    return jsonResponse({ error: "Not Found" }, 404);
+                }
+                return jsonResponse({
+                    name: slug,
+                    type: record.type,
+                    content: record.content,
+                });
+            },
+        },
+        fetch(req) {
+            if (req.method === "OPTIONS") {
+                return corsPreflightResponse();
+            }
+            return jsonResponse({ error: "Not Found" }, 404);
+        },
+    });
+
+    const url = server.url.toString();
+    console.log(`API server listening at ${url}`);
+
+    return {
+        url,
+        stop: () => server.stop(),
+    };
+}

package/src/command-handler.ts

@@ -0,0 +1,139 @@
+import type { Engine } from "./engine/index.ts";
+
+export type CommandResult = {
+    kind: "output" | "error" | "exit";
+    message: string;
+};
+
+/** All recognized command names — exported for tab-completion. */
+export const COMMAND_NAMES: readonly string[] = [
+    "run",
+    "clear",
+    "status",
+    "list",
+    "help",
+    "exit",
+    "quit",
+] as const;
+
+const HELP_TEXT = `Available commands:
+  run [slug...]    Re-run workflows (all if no slug given)
+  clear [slug...]  Clear output files (all if no slug given)
+  status           Show in-flight workflows and output file count
+  list             Show all configured workflow slugs
+  help             Show this help message
+  exit / quit      Shut down the program`;
+
+/**
+ * Parse a raw command string and dispatch to the appropriate Engine method.
+ * Returns a structured result that any input channel (CLI REPL, HTTP API)
+ * can format however it likes.
+ */
+export async function parseAndExecute(engine: Engine, rawInput: string): Promise<CommandResult> {
+    const trimmed = rawInput.trim();
+    if (trimmed.length === 0) {
+        return { kind: "output", message: "" };
+    }
+
+    const parts = trimmed.split(/\s+/);
+    const command = parts[0]!.toLowerCase();
+    const args = parts.slice(1);
+
+    switch (command) {
+        case "run":
+            return await handleRun(engine, args);
+        case "clear":
+            return handleClear(engine, args);
+        case "status":
+            return handleStatus(engine);
+        case "list":
+            return handleList(engine);
+        case "help":
+            return { kind: "output", message: HELP_TEXT };
+        case "exit":
+        case "quit":
+            return { kind: "exit", message: "Shutting down..." };
+        default:
+            return { kind: "error", message: `Unknown command: '${command}'. Type 'help' for available commands.` };
+    }
+}
+
+async function handleRun(engine: Engine, slugs: string[]): Promise<CommandResult> {
+    const filters = slugs.length > 0 ? { only: slugs } : undefined;
+    const results = await engine.runWorkflows(filters);
+
+    if (results.length === 0) {
+        return { kind: "output", message: "No workflows matched the given filter." };
+    }
+
+    const lines: string[] = [];
+    let hasFailures = false;
+    for (const r of results) {
+        switch (r.status) {
+            case "succeeded":
+                lines.push(`  ✓ ${r.slug} (run ${r.runNumber}) — succeeded`);
+                break;
+            case "failed":
+                lines.push(`  ✗ ${r.slug} (run ${r.runNumber}) — failed: ${r.error ?? "unknown error"}`);
+                hasFailures = true;
+                break;
+            case "rejected":
+                lines.push(`  ⊘ ${r.slug} — rejected: ${r.error ?? "already running"}`);
+                hasFailures = true;
+                break;
+        }
+    }
+
+    const succeeded = results.filter((r) => r.status === "succeeded").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    const rejected = results.filter((r) => r.status === "rejected").length;
+
+    lines.unshift(`Workflow run complete. Succeeded: ${succeeded}, Failed: ${failed}, Rejected: ${rejected}`);
+    return { kind: hasFailures ? "error" : "output", message: lines.join("\n") };
+}
+
+function handleClear(engine: Engine, slugs: string[]): CommandResult {
+    const filter = slugs.length > 0 ? slugs : undefined;
+    engine.clearResults(filter);
+    const target = filter ? filter.join(", ") : "all";
+    return { kind: "output", message: `Cleared results: ${target}` };
+}
+
+function handleStatus(engine: Engine): CommandResult {
+    const status = engine.getStatus();
+    const lines: string[] = [];
+    lines.push(`In-flight workflows: ${status.inFlight.length > 0 ? status.inFlight.join(", ") : "(none)"}`);
+    lines.push(`Output files: ${status.completedFiles.length}`);
+    if (status.completedFiles.length > 0) {
+        for (const f of status.completedFiles) {
+            lines.push(`  • ${f}`);
+        }
+    }
+    return { kind: "output", message: lines.join("\n") };
+}
+
+function handleList(engine: Engine): CommandResult {
+    const workflows = engine.listWorkflows();
+    const lines: string[] = [];
+
+    if (workflows.analysis.length > 0) {
+        lines.push("Analysis workflows:");
+        for (const slug of workflows.analysis) {
+            lines.push(`  • ${slug}`);
+        }
+    }
+    if (workflows.testing.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("Testing workflows:");
+        for (const slug of workflows.testing) {
+            lines.push(`  • ${slug}`);
+        }
+    }
+
+    if (lines.length === 0) {
+        return { kind: "output", message: "No workflows configured." };
+    }
+    return { kind: "output", message: lines.join("\n") };
+}

package/src/engine/engine.ts

@@ -0,0 +1,165 @@
+import { OpenRouter } from "@openrouter/sdk";
+
+import { OutputViewer } from "../util/output-viewer.ts";
+import { executeAnalysisWorkflow } from "../workflow/analysis-workflow.ts";
+import { executeTestingWorkflow } from "../workflow/testing-workflow.ts";
+import type { WorkflowDependencies } from "../workflow/index.ts";
+import type { Config } from "../util/config.ts";
+
+export type WorkflowRunResult = {
+    slug: string;
+    runNumber: number;
+    status: "succeeded" | "failed" | "rejected";
+    error?: string;
+};
+
+export type EngineStatus = {
+    inFlight: string[];
+    completedFiles: string[];
+};
+
+/**
+ * Stateful core that owns the OutputViewer, WorkflowDependencies, and
+ * in-flight tracking.  Runtime-agnostic — no process.stdin / stdout,
+ * no HTTP server.  Input channels (CLI REPL, HTTP API) call into this
+ * via the CommandHandler.
+ */
+export class Engine {
+    readonly outputViewer: OutputViewer;
+    private readonly config: Config;
+    private readonly deps: WorkflowDependencies;
+    private readonly inFlightSlugs: Set<string> = new Set();
+
+    constructor(config: Config) {
+        this.config = config;
+        this.outputViewer = new OutputViewer();
+        this.deps = {
+            seed: Math.floor(Date.now() / 1000),
+            openRouter: new OpenRouter({
+                apiKey: config.vendors.openrouter.api_key,
+            }),
+            outputViewer: this.outputViewer,
+        };
+    }
+
+    /**
+     * Run workflows matching the given filters.
+     * If `only` is provided, only run slugs in that list.
+     * If `skip` is provided, skip slugs in that list.
+     * Rejects any slug that is already in-flight.
+     */
+    async runWorkflows(filters?: { only?: string[]; skip?: string[] }): Promise<WorkflowRunResult[]> {
+        const onlySlugs = filters?.only;
+        const skipSlugs = filters?.skip;
+
+        let analysisWorkflows = this.applyFilters(this.config.analysis_workflows, onlySlugs, skipSlugs);
+        let testingWorkflows = this.applyFilters(this.config.testing_workflows, onlySlugs, skipSlugs);
+
+        console.log(`Starting execution of ${analysisWorkflows.length} analysis + ${testingWorkflows.length} testing workflows...`);
+        console.log([...analysisWorkflows, ...testingWorkflows].map((w) => w.slug));
+
+        const runs: { slug: string; runNumber: number; promise: Promise<void> }[] = [];
+        const results: WorkflowRunResult[] = [];
+
+        // Build run list, rejecting in-flight duplicates
+        for (const workflow of analysisWorkflows) {
+            if (this.inFlightSlugs.has(workflow.slug)) {
+                results.push({ slug: workflow.slug, runNumber: 0, status: "rejected", error: "already running" });
+                continue;
+            }
+            this.inFlightSlugs.add(workflow.slug);
+            for (let i = 0; i < workflow.runs; i++) {
+                runs.push({
+                    slug: workflow.slug,
+                    runNumber: i + 1,
+                    promise: executeAnalysisWorkflow(workflow, i + 1, this.deps),
+                });
+            }
+        }
+
+        for (const workflow of testingWorkflows) {
+            if (this.inFlightSlugs.has(workflow.slug)) {
+                results.push({ slug: workflow.slug, runNumber: 0, status: "rejected", error: "already running" });
+                continue;
+            }
+            this.inFlightSlugs.add(workflow.slug);
+            for (let i = 0; i < workflow.runs; i++) {
+                runs.push({
+                    slug: workflow.slug,
+                    runNumber: i + 1,
+                    promise: executeTestingWorkflow(workflow, i + 1, this.deps),
+                });
+            }
+        }
+
+        // Execute all non-rejected runs in parallel
+        const settled = await Promise.allSettled(runs.map((r) => r.promise));
+
+        // Collect results and clear in-flight tracking
+        const completedSlugs = new Set<string>();
+        for (let i = 0; i < settled.length; i++) {
+            const run = runs[i]!;
+            const outcome = settled[i]!;
+            completedSlugs.add(run.slug);
+            if (outcome.status === "fulfilled") {
+                results.push({ slug: run.slug, runNumber: run.runNumber, status: "succeeded" });
+            } else {
+                const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+                console.warn(`Workflow '${run.slug}' run ${run.runNumber} failed:`, outcome.reason);
+                results.push({ slug: run.slug, runNumber: run.runNumber, status: "failed", error: errorMsg });
+            }
+        }
+
+        // Remove completed slugs from in-flight set
+        for (const slug of completedSlugs) {
+            this.inFlightSlugs.delete(slug);
+        }
+
+        return results;
+    }
+
+    /** Clear output files. If slugs provided, only clear matching filenames. */
+    clearResults(slugFilter?: string[]): void {
+        this.outputViewer.clearFiles(slugFilter);
+    }
+
+    /** Return current engine state snapshot. */
+    getStatus(): EngineStatus {
+        return {
+            inFlight: [...this.inFlightSlugs],
+            completedFiles: this.outputViewer.getFileList().map((f) => f.name),
+        };
+    }
+
+    /** List all configured workflow slugs grouped by type. */
+    listWorkflows(): { analysis: string[]; testing: string[] } {
+        return {
+            analysis: this.config.analysis_workflows.map((w) => w.slug),
+            testing: this.config.testing_workflows.map((w) => w.slug),
+        };
+    }
+
+    /** Apply --only / --skip filters to a workflow list. */
+    private applyFilters<T extends { slug: string }>(workflows: T[], onlySlugs?: string[], skipSlugs?: string[]): T[] {
+        let filtered = workflows;
+        if (onlySlugs && onlySlugs.length > 0) {
+            filtered = filtered.filter((w) => {
+                if (onlySlugs.includes(w.slug)) {
+                    return true;
+                }
+                console.log(`Skipping workflow '${w.slug}' (not in --only_workflows list)`);
+                return false;
+            });
+        }
+        if (skipSlugs && skipSlugs.length > 0) {
+            filtered = filtered.filter((w) => {
+                if (skipSlugs.includes(w.slug)) {
+                    console.log(`Skipping workflow '${w.slug}' (matched --skip_workflow)`);
+                    return false;
+                }
+                return true;
+            });
+        }
+        return filtered;
+    }
+}

package/src/engine/index.ts

@@ -0,0 +1,2 @@
+export { Engine } from "./engine.ts";
+export type { WorkflowRunResult, EngineStatus } from "./engine.ts";

package/src/hosts/cli-host.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+
+import "../version.ts";
+
+import { createInterface } from "node:readline";
+
+import chalk from "chalk";
+
+import { ARGS } from "../util/args.ts";
+import { CONFIG } from "../util/config.ts";
+import { Engine } from "../engine/index.ts";
+import { parseAndExecute, COMMAND_NAMES } from "../command-handler.ts";
+import { startApiServer } from "../api-server.ts";
+import { OutputViewingModeEnum } from "../util/config-schema.ts";
+
+
+const engine = new Engine(CONFIG);
+
+// --- Start API server (WebUI mode) or skip (Local mode) ---
+let apiServerHandle: { url: string; stop: () => void } | null = null;
+let frontendURL = "";
+
+if (CONFIG.output_viewing.mode === OutputViewingModeEnum.WebUI) {
+    apiServerHandle = startApiServer(engine, CONFIG.output_viewing.api_port);
+    const params = new URLSearchParams();
+    params.set("api", apiServerHandle.url);
+    frontendURL = `${CONFIG.output_viewing.webui_base_url}/tools/results-viewer#${params.toString()}`;
+
+    console.log(chalk.cyan("Open the following URL to view all outputs:"));
+    console.log(frontendURL);
+}
+
+// --- Initial workflow run (same as old cli.ts) ---
+const onlySlugs: string[] | undefined = ARGS.values.only_workflows;
+const skipSlugs: string[] | undefined = ARGS.values.skip_workflow;
+
+const initialResults = await engine.runWorkflows({
+    only: onlySlugs,
+    skip: skipSlugs,
+});
+
+// Print summary of initial run
+const succeeded = initialResults.filter((r) => r.status === "succeeded").length;
+const failed = initialResults.filter((r) => r.status === "failed").length;
+console.log(`\nInitial run complete. Succeeded: ${succeeded}; Failed: ${failed}`);
+if (failed > 0) {
+    for (const r of initialResults.filter((r) => r.status === "failed")) {
+        console.warn(`  Workflow '${r.slug}' failed: ${r.error ?? "unknown"}`);
+    }
+}
+
+// In Local mode, print per-file links after initial run
+if (CONFIG.output_viewing.mode === OutputViewingModeEnum.Local) {
+    const files = engine.outputViewer.getFileList();
+    if (files.length > 0) {
+        console.log("\nClick the following links to view the outputs in your browser:");
+        for (const file of files) {
+            const record = engine.outputViewer.getFile(file.name);
+            if (record) {
+                const params = new URLSearchParams();
+                params.set("name", file.name);
+                params.set("comp", "gzip");
+                params.set("data", Bun.gzipSync(record.content).toBase64());
+                const url = `${CONFIG.output_viewing.webui_base_url}/tools/results-viewer#${params.toString()}`;
+                console.log(`${chalk.cyan(file.name)}: ${url}\n`);
+            }
+        }
+    } else {
+        console.warn("No files to display.");
+    }
+}
+
+// --- Tab-completion ---
+function completer(line: string): [string[], string] {
+    const trimmed = line.trimStart();
+    const parts = trimmed.split(/\s+/);
+
+    // Completing the command name (first token)
+    if (parts.length <= 1) {
+        const hits = COMMAND_NAMES.filter((c) => c.startsWith(trimmed.toLowerCase()));
+        return [hits, trimmed];
+    }
+
+    // Completing workflow slugs for "run" and "clear"
+    const command = parts[0]!.toLowerCase();
+    if (command === "run" || command === "clear") {
+        const partial = parts[parts.length - 1]!;
+        const workflows = engine.listWorkflows();
+        const allSlugs = [...workflows.analysis, ...workflows.testing];
+        const hits = allSlugs.filter((s) => s.startsWith(partial));
+        return [hits, partial];
+    }
+
+    return [[], line];
+}
+
+// --- REPL loop ---
+const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: chalk.green("epf> "),
+    completer,
+});
+
+console.log(chalk.gray("\nInteractive mode. Type 'help' for commands, 'exit' to quit.\n"));
+rl.prompt();
+
+rl.on("line", async (line: string) => {
+    const result = await parseAndExecute(engine, line);
+
+    if (result.kind === "exit") {
+        console.log(result.message);
+        rl.close();
+        return;
+    }
+
+    if (result.message.length > 0) {
+        if (result.kind === "error") {
+            console.error(chalk.red(result.message));
+        } else {
+            console.log(result.message);
+        }
+    }
+
+    rl.prompt();
+});
+
+rl.on("close", () => {
+    console.log(chalk.gray("Goodbye."));
+    if (apiServerHandle) {
+        apiServerHandle.stop();
+    }
+    process.exit(0);
+});
+
+// Graceful Ctrl+C handling
+process.on("SIGINT", () => {
+    console.log(chalk.gray("\nReceived SIGINT."));
+    rl.close();
+});

package/src/util/args.ts

@@ -1,4 +1,4 @@
-import {parseArgs} from "util";
+import { parseArgs } from "util";
 
 // console.log(Bun.argv);
 export const ARGS = parseArgs({
@@ -23,6 +23,11 @@ export const ARGS = parseArgs({
             short: "S",
             multiple: true,
         },
+        only_workflows: {
+            type: "string",
+            short: "O",
+            multiple: true,
+        },
         completion_inputs_destination: {
             type: "string",
         },

package/src/util/config-schema.ts

@@ -1,4 +1,4 @@
-import {z} from "zod";
+import { z } from "zod";
 
 export enum OutputViewingModeEnum {
     Local = "local",
@@ -20,6 +20,8 @@ export const ModelConfigSchema = z.object({
     frequency_penalty: z.number().min(-2).max(2).default(0),
     presence_penalty: z.number().min(-2).max(2).default(0),
     reasoning_effort: z.enum(["low", "medium", "high"]).default("high"),
+    max_retries: z.number().min(0).default(1),  // 0 for no retry
+    retry_delay_ms: z.number().min(0).default(1000),
 });
 
 export const LLMConfigSchema = z.object({
@@ -45,7 +47,7 @@ export const AnalysisWorkflowEntrySchema = BaseWorkflowEntrySchema.extend({
     prompt: z.string(),
 })
 
-export enum LLMJudgeInputModeEnum{
+export enum LLMJudgeInputModeEnum {
     None = "NONE",
     Diff = "DIFF",
     Full = "FULL",

package/src/util/config.ts

@@ -11,7 +11,7 @@ const homeDir: string = os.homedir();
 const defaultConfigFileName = "epf.toml";
 const configURLEnvVar = "EPF_CONFIG_URL";
 
-type Config = z.infer<typeof ConfigSchema>;
+export type Config = z.infer<typeof ConfigSchema>;
 
 async function readConfig() {
     console.log(`Loading config`);

package/src/util/llm.ts

@@ -1,46 +1,49 @@
-import type {SystemMessage, UserMessage} from "@openrouter/sdk/models";
+import type {ChatSystemMessage, ChatUserMessage} from "@openrouter/sdk/models";
 
 import {CONFIG} from "./config.ts";
 import type {WorkflowDependencies} from "../workflow";
 import {recordCompletionInput} from "./eval-harness.ts";
 
 
+async function delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 export async function generateCompletion(deps: WorkflowDependencies,
                                          log: (..._: any[])=>void,
                                          warn: (..._: any[])=>void,
                                          model: string,
                                          systemPrompt: string,
-                                         content: UserMessage["content"]) {
+                                         content: ChatUserMessage["content"]) {
     let modelSettings = CONFIG.llm.models[model];
     if (!modelSettings) {
         throw new Error(`No model settings found for model "${model}"`);
     }
-    
+
     let replacedCount = 0;
     for (const [replacementKey, replacementValue] of Object.entries(CONFIG.llm.prompt_replacement)) {
-        if (systemPrompt.includes(replacementKey)) {replacedCount++}
+        if (systemPrompt.includes(replacementKey)) {replacedCount++;}
         systemPrompt = systemPrompt.replaceAll(`{{${replacementKey}}}`, replacementValue);
         if (typeof content === "string") {
-            if (content.includes(replacementKey)) {replacedCount++}
+            if (content.includes(replacementKey)) {replacedCount++;}
             content = content.replaceAll(`{{${replacementKey}}}`, replacementValue);
         }
         else {
             for (let i = 0; i < content.length; i++) {
                 const element = content[i];
                 if (element && "type" in element && element.type === "text" && typeof element.text === "string") {
-                    if (element.text.includes(replacementKey)) {replacedCount++}
+                    if (element.text.includes(replacementKey)) {replacedCount++;}
                     content[i] = {
                         ...element,
                         text: element.text.replaceAll(`{{${replacementKey}}}`, replacementValue),
-                    }
+                    };
                 }
             }
-            
         }
     }
     log(`Replaced ${replacedCount} instances of prompt variables in system prompt and content`);
-    
-    let messages: (SystemMessage | UserMessage)[] = [
+
+    let messages: (ChatSystemMessage | ChatUserMessage)[] = [
         {
             role: "system",
             content: systemPrompt,
@@ -51,30 +54,64 @@ export async function generateCompletion(deps: WorkflowDependencies,
         }
     ];
     setTimeout(async ()=> await recordCompletionInput(messages), 5);
-    
-    log("Sending chat completion request...");
-    let startTime = Date.now();
-    let completion = await deps.openRouter.chat.send({
-        model: modelSettings.model_name,
-        maxCompletionTokens: modelSettings.max_completion_tokens,
-        messages: messages,
-        stream: false,
-        seed: deps.seed,
-        frequencyPenalty: modelSettings.frequency_penalty,
-        presencePenalty: modelSettings.presence_penalty,
-        temperature: modelSettings.temperature,
-        reasoning: {
-            effort: modelSettings.reasoning_effort,
-        },
-    });
-    log(`Completion response generated in ${(Date.now() - startTime) / 1000} seconds`);
-    if (completion.choices.length < 1){
-        warn("No choices returned from completion");
-        console.log(completion);
+
+    const maxRetries = modelSettings.max_retries;
+    const retryDelayMs = modelSettings.retry_delay_ms;
+    const totalAttempts = maxRetries + 1;
+
+    let lastError: unknown = null;
+
+    for (let attempt = 0; attempt < totalAttempts; attempt++) {
+        const attemptLabel = `${attempt + 1}/${totalAttempts}`;
+
+        if (attempt > 0) {
+            const backoffMs = retryDelayMs * (2 ** (attempt - 1)) + Math.random() * 200;
+            warn(`Retrying after ${Math.round(backoffMs)}ms (attempt ${attemptLabel})...`);
+            await delay(backoffMs);
+        }
+
+        log(`Sending chat completion request (attempt ${attemptLabel})...`);
+        let startTime = Date.now();
+
+        try {
+            let completion = await deps.openRouter.chat.send({chatRequest: {
+                model: modelSettings.model_name,
+                maxCompletionTokens: modelSettings.max_completion_tokens,
+                messages: messages,
+                stream: false,
+                seed: deps.seed,
+                frequencyPenalty: modelSettings.frequency_penalty,
+                presencePenalty: modelSettings.presence_penalty,
+                temperature: modelSettings.temperature,
+                reasoning: {
+                    effort: modelSettings.reasoning_effort,
+                },
+            }});
+            log(`Completion response received in ${(Date.now() - startTime) / 1000}s (attempt ${attemptLabel})`);
+
+            const text = completion.choices[0]?.message.content?.toString() ?? "";
+
+            if (completion.choices.length < 1 || text.length === 0) {
+                warn(`Empty completion on attempt ${attemptLabel}`);
+                console.log(completion);
+                // Retry if attempts remain; otherwise return empty
+                if (attempt < maxRetries) {
+                    continue;
+                }
+                warn("Exhausted all retries — returning empty completion");
+                return {text: "", model: completion.model};
+            }
+
+            return {text, model: completion.model};
+
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warn(`Chat completion error on attempt ${attemptLabel}: ${message}`);
+            lastError = error;
+            // Loop continues to next attempt (or exits if this was the last)
+        }
     }
-    
-    return {
-        text: completion.choices[0]?.message.content?.toString() ?? "",
-        model: completion.model,
-    };
+
+    warn("Exhausted all retries due to errors — re-throwing last error");
+    throw lastError;
 }

package/src/util/output-viewer.ts

@@ -1,119 +1,56 @@
-import chalk from "chalk";
-
-import {CONFIG} from "./config.ts";
-import {OutputViewingModeEnum} from "./config-schema.ts";
-
 type FileRecord = {
     type: "markdown" | "text";
     content: string;
-}
-
-const CORS_HEADERS = {
-    "Access-Control-Allow-Origin": "*",
-    "Access-Control-Allow-Methods": "GET, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type",
+    modification_time: Date;
 };
 
-function jsonResponse(data: unknown, status = 200): Response {
-    return new Response(JSON.stringify(data), {
-        status,
-        headers: {
-            "Content-Type": "application/json",
-            ...CORS_HEADERS,
-        },
-    });
-}
-
+/**
+ * Pure data store for workflow output files.
+ * Persists across multiple workflow runs so that re-runs append/overwrite
+ * rather than starting from scratch.
+ *
+ * The HTTP serving layer lives in ApiServer (src/api-server.ts).
+ */
 export class OutputViewer {
-    filesRecords: Record<string, FileRecord> = {};
-    displayed: boolean = false;
-    
-    addFile(filename: string, _: FileRecord): void {
-        this.filesRecords[filename] = _;
-    }
-    
-    serve(): string {
-        let files = Object.entries(this.filesRecords).sort((a, b) => a[0].localeCompare(b[0]));
-        
-        let server = Bun.serve({
-            port: CONFIG.output_viewing.api_port,
-            routes: {
-                "/": (req) => {
-                    if (req.method === "OPTIONS") {
-                        return new Response(null, { status: 204, headers: CORS_HEADERS });
-                    }
-                    return jsonResponse({
-                        files: files.map(([filename, fileRecord]) => ({
-                            name: filename,
-                            type: fileRecord.type,
-                        })),
-                    });
-                },
-                "/:slug": (req) => {
-                    if (req.method === "OPTIONS") {
-                        return new Response(null, { status: 204, headers: CORS_HEADERS });
-                    }
-                    let slug = req.params.slug;
-                    let record = this.filesRecords[slug];
-                    if (!record) {
-                        return jsonResponse({ error: "Not Found" }, 404);
-                    }
-                    return jsonResponse({
-                        name: slug,
-                        type: record.type,
-                        content: record.content,
-                    });
-                }
-            },
-            fetch(req) {
-                if (req.method === "OPTIONS") {
-                    return new Response(null, { status: 204, headers: CORS_HEADERS });
-                }
-                return jsonResponse({ error: "Not Found" }, 404);
-            },
-        });
-        console.log(server.url);
-        return server.url.toString();
+    fileRecords: Record<string, FileRecord> = {};
+
+    async addFile(filename: string, fileRecord: Omit<FileRecord, "modification_time">): Promise<void> {
+        await Bun.write(filename, fileRecord.content);
+        this.fileRecords[filename] = {
+            ...fileRecord,
+            modification_time: new Date(),
+        };
     }
-    
-    display() {
-        let frontendURL = "";
-        switch (CONFIG.output_viewing.mode) {
-            case OutputViewingModeEnum.Local:
-                if (Object.keys(this.filesRecords).length === 0) {
-                    console.warn("No files to display (you can probably ignore this warning if your workflows haven't completed yet)");
-                    return;
-                }
-                
-                console.log("Click the following links to view the outputs in your browser:");
-                
-                let files = Object.entries(this.filesRecords).sort((a, b) => a[0].localeCompare(b[0]));
-                for (const [filename, fileRecord] of files) {
-                    let params = new URLSearchParams();
-                    params.set("name", filename);
-                    params.set("comp", "gzip");
-                    params.set("data", Bun.gzipSync(fileRecord.content).toBase64());
-                    frontendURL = `${CONFIG.output_viewing.webui_base_url}/tools/results-viewer#${params.toString()}`;
-                    console.log(`${chalk.cyan(filename)}: ${frontendURL}` + "\n");
-                }
-                break
-            case OutputViewingModeEnum.WebUI:
-                if (this.displayed){
-                    console.log("Output viewer API is already running");
-                    console.log(frontendURL + "\n");
-                    console.log("Press Ctrl+C to stop")
-                    return;
-                }
-                this.displayed = true;
-                let apiURL = this.serve();
-                let params = new URLSearchParams();
-                params.set("api", apiURL);
-                frontendURL = `${CONFIG.output_viewing.webui_base_url}/tools/results-viewer#${params.toString()}`;
-                
-                console.log(chalk.cyan("Open the following URL to view all outputs:"));
-                console.log(frontendURL);
-                console.log("Press Ctrl+C to stop the server")
+
+    /**
+     * Remove files matching the given slug substrings.
+     * If no filter is provided (or empty array), clear everything.
+     */
+    clearFiles(slugFilter?: string[]): void {
+        if (!slugFilter || slugFilter.length === 0) {
+            this.fileRecords = {};
+            return;
         }
-        
+        for (const key of Object.keys(this.fileRecords)) {
+            if (slugFilter.some((s) => key.includes(s))) {
+                delete this.fileRecords[key];
+            }
+        }
+    }
+
+    /** Return the sorted list of files (metadata only, no content). */
+    getFileList(): { name: string; type: string; modification_time: Date }[] {
+        return Object.entries(this.fileRecords)
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([filename, record]) => ({
+                name: filename,
+                type: record.type,
+                modification_time: record.modification_time,
+            }));
+    }
+
+    /** Return a single file's record, or null if not found. */
+    getFile(slug: string): FileRecord | null {
+        return this.fileRecords[slug] ?? null;
     }
 }

package/src/workflow/analysis-workflow.ts

@@ -1,11 +1,11 @@
-import {Glob} from "bun";
+import { Glob } from "bun";
 
 import chalk from "chalk";
 
-import {CONFIG} from "../util/config.ts";
-import {FilePayloadGenerator} from "../util/file-payload.ts";
-import type {WorkflowDependencies} from "./index.ts";
-import {generateCompletion} from "../util/llm.ts";
+import { CONFIG } from "../util/config.ts";
+import { FilePayloadGenerator } from "../util/file-payload.ts";
+import type { WorkflowDependencies } from "./index.ts";
+import { generateCompletion } from "../util/llm.ts";
 
 
 export async function executeAnalysisWorkflow(workflow: typeof CONFIG.analysis_workflows[number], runNum: number, deps: WorkflowDependencies) {
@@ -16,7 +16,7 @@ export async function executeAnalysisWorkflow(workflow: typeof CONFIG.analysis_w
     const warn = (...args: Parameters<typeof console.warn>) => {
         console.warn(chalk.red(`[${workflow.slug}]`), ...args);
     }
-    
+
     let allFiles = (
         await Promise.all(
             workflow.input_files_searches.map(async (fileSearch) => {
@@ -35,7 +35,7 @@ export async function executeAnalysisWorkflow(workflow: typeof CONFIG.analysis_w
             })
         )
     ).flat();
-    
+
     if (allFiles.length === 0) {
         warn(`No files found for workflow, skipping...`);
         return;
@@ -54,7 +54,7 @@ export async function executeAnalysisWorkflow(workflow: typeof CONFIG.analysis_w
         .replaceAll("[slug]", workflow.slug)
         .replaceAll("[model]", `(${completion.model.replaceAll("/", "--")})`)
         .replaceAll("[run]", runNum.toString());
-    await Bun.write(outputFileName, completion.text);
-    log(`Completion written to ${outputFileName}`);
-    deps.outputViewer.addFile(outputFileName, {type: "markdown", content: completion.text});
+
+    await deps.outputViewer.addFile(outputFileName, { type: "markdown", content: completion.text });
+    log(`Completion saved as ${outputFileName}`);
 }

package/src/cli.ts

@@ -1,59 +0,0 @@
-#!/usr/bin/env bun
-
-import "./version.ts";
-
-import {OpenRouter} from "@openrouter/sdk";
-
-import {CONFIG} from "./util/config.ts";
-import {executeTestingWorkflow} from "./workflow/testing-workflow.ts";
-import {executeAnalysisWorkflow} from "./workflow/analysis-workflow.ts";
-import type {WorkflowDependencies} from "./workflow";
-import {OutputViewer} from "./util/output-viewer.ts";
-
-
-const workflowDependencies: WorkflowDependencies = {
-    seed: Math.floor(Date.now() / 1000),
-    openRouter: new OpenRouter({
-        apiKey: CONFIG.vendors.openrouter.api_key,
-    }),
-    outputViewer: new OutputViewer(),
-}
-
-// Parallelize workflows with Promise.allSettled
-const analysisWorkflows = CONFIG.analysis_workflows;
-const testingWorkflows = CONFIG.testing_workflows;
-console.log(`Starting execution of ${analysisWorkflows.length} workflows...`);
-console.log(analysisWorkflows.map((w) => w.slug));
-let workflowRuns: Promise<void>[] = [];
-analysisWorkflows.forEach((workflow) => {
-    for (let i = 0; i < workflow.runs; i++) {
-        workflowRuns.push(executeAnalysisWorkflow(workflow, i+1, workflowDependencies));
-    }
-});
-testingWorkflows.forEach((workflow) => {
-    for (let i = 0; i < workflow.runs; i++) {
-        workflowRuns.push(executeTestingWorkflow(workflow, i+1, workflowDependencies));
-    }
-});
-workflowDependencies.outputViewer.display();  // For start the server early.
-const workflowsResults = await Promise.allSettled(workflowRuns);
-// Summarize with indices to include slugs in failure logs
-const failedIndices: number[] = [];
-const succeededIndices: number[] = [];
-workflowsResults.forEach((r, i) => {
-    if (r.status === "rejected") failedIndices.push(i);
-    else succeededIndices.push(i);
-});
-
-console.log(`Workflows completed. Succeeded: ${succeededIndices.length}; Failed: ${failedIndices.length}`);
-if (failedIndices.length > 0) {
-    failedIndices.forEach((i) => {
-        const r = workflowsResults[i] as PromiseRejectedResult;
-        const slug = analysisWorkflows[i]?.slug ?? `#${i + 1}`;
-        console.warn(`Workflow '${slug}' failed:`, r.reason);
-    });
-}
-
-workflowDependencies.outputViewer.display();
-
-console.log("index.ts done");