@10et/cli 1.0.0

package/dist/lib/agent-guards.js

@@ -0,0 +1,229 @@
+/**
+ * Agent Guards
+ *
+ * Pre-flight checks that run before an agent session starts.
+ * Implements the TOCTOU guard pattern used elsewhere (hub-health.ts, planning-loop.ts)
+ * but scoped to the agent runner lifecycle.
+ *
+ * Guards are composable: each returns a GuardResult, and runGuards() aggregates them.
+ * Non-critical guards warn but don't block; critical guards abort the session.
+ *
+ * @purpose Pre-flight guard checks for scoped agent runner sessions
+ * @invariant HubRequiredForScheduling (SystemSpec.tla)
+ */
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { spawnSync } from "child_process";
+// ============================================================================
+// Individual Guards
+// ============================================================================
+/**
+ * Guard: Hub must be reachable before starting an agent session.
+ * Critical: false — agents can run without hub, but results won't be tracked.
+ *
+ * Re-implements the TOCTOU pattern from hub-health.ts for the agent runner path.
+ */
+export async function guardHub(projectRoot) {
+    try {
+        const { checkHubHealth } = await import("./hub-health.js");
+        const status = await checkHubHealth(projectRoot);
+        if (status.available) {
+            return {
+                name: "hub",
+                passed: true,
+                critical: false,
+            };
+        }
+        return {
+            name: "hub",
+            passed: false,
+            critical: false,
+            reason: `Hub unavailable (${status.error}). Agent will run but results won't be tracked.`,
+        };
+    }
+    catch {
+        return {
+            name: "hub",
+            passed: false,
+            critical: false,
+            reason: "Hub health check unavailable. Agent will run but results won't be tracked.",
+        };
+    }
+}
+/**
+ * Guard: No concurrent session for the same agent.
+ * Critical: true — running two sessions on the same agent causes git conflicts.
+ */
+export function guardNoConcurrentSession(projectRoot, agentName) {
+    const sessionsDir = join(projectRoot, ".jfl", "sessions");
+    if (!existsSync(sessionsDir)) {
+        return { name: "concurrent_session", passed: true, critical: true };
+    }
+    let entries;
+    try {
+        entries = readdirSync(sessionsDir);
+    }
+    catch {
+        return { name: "concurrent_session", passed: true, critical: true };
+    }
+    for (const entry of entries) {
+        // Only check sessions for this specific agent
+        if (!entry.startsWith(`${agentName}-`))
+            continue;
+        const statePath = join(sessionsDir, entry, "state.json");
+        if (!existsSync(statePath))
+            continue;
+        try {
+            const state = JSON.parse(readFileSync(statePath, "utf-8"));
+            if (state.status === "active") {
+                // Check if the worktree still exists (session might be stale)
+                if (state.worktreePath && existsSync(state.worktreePath)) {
+                    return {
+                        name: "concurrent_session",
+                        passed: false,
+                        critical: true,
+                        reason: `Agent "${agentName}" has an active session: ${entry}. ` +
+                            `Worktree: ${state.worktreePath}. ` +
+                            `If this is stale, remove it: rm -rf ${state.worktreePath} && rm -rf ${join(sessionsDir, entry)}`,
+                    };
+                }
+                // Worktree doesn't exist — session is stale, mark it as completed
+                // (don't block — just note it)
+            }
+        }
+        catch {
+            // Corrupted state file — skip
+        }
+    }
+    return { name: "concurrent_session", passed: true, critical: true };
+}
+/**
+ * Guard: Eval script and data files must exist.
+ * Critical: true — agent can't measure improvement without eval.
+ */
+export function guardEvalReady(projectRoot, config) {
+    const errors = [];
+    const evalScriptPath = join(projectRoot, config.eval.script);
+    if (!existsSync(evalScriptPath)) {
+        errors.push(`Eval script not found: ${config.eval.script}`);
+    }
+    const evalDataPath = join(projectRoot, config.eval.data);
+    if (!existsSync(evalDataPath)) {
+        errors.push(`Eval data not found: ${config.eval.data}`);
+    }
+    if (errors.length > 0) {
+        return {
+            name: "eval_ready",
+            passed: false,
+            critical: true,
+            reason: errors.join("; "),
+        };
+    }
+    return { name: "eval_ready", passed: true, critical: true };
+}
+/**
+ * Guard: No stale worktree for this agent.
+ * Critical: true — stale worktrees cause git worktree add to fail.
+ */
+export function guardWorktreeClean(projectRoot, agentName) {
+    // Check for stale /tmp worktrees matching this agent
+    const result = spawnSync("git", ["worktree", "list", "--porcelain"], {
+        cwd: projectRoot,
+        encoding: "utf-8",
+        stdio: "pipe",
+    });
+    if (result.status !== 0) {
+        // Can't check worktrees — don't block
+        return { name: "worktree_clean", passed: true, critical: true };
+    }
+    const lines = (result.stdout || "").split("\n");
+    const staleWorktrees = [];
+    for (const line of lines) {
+        if (line.startsWith("worktree ")) {
+            const worktreePath = line.replace("worktree ", "").trim();
+            // Match agent worktrees in /tmp
+            if (worktreePath.includes(`jfl-agent-${agentName}-`)) {
+                // Check if the directory actually exists
+                if (!existsSync(worktreePath)) {
+                    staleWorktrees.push(worktreePath);
+                }
+            }
+        }
+    }
+    if (staleWorktrees.length > 0) {
+        // Auto-prune stale worktrees — they're just git bookkeeping for deleted /tmp dirs
+        spawnSync("git", ["worktree", "prune"], {
+            cwd: projectRoot,
+            stdio: "pipe",
+        });
+        // Re-check after pruning
+        const recheck = spawnSync("git", ["worktree", "list", "--porcelain"], {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            stdio: "pipe",
+        });
+        const recheckLines = (recheck.stdout || "").split("\n");
+        const remaining = recheckLines.filter((l) => l.startsWith("worktree ") && l.includes(`jfl-agent-${agentName}-`));
+        if (remaining.length > 0) {
+            const paths = remaining.map((l) => l.replace("worktree ", "").trim());
+            return {
+                name: "worktree_clean",
+                passed: false,
+                critical: true,
+                reason: `Stale worktrees found for agent "${agentName}": ${paths.join(", ")}. ` +
+                    `Clean up with: git worktree remove <path> --force`,
+            };
+        }
+    }
+    return { name: "worktree_clean", passed: true, critical: true };
+}
+/**
+ * Guard: Git repo must be in a clean state for the base branch.
+ * Critical: false — uncommitted changes are stashed by agent-session.
+ */
+export function guardGitClean(projectRoot) {
+    const result = spawnSync("git", ["status", "--porcelain"], {
+        cwd: projectRoot,
+        encoding: "utf-8",
+        stdio: "pipe",
+    });
+    const output = (result.stdout || "").trim();
+    if (output) {
+        return {
+            name: "git_clean",
+            passed: false,
+            critical: false,
+            reason: `Uncommitted changes in working directory (${output.split("\n").length} files). ` +
+                `These may conflict with agent worktree creation.`,
+        };
+    }
+    return { name: "git_clean", passed: true, critical: false };
+}
+// ============================================================================
+// Guard Runner
+// ============================================================================
+/**
+ * Run all guards for an agent session.
+ * Returns a summary with proceed/blockers/warnings.
+ */
+export async function runGuards(projectRoot, agentName, config) {
+    const results = [];
+    // Run all guards (async hub guard + sync guards)
+    const [hubResult] = await Promise.all([
+        guardHub(projectRoot),
+    ]);
+    results.push(hubResult);
+    results.push(guardNoConcurrentSession(projectRoot, agentName));
+    results.push(guardEvalReady(projectRoot, config));
+    results.push(guardWorktreeClean(projectRoot, agentName));
+    results.push(guardGitClean(projectRoot));
+    const blockers = results.filter((r) => !r.passed && r.critical);
+    const warnings = results.filter((r) => !r.passed && !r.critical);
+    return {
+        proceed: blockers.length === 0,
+        results,
+        blockers,
+        warnings,
+    };
+}
+//# sourceMappingURL=agent-guards.js.map

package/dist/lib/agent-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-guards.js","sourceRoot":"","sources":["../../src/lib/agent-guards.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent-manifest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @purpose Agent manifest types and scaffold generator for narrowly-scoped agents
+ */
+export interface AgentManifest {
+    name: string;
+    version: string;
+    description: string;
+    type: "reactive" | "scheduled" | "hybrid";
+    triggers: AgentTrigger[];
+    capabilities: string[];
+    runtime: AgentRuntime;
+}
+export interface AgentTrigger {
+    pattern?: string;
+    schedule?: string;
+}
+export interface AgentRuntime {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+}
+export interface AgentPolicy {
+    cost_limit_usd: number;
+    approval_gate: "auto" | "manual";
+    allowed_actions: string[];
+    blocked_actions: string[];
+    max_concurrent: number;
+    cooldown_seconds: number;
+}
+export declare function generateManifest(name: string, description?: string): string;
+export declare function generatePolicy(): string;
+export declare function generateLifecycle(name: string, triggerPattern: string): string;
+export declare function parseManifest(content: string): AgentManifest | null;
+//# sourceMappingURL=agent-manifest.d.ts.map

package/dist/lib/agent-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manifest.d.ts","sourceRoot":"","sources":["../../src/lib/agent-manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAA;IACzC,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,OAAO,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAA;IAChC,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAoB3E;AAED,wBAAgB,cAAc,IAAI,MAAM,CAUvC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CA4B9E;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAOnE"}

package/dist/lib/agent-manifest.js

@@ -0,0 +1,75 @@
+/**
+ * @purpose Agent manifest types and scaffold generator for narrowly-scoped agents
+ */
+import { stringify as stringifyYaml } from "yaml";
+export function generateManifest(name, description) {
+    const manifest = {
+        name,
+        version: "0.1.0",
+        description: description || `${name} agent`,
+        type: "reactive",
+        triggers: [
+            { pattern: "session:ended" },
+        ],
+        capabilities: [
+            "read_telemetry",
+            "write_journal",
+        ],
+        runtime: {
+            command: "claude",
+            args: ["-p", `Run ${name} agent tasks`],
+            cwd: "{{project_root}}",
+        },
+    };
+    return stringifyYaml(manifest, { lineWidth: 120 });
+}
+export function generatePolicy() {
+    const policy = {
+        cost_limit_usd: 0.50,
+        approval_gate: "auto",
+        allowed_actions: ["log", "emit", "journal", "command"],
+        blocked_actions: ["spawn"],
+        max_concurrent: 1,
+        cooldown_seconds: 300,
+    };
+    return JSON.stringify(policy, null, 2);
+}
+export function generateLifecycle(name, triggerPattern) {
+    const lifecycle = {
+        flows: [
+            {
+                name: `${name}-trigger`,
+                description: `Trigger ${name} agent on matching events`,
+                enabled: true,
+                trigger: {
+                    pattern: triggerPattern,
+                },
+                actions: [
+                    {
+                        type: "log",
+                        message: `[${name}] Triggered by {{type}} from {{source}}`,
+                    },
+                    {
+                        type: "emit",
+                        event_type: "agent:started",
+                        data: {
+                            agent: name,
+                            trigger_event: "{{id}}",
+                        },
+                    },
+                ],
+            },
+        ],
+    };
+    return stringifyYaml(lifecycle, { lineWidth: 120 });
+}
+export function parseManifest(content) {
+    try {
+        const { parse } = require("yaml");
+        return parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=agent-manifest.js.map

package/dist/lib/agent-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manifest.js","sourceRoot":"","sources":["../../src/lib/agent-manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAA;AAiCjD,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,WAAoB;IACjE,MAAM,QAAQ,GAAkB;QAC9B,IAAI;QACJ,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE,WAAW,IAAI,GAAG,IAAI,QAAQ;QAC3C,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,EAAE,OAAO,EAAE,eAAe,EAAE;SAC7B;QACD,YAAY,EAAE;YACZ,gBAAgB;YAChB,eAAe;SAChB;QACD,OAAO,EAAE;YACP,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,IAAI,cAAc,CAAC;YACvC,GAAG,EAAE,kBAAkB;SACxB;KACF,CAAA;IACD,OAAO,aAAa,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,MAAM,MAAM,GAAgB;QAC1B,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,MAAM;QACrB,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC;QACtD,eAAe,EAAE,CAAC,OAAO,CAAC;QAC1B,cAAc,EAAE,CAAC;QACjB,gBAAgB,EAAE,GAAG;KACtB,CAAA;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,cAAsB;IACpE,MAAM,SAAS,GAAG;QAChB,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,GAAG,IAAI,UAAU;gBACvB,WAAW,EAAE,WAAW,IAAI,2BAA2B;gBACvD,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP,OAAO,EAAE,cAAc;iBACxB;gBACD,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,KAAK;wBACX,OAAO,EAAE,IAAI,IAAI,yCAAyC;qBAC3D;oBACD;wBACE,IAAI,EAAE,MAAM;wBACZ,UAAU,EAAE,eAAe;wBAC3B,IAAI,EAAE;4BACJ,KAAK,EAAE,IAAI;4BACX,aAAa,EAAE,QAAQ;yBACxB;qBACF;iBACF;aACF;SACF;KACF,CAAA;IACD,OAAO,aAAa,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAA;AACrD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAC,OAAO,CAAkB,CAAA;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/lib/agent-runtime-api.d.ts

@@ -0,0 +1,32 @@
+/**
+ * API-based agent runtime — replaces spawn('claude') with Anthropic API + tool_use.
+ *
+ * WHY: Every spawn('claude') creates a ~300MB node process. macOS compresses dead
+ * pages instead of freeing them. 20 rounds/night = 6GB compressed memory that's
+ * unreclaimable without reboot. This replaces N process spawns with N HTTP calls
+ * from a single long-lived process. Zero memory churn.
+ *
+ * Tools: read_file, write_file, list_files, bash (same capabilities as claude CLI)
+ * Model: claude-sonnet-4-20250514 (fast, cheap, good enough for focused edits)
+ *
+ * @purpose API-based agent runtime — zero memory churn replacement for spawn('claude')
+ */
+interface AgentRuntimeOptions {
+    task: string;
+    cwd: string;
+    timeoutMs: number;
+    maxTurns?: number;
+    model?: string;
+}
+/**
+ * Run an agent round via Anthropic API with tool_use.
+ * Single HTTP conversation — no process spawning.
+ * Replaces spawnClaudeCli() and spawnAgentRuntime().
+ *
+ * Key priority: ANTHROPIC_API_KEY > OPENROUTER_API_KEY
+ * OpenRouter uses its own REST format (not Anthropic SDK compatible),
+ * so we call it directly via fetch when using OpenRouter.
+ */
+export declare function runAgentViaAPI(options: AgentRuntimeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=agent-runtime-api.d.ts.map

package/dist/lib/agent-runtime-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime-api.d.ts","sourceRoot":"","sources":["../../src/lib/agent-runtime-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAmFD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahF"}

package/dist/lib/agent-runtime-api.js

@@ -0,0 +1,270 @@
+/**
+ * API-based agent runtime — replaces spawn('claude') with Anthropic API + tool_use.
+ *
+ * WHY: Every spawn('claude') creates a ~300MB node process. macOS compresses dead
+ * pages instead of freeing them. 20 rounds/night = 6GB compressed memory that's
+ * unreclaimable without reboot. This replaces N process spawns with N HTTP calls
+ * from a single long-lived process. Zero memory churn.
+ *
+ * Tools: read_file, write_file, list_files, bash (same capabilities as claude CLI)
+ * Model: claude-sonnet-4-20250514 (fast, cheap, good enough for focused edits)
+ *
+ * @purpose API-based agent runtime — zero memory churn replacement for spawn('claude')
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+// ── Tool Definitions ───────────────────────────────────────────────────────
+// Karpathy-style: minimal tools. bash handles everything — grep, sed, cat, python.
+// edit_file kept but with line-number replacement (way more reliable than exact text match).
+const TOOLS = [
+    {
+        name: "bash",
+        description: "Run a bash command. Use this for everything: reading files (cat, head, tail, sed -n), editing (sed -i, python -c), searching (grep, find), testing. Returns stdout+stderr.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "Bash command to execute" },
+            },
+            required: ["command"],
+        },
+    },
+    {
+        name: "write_file",
+        description: "Write full content to a file (create or overwrite). For small edits, prefer bash with sed -i.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Relative path to the file" },
+                content: { type: "string", description: "Full file content" },
+            },
+            required: ["path", "content"],
+        },
+    },
+];
+// ── Tool Execution ─────────────────────────────────────────────────────────
+function executeTool(name, input, cwd) {
+    try {
+        switch (name) {
+            case "bash": {
+                const command = input.command;
+                // Block dangerous commands
+                if (/rm\s+-rf\s+[/~]|mkfs|dd\s+if/.test(command)) {
+                    return { content: "Error: Dangerous command blocked", is_error: true };
+                }
+                try {
+                    const result = execSync(command, {
+                        cwd,
+                        encoding: "utf-8",
+                        timeout: 30000,
+                        maxBuffer: 1024 * 1024, // 1MB
+                        stdio: ["pipe", "pipe", "pipe"],
+                    });
+                    return { content: result.slice(0, 10000), is_error: false };
+                }
+                catch (err) {
+                    // Return stderr+stdout even on non-zero exit (useful for grep, test, etc)
+                    const out = (err.stdout || "") + (err.stderr || "");
+                    return { content: out.slice(0, 5000) || err.message, is_error: false };
+                }
+            }
+            case "write_file": {
+                const filePath = join(cwd, input.path);
+                writeFileSync(filePath, input.content);
+                return { content: `Written: ${input.path}`, is_error: false };
+            }
+            default:
+                return { content: `Error: Unknown tool: ${name}`, is_error: true };
+        }
+    }
+    catch (err) {
+        const msg = err.stderr || err.stdout || err.message || String(err);
+        return { content: `Error: ${msg.slice(0, 2000)}`, is_error: true };
+    }
+}
+// ── Main Runtime ───────────────────────────────────────────────────────────
+/**
+ * Run an agent round via Anthropic API with tool_use.
+ * Single HTTP conversation — no process spawning.
+ * Replaces spawnClaudeCli() and spawnAgentRuntime().
+ *
+ * Key priority: ANTHROPIC_API_KEY > OPENROUTER_API_KEY
+ * OpenRouter uses its own REST format (not Anthropic SDK compatible),
+ * so we call it directly via fetch when using OpenRouter.
+ */
+export async function runAgentViaAPI(options) {
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openrouterKey = process.env.OPENROUTER_API_KEY;
+    if (openrouterKey && !anthropicKey) {
+        console.log("  [api] Using OpenRouter (zero memory churn)");
+        return runViaOpenRouter(options, openrouterKey);
+    }
+    if (!anthropicKey) {
+        throw new Error("No API key: set ANTHROPIC_API_KEY or OPENROUTER_API_KEY");
+    }
+    return runViaAnthropic(options, anthropicKey);
+}
+async function runViaAnthropic(options, apiKey) {
+    const { task, cwd, timeoutMs, maxTurns = 15 } = options;
+    const model = options.model || "claude-sonnet-4-20250514";
+    console.log("  [api] Using Anthropic API (zero memory churn)");
+    const client = new Anthropic({ apiKey });
+    const deadline = Date.now() + timeoutMs;
+    // Read CLAUDE.md and EXPERIMENTS.md if they exist (written by writeAgentClaudeMd/writeExperimentHistory)
+    let systemPrompt = "You are a code improvement agent. Read the files in your working directory, make ONE targeted edit to improve the metric, then stop.";
+    const claudeMdPath = join(cwd, "CLAUDE.md");
+    if (existsSync(claudeMdPath)) {
+        systemPrompt = readFileSync(claudeMdPath, "utf-8");
+    }
+    const messages = [
+        { role: "user", content: task },
+    ];
+    let turns = 0;
+    while (turns < maxTurns && Date.now() < deadline) {
+        turns++;
+        console.log(`  [api] Turn ${turns}/${maxTurns}...`);
+        const response = await client.messages.create({
+            model,
+            max_tokens: 4096,
+            system: systemPrompt,
+            tools: TOOLS,
+            messages,
+        });
+        // Collect text and tool_use blocks
+        const toolUses = [];
+        let hasText = false;
+        for (const block of response.content) {
+            if (block.type === "text") {
+                hasText = true;
+                // Only log first 200 chars to avoid noise
+                if (block.text.trim()) {
+                    console.log(`  [api] ${block.text.trim().slice(0, 200)}`);
+                }
+            }
+            else if (block.type === "tool_use") {
+                toolUses.push({ id: block.id, name: block.name, input: block.input });
+            }
+        }
+        // If no tool calls, agent is done
+        if (response.stop_reason === "end_turn" && toolUses.length === 0) {
+            console.log("  [api] Agent finished (no more tool calls)");
+            break;
+        }
+        if (toolUses.length === 0) {
+            console.log(`  [api] Agent stopped: ${response.stop_reason}`);
+            break;
+        }
+        // Execute tools and collect results
+        const toolResults = [];
+        for (const tu of toolUses) {
+            console.log(`  [api] tool: ${tu.name}(${JSON.stringify(tu.input).slice(0, 100)})`);
+            const { content, is_error } = executeTool(tu.name, tu.input, cwd);
+            toolResults.push({
+                type: "tool_result",
+                tool_use_id: tu.id,
+                content: content.slice(0, 10000), // Cap tool output
+                is_error,
+            });
+        }
+        // Add assistant response + tool results to messages
+        messages.push({ role: "assistant", content: response.content });
+        messages.push({ role: "user", content: toolResults });
+    }
+    if (Date.now() >= deadline) {
+        console.log("  [api] Agent timed out");
+    }
+    if (turns >= maxTurns) {
+        console.log("  [api] Agent hit max turns");
+    }
+}
+// ── OpenRouter Implementation ──────────────────────────────────────────────
+// OpenRouter exposes Anthropic models via its own REST API (not SDK-compatible).
+// We call it directly with fetch using the messages format.
+const OPENROUTER_TOOLS = TOOLS.map(t => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.input_schema,
+}));
+async function runViaOpenRouter(options, apiKey) {
+    const { task, cwd, timeoutMs, maxTurns = 15 } = options;
+    const model = options.model || "anthropic/claude-sonnet-4";
+    const deadline = Date.now() + timeoutMs;
+    const claudeMdPath = join(cwd, "CLAUDE.md");
+    let systemPrompt = "You are a code improvement agent. Read the files, make ONE targeted edit, then stop.";
+    if (existsSync(claudeMdPath)) {
+        systemPrompt = readFileSync(claudeMdPath, "utf-8");
+    }
+    // OpenRouter uses Anthropic's messages format
+    const messages = [
+        { role: "user", content: task },
+    ];
+    let turns = 0;
+    while (turns < maxTurns && Date.now() < deadline) {
+        turns++;
+        console.log(`  [api] Turn ${turns}/${maxTurns}...`);
+        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+                "HTTP-Referer": "https://github.com/402goose/jfl",
+                "X-Title": "JFL Agent Runtime",
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 4096,
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    ...messages,
+                ],
+                tools: OPENROUTER_TOOLS.map(t => ({ type: "function", function: t })),
+                tool_choice: "auto",
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`OpenRouter ${response.status}: ${text.slice(0, 200)}`);
+        }
+        const data = await response.json();
+        const choice = data.choices?.[0];
+        if (!choice) {
+            console.log("  [api] No response from OpenRouter");
+            break;
+        }
+        const msg = choice.message;
+        if (msg.content) {
+            console.log(`  [api] ${String(msg.content).trim().slice(0, 200)}`);
+        }
+        const toolCalls = msg.tool_calls || [];
+        if (toolCalls.length === 0) {
+            console.log(`  [api] Agent finished (finish_reason: ${choice.finish_reason})`);
+            break;
+        }
+        // Add assistant message to history
+        messages.push({ role: "assistant", content: msg.content, ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}) });
+        // Execute tools
+        for (const tc of toolCalls) {
+            const fnName = tc.function?.name || tc.name;
+            let fnArgs = {};
+            try {
+                fnArgs = JSON.parse(tc.function?.arguments || "{}");
+            }
+            catch { }
+            console.log(`  [api] tool: ${fnName}(${JSON.stringify(fnArgs).slice(0, 100)})`);
+            const { content, is_error } = executeTool(fnName, fnArgs, cwd);
+            messages.push({
+                role: "tool",
+                content: is_error ? `Error: ${content.slice(0, 5000)}` : content.slice(0, 10000),
+                ...(tc.id ? { tool_call_id: tc.id } : {}),
+            });
+        }
+    }
+    if (Date.now() >= deadline) {
+        console.log("  [api] Agent timed out");
+    }
+    if (turns >= maxTurns) {
+        console.log("  [api] Agent hit max turns");
+    }
+}
+//# sourceMappingURL=agent-runtime-api.js.map