@elvatis_com/openclaw-cli-bridge-elvatis 1.9.1 → 2.1.1

package/src/proxy-server.ts

@@ -18,6 +18,7 @@ import { claudeComplete, claudeCompleteStream, type ChatMessage as ClaudeBrowser
 import { chatgptComplete, chatgptCompleteStream, type ChatMessage as ChatGPTBrowserChatMessage } from "./chatgpt-browser.js";
 import type { BrowserContext } from "playwright";
 import { renderStatusPage, type StatusProvider } from "./status-template.js";
+import { sessionManager } from "./session-manager.js";
 
 export type GrokCompleteOptions = Parameters<typeof grokComplete>[1];
 export type GrokCompleteStreamOptions = Parameters<typeof grokCompleteStream>[1];
@@ -85,32 +86,38 @@ export interface ProxyServerOptions {
 /** Available CLI bridge models for GET /v1/models */
 export const CLI_MODELS = [
   // ── Claude Code CLI ───────────────────────────────────────────────────────
-  { id: "cli-claude/claude-sonnet-4-6", name: "Claude Sonnet 4.6 (CLI)",  contextWindow: 200_000,   maxTokens: 8_192 },
-  { id: "cli-claude/claude-opus-4-6",   name: "Claude Opus 4.6 (CLI)",    contextWindow: 200_000,   maxTokens: 8_192 },
-  { id: "cli-claude/claude-haiku-4-5",  name: "Claude Haiku 4.5 (CLI)",   contextWindow: 200_000,   maxTokens: 8_192 },
+  { id: "cli-claude/claude-sonnet-4-6", name: "Claude Sonnet 4.6 (CLI)",  contextWindow: 1_000_000, maxTokens: 64_000 },
+  { id: "cli-claude/claude-opus-4-6",   name: "Claude Opus 4.6 (CLI)",    contextWindow: 1_000_000, maxTokens: 128_000 },
+  { id: "cli-claude/claude-haiku-4-5",  name: "Claude Haiku 4.5 (CLI)",   contextWindow: 200_000,   maxTokens: 64_000 },
   // ── Gemini CLI ────────────────────────────────────────────────────────────
-  { id: "cli-gemini/gemini-2.5-pro",      name: "Gemini 2.5 Pro (CLI)",   contextWindow: 1_000_000, maxTokens: 8_192 },
-  { id: "cli-gemini/gemini-2.5-flash",    name: "Gemini 2.5 Flash (CLI)", contextWindow: 1_000_000, maxTokens: 8_192 },
-  { id: "cli-gemini/gemini-3-pro-preview",   name: "Gemini 3 Pro Preview (CLI)",   contextWindow: 1_000_000, maxTokens: 8_192 },
-  { id: "cli-gemini/gemini-3-flash-preview", name: "Gemini 3 Flash Preview (CLI)", contextWindow: 1_000_000, maxTokens: 8_192 },
+  { id: "cli-gemini/gemini-2.5-pro",      name: "Gemini 2.5 Pro (CLI)",   contextWindow: 1_048_576, maxTokens: 65_535 },
+  { id: "cli-gemini/gemini-2.5-flash",    name: "Gemini 2.5 Flash (CLI)", contextWindow: 1_048_576, maxTokens: 65_535 },
+  { id: "cli-gemini/gemini-3-pro-preview",   name: "Gemini 3 Pro Preview (CLI)",   contextWindow: 1_048_576, maxTokens: 65_536 },
+  { id: "cli-gemini/gemini-3-flash-preview", name: "Gemini 3 Flash Preview (CLI)", contextWindow: 1_048_576, maxTokens: 65_536 },
   // Codex CLI models (via openai-codex provider, OAuth auth)
-  { id: "openai-codex/gpt-5.3-codex",       name: "GPT-5.3 Codex",            contextWindow: 200_000, maxTokens: 32_768 },
-  { id: "openai-codex/gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark",      contextWindow: 200_000, maxTokens: 32_768 },
-  { id: "openai-codex/gpt-5.2-codex",       name: "GPT-5.2 Codex",            contextWindow: 200_000, maxTokens: 32_768 },
-  { id: "openai-codex/gpt-5.4",             name: "GPT-5.4",                   contextWindow: 200_000, maxTokens: 32_768 },
-  { id: "openai-codex/gpt-5.1-codex-mini",  name: "GPT-5.1 Codex Mini",       contextWindow: 200_000, maxTokens: 32_768 },
+  // GPT-5.4: 1M ctx, 128K out | GPT-5.3: 400K ctx, 128K out | GPT-5.2: 200K, 32K | Mini: 128K, 16K
+  { id: "openai-codex/gpt-5.4",             name: "GPT-5.4",               contextWindow: 1_050_000, maxTokens: 128_000 },
+  { id: "openai-codex/gpt-5.3-codex",       name: "GPT-5.3 Codex",        contextWindow: 400_000,   maxTokens: 128_000 },
+  { id: "openai-codex/gpt-5.3-codex-spark", name: "GPT-5.3 Codex Spark",  contextWindow: 400_000,   maxTokens: 64_000 },
+  { id: "openai-codex/gpt-5.2-codex",       name: "GPT-5.2 Codex",        contextWindow: 200_000,   maxTokens: 32_768 },
+  { id: "openai-codex/gpt-5.1-codex-mini",  name: "GPT-5.1 Codex Mini",   contextWindow: 128_000,   maxTokens: 16_384 },
   // Grok web-session models (requires /grok-login)
+  { id: "web-grok/grok-4",           name: "Grok 4 (web session)",           contextWindow: 131_072, maxTokens: 131_072 },
   { id: "web-grok/grok-3",           name: "Grok 3 (web session)",           contextWindow: 131_072, maxTokens: 131_072 },
   { id: "web-grok/grok-3-fast",      name: "Grok 3 Fast (web session)",      contextWindow: 131_072, maxTokens: 131_072 },
   { id: "web-grok/grok-3-mini",      name: "Grok 3 Mini (web session)",      contextWindow: 131_072, maxTokens: 131_072 },
   { id: "web-grok/grok-3-mini-fast", name: "Grok 3 Mini Fast (web session)", contextWindow: 131_072, maxTokens: 131_072 },
   // Gemini web-session models (requires /gemini-login)
-  { id: "web-gemini/gemini-2-5-pro",   name: "Gemini 2.5 Pro (web session)",   contextWindow: 1_000_000, maxTokens: 8192 },
-  { id: "web-gemini/gemini-2-5-flash", name: "Gemini 2.5 Flash (web session)", contextWindow: 1_000_000, maxTokens: 8192 },
-  { id: "web-gemini/gemini-3-pro",     name: "Gemini 3 Pro (web session)",     contextWindow: 1_000_000, maxTokens: 8192 },
-  { id: "web-gemini/gemini-3-flash",   name: "Gemini 3 Flash (web session)",   contextWindow: 1_000_000, maxTokens: 8192 },
+  { id: "web-gemini/gemini-2-5-pro",   name: "Gemini 2.5 Pro (web session)",   contextWindow: 1_048_576, maxTokens: 65_535 },
+  { id: "web-gemini/gemini-2-5-flash", name: "Gemini 2.5 Flash (web session)", contextWindow: 1_048_576, maxTokens: 65_535 },
+  { id: "web-gemini/gemini-3-pro",     name: "Gemini 3 Pro (web session)",     contextWindow: 1_048_576, maxTokens: 65_536 },
+  { id: "web-gemini/gemini-3-flash",   name: "Gemini 3 Flash (web session)",   contextWindow: 1_048_576, maxTokens: 65_536 },
   // Claude → use cli-claude/* instead (web-claude removed in v1.6.x)
   // ChatGPT → use openai-codex/* or copilot-proxy instead (web-chatgpt removed in v1.6.x)
+  // ── OpenCode CLI ──────────────────────────────────────────────────────────
+  { id: "opencode/default",             name: "OpenCode (CLI)",             contextWindow: 128_000,   maxTokens: 16_384 },
+  // ── Pi CLI ──────────────────────────────────────────────────────────────
+  { id: "pi/default",                   name: "Pi (CLI)",                   contextWindow: 128_000,   maxTokens: 16_384 },
   // ── Local BitNet inference ──────────────────────────────────────────────────
   { id: "local-bitnet/bitnet-2b",       name: "BitNet b1.58 2B (local CPU inference)", contextWindow: 4_096, maxTokens: 2_048 },
 ];
@@ -131,9 +138,10 @@ export function startProxyServer(opts: ProxyServerOptions): Promise<http.Server>
       });
     });
 
-    // Stop the token refresh interval when the server closes (timer-leak prevention)
+    // Stop the token refresh interval and session manager when the server closes (timer-leak prevention)
     server.on("close", () => {
       stopTokenRefresh();
+      sessionManager.stop();
     });
 
     server.on("error", (err) => reject(err));
@@ -141,6 +149,10 @@ export function startProxyServer(opts: ProxyServerOptions): Promise<http.Server>
       opts.log(
         `[cli-bridge] proxy server listening on http://127.0.0.1:${opts.port}`
       );
+      // unref() so the proxy server does not keep the Node.js event loop alive
+      // when openclaw doctor or other short-lived CLI commands load plugins.
+      // The gateway's own main loop keeps the process alive during normal operation.
+      server.unref();
       // Start proactive OAuth token refresh scheduler for Claude Code CLI.
       setAuthLogger(opts.log);
       void scheduleTokenRefresh();
@@ -236,7 +248,7 @@ async function handleRequest(
           owned_by: "openclaw-cli-bridge",
           // CLI-proxy models stream plain text — no tool/function call support
           capabilities: {
-            tools: !(m.id.startsWith("cli-gemini/") || m.id.startsWith("cli-claude/") || m.id.startsWith("local-bitnet/")),
+            tools: !(m.id.startsWith("cli-gemini/") || m.id.startsWith("cli-claude/") || m.id.startsWith("openai-codex/") || m.id.startsWith("opencode/") || m.id.startsWith("pi/") || m.id.startsWith("local-bitnet/")),
           },
         })),
       })
@@ -272,7 +284,8 @@ async function handleRequest(
       return;
     }
 
-    const { model, messages, stream = false } = parsed as { model: string; messages: ChatMessage[]; stream?: boolean; tools?: unknown };
+    const { model, messages, stream = false } = parsed as { model: string; messages: ChatMessage[]; stream?: boolean; tools?: unknown; workdir?: string };
+    const workdir = (parsed as { workdir?: string }).workdir;
     const hasTools = Array.isArray((parsed as { tools?: unknown }).tools) && (parsed as { tools?: unknown[] }).tools!.length > 0;
 
     if (!model || !messages?.length) {
@@ -284,7 +297,7 @@ async function handleRequest(
     // CLI-proxy models (cli-gemini/*, cli-claude/*) are plain text completions —
     // they cannot process tool/function call schemas. Return a clear 400 so
     // OpenClaw can surface a meaningful error instead of getting a garbled response.
-    const isCliModel = model.startsWith("cli-gemini/") || model.startsWith("cli-claude/"); // local-bitnet/* exempt: llama-server silently ignores tools
+    const isCliModel = model.startsWith("cli-gemini/") || model.startsWith("cli-claude/") || model.startsWith("openai-codex/") || model.startsWith("opencode/") || model.startsWith("pi/"); // local-bitnet/* exempt: llama-server silently ignores tools
     if (hasTools && isCliModel) {
       res.writeHead(400, { "Content-Type": "application/json" });
       res.end(JSON.stringify({
@@ -591,7 +604,7 @@ async function handleRequest(
     let content: string;
     let usedModel = model;
     try {
-      content = await routeToCliRunner(model, messages, opts.timeoutMs ?? 120_000);
+      content = await routeToCliRunner(model, messages, opts.timeoutMs ?? 120_000, { workdir });
     } catch (err) {
       const msg = (err as Error).message;
       // ── Model fallback: retry once with a lighter model if configured ────
@@ -599,7 +612,7 @@ async function handleRequest(
       if (fallbackModel) {
         opts.warn(`[cli-bridge] ${model} failed (${msg}), falling back to ${fallbackModel}`);
         try {
-          content = await routeToCliRunner(fallbackModel, messages, opts.timeoutMs ?? 120_000);
+          content = await routeToCliRunner(fallbackModel, messages, opts.timeoutMs ?? 120_000, { workdir });
           usedModel = fallbackModel;
           opts.log(`[cli-bridge] fallback to ${fallbackModel} succeeded`);
         } catch (fallbackErr) {
@@ -667,6 +680,116 @@ async function handleRequest(
     return;
   }
 
+  // ── Session Manager endpoints ──────────────────────────────────────────────
+
+  // POST /v1/sessions/spawn
+  if (url === "/v1/sessions/spawn" && req.method === "POST") {
+    const body = await readBody(req);
+    let parsed: { model: string; messages: ChatMessage[]; workdir?: string; timeout?: number };
+    try {
+      parsed = JSON.parse(body) as typeof parsed;
+    } catch {
+      res.writeHead(400, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify({ error: { message: "Invalid JSON body", type: "invalid_request_error" } }));
+      return;
+    }
+    if (!parsed.model || !parsed.messages?.length) {
+      res.writeHead(400, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify({ error: { message: "model and messages are required", type: "invalid_request_error" } }));
+      return;
+    }
+    const sessionId = sessionManager.spawn(parsed.model, parsed.messages, {
+      workdir: parsed.workdir,
+      timeout: parsed.timeout,
+    });
+    opts.log(`[cli-bridge] session spawned: ${sessionId} (${parsed.model})`);
+    res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+    res.end(JSON.stringify({ sessionId }));
+    return;
+  }
+
+  // GET /v1/sessions — list all sessions
+  if (url === "/v1/sessions" && req.method === "GET") {
+    const sessions = sessionManager.list();
+    res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+    res.end(JSON.stringify({ sessions }));
+    return;
+  }
+
+  // Session-specific endpoints: /v1/sessions/:id/*
+  const sessionMatch = url.match(/^\/v1\/sessions\/([a-f0-9]+)\/(poll|log|write|kill)$/);
+  if (sessionMatch) {
+    const sessionId = sessionMatch[1];
+    const action = sessionMatch[2];
+
+    if (action === "poll" && req.method === "GET") {
+      const result = sessionManager.poll(sessionId);
+      if (!result) {
+        res.writeHead(404, { "Content-Type": "application/json", ...corsHeaders() });
+        res.end(JSON.stringify({ error: { message: "Session not found", type: "not_found" } }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify(result));
+      return;
+    }
+
+    if (action === "log" && req.method === "GET") {
+      // Parse ?offset=N from URL
+      const urlObj = new URL(url, `http://127.0.0.1:${opts.port}`);
+      const offset = parseInt(urlObj.searchParams.get("offset") ?? "0", 10) || 0;
+      const result = sessionManager.log(sessionId, offset);
+      if (!result) {
+        res.writeHead(404, { "Content-Type": "application/json", ...corsHeaders() });
+        res.end(JSON.stringify({ error: { message: "Session not found", type: "not_found" } }));
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify(result));
+      return;
+    }
+
+    if (action === "write" && req.method === "POST") {
+      const body = await readBody(req);
+      let parsed: { data: string };
+      try {
+        parsed = JSON.parse(body) as typeof parsed;
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...corsHeaders() });
+        res.end(JSON.stringify({ error: { message: "Invalid JSON body", type: "invalid_request_error" } }));
+        return;
+      }
+      const ok = sessionManager.write(sessionId, parsed.data ?? "");
+      res.writeHead(ok ? 200 : 404, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify({ ok }));
+      return;
+    }
+
+    if (action === "kill" && req.method === "POST") {
+      const ok = sessionManager.kill(sessionId);
+      res.writeHead(ok ? 200 : 404, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify({ ok }));
+      return;
+    }
+  }
+
+  // Also handle /v1/sessions/:id/log with query params (URL match above doesn't capture query strings)
+  const logMatch = url.match(/^\/v1\/sessions\/([a-f0-9]+)\/log\?/);
+  if (logMatch && req.method === "GET") {
+    const sessionId = logMatch[1];
+    const urlObj = new URL(url, `http://127.0.0.1:${opts.port}`);
+    const offset = parseInt(urlObj.searchParams.get("offset") ?? "0", 10) || 0;
+    const result = sessionManager.log(sessionId, offset);
+    if (!result) {
+      res.writeHead(404, { "Content-Type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify({ error: { message: "Session not found", type: "not_found" } }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json", ...corsHeaders() });
+    res.end(JSON.stringify(result));
+    return;
+  }
+
   // 404
   res.writeHead(404, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ error: { message: `Not found: ${url}`, type: "not_found" } }));

package/src/session-manager.ts

@@ -0,0 +1,346 @@
+/**
+ * session-manager.ts
+ *
+ * Manages long-running CLI sessions as background processes.
+ * Each session spawns a CLI subprocess, buffers stdout/stderr, and allows
+ * polling, log streaming, stdin writes, and graceful termination.
+ *
+ * Singleton pattern — import and use the shared `sessionManager` instance.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { tmpdir, homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { formatPrompt, type ChatMessage } from "./cli-runner.js";
+import { createIsolatedWorkdir, cleanupWorkdir, sweepOrphanedWorkdirs } from "./workdir.js";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────────────────────────────────────
+
+export type SessionStatus = "running" | "exited" | "killed";
+
+export interface SessionEntry {
+  proc: ChildProcess;
+  stdout: string;
+  stderr: string;
+  startTime: number;
+  exitCode: number | null;
+  model: string;
+  status: SessionStatus;
+  /** Isolated workdir created for this session (null if caller provided explicit workdir). */
+  isolatedWorkdir: string | null;
+}
+
+export interface SessionInfo {
+  sessionId: string;
+  model: string;
+  status: SessionStatus;
+  startTime: number;
+  exitCode: number | null;
+  /** Isolated workdir path (null if not using workdir isolation). */
+  isolatedWorkdir: string | null;
+}
+
+export interface SpawnOptions {
+  workdir?: string;
+  timeout?: number;
+  /**
+   * If true, create an isolated temp directory for this session.
+   * The directory is automatically cleaned up when the session exits or is killed.
+   * Ignored if `workdir` is explicitly set.
+   * Default: false (uses per-runner defaults: tmpdir for gemini, homedir for others).
+   */
+  isolateWorkdir?: boolean;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Minimal env (mirrors cli-runner.ts buildMinimalEnv)
+// ──────────────────────────────────────────────────────────────────────────────
+
+function buildMinimalEnv(): Record<string, string> {
+  const pick = (key: string) => process.env[key];
+  const env: Record<string, string> = { NO_COLOR: "1", TERM: "dumb" };
+
+  for (const key of ["HOME", "PATH", "USER", "LOGNAME", "SHELL", "TMPDIR", "TMP", "TEMP"]) {
+    const v = pick(key);
+    if (v) env[key] = v;
+  }
+  for (const key of [
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "ANTHROPIC_API_KEY",
+    "CLAUDE_API_KEY",
+    "CODEX_API_KEY",
+    "OPENAI_API_KEY",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "XDG_CACHE_HOME",
+    "XDG_RUNTIME_DIR",
+    "DBUS_SESSION_BUS_ADDRESS",
+  ]) {
+    const v = pick(key);
+    if (v) env[key] = v;
+  }
+
+  return env;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Session Manager
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Auto-cleanup interval: 30 minutes. */
+const SESSION_TTL_MS = 30 * 60 * 1000;
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+export class SessionManager {
+  private sessions = new Map<string, SessionEntry>();
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor() {
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+    // Don't keep the process alive just for cleanup
+    if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+  }
+
+  /**
+   * Spawn a new CLI session for the given model + messages.
+   * Returns a unique sessionId (random hex).
+   */
+  spawn(model: string, messages: ChatMessage[], opts: SpawnOptions = {}): string {
+    const sessionId = randomBytes(8).toString("hex");
+    const prompt = formatPrompt(messages);
+
+    // Workdir isolation: create a temp dir if requested and no explicit workdir given
+    let isolatedDir: string | null = null;
+    const effectiveOpts = { ...opts };
+    if (opts.isolateWorkdir && !opts.workdir) {
+      isolatedDir = createIsolatedWorkdir();
+      effectiveOpts.workdir = isolatedDir;
+    }
+
+    const { cmd, args, cwd, useStdin } = this.resolveCliCommand(model, prompt, effectiveOpts);
+
+    const proc = spawn(cmd, args, {
+      env: buildMinimalEnv(),
+      cwd,
+      timeout: opts.timeout,
+    });
+
+    const entry: SessionEntry = {
+      proc,
+      stdout: "",
+      stderr: "",
+      startTime: Date.now(),
+      exitCode: null,
+      model,
+      status: "running",
+      isolatedWorkdir: isolatedDir,
+    };
+
+    if (useStdin) {
+      proc.stdin.write(prompt, "utf8", () => {
+        proc.stdin.end();
+      });
+    }
+
+    proc.stdout?.on("data", (d: Buffer) => { entry.stdout += d.toString(); });
+    proc.stderr?.on("data", (d: Buffer) => { entry.stderr += d.toString(); });
+
+    proc.on("close", (code) => {
+      entry.exitCode = code ?? 0;
+      if (entry.status === "running") entry.status = "exited";
+      // Auto-cleanup isolated workdir on process exit
+      if (entry.isolatedWorkdir) {
+        cleanupWorkdir(entry.isolatedWorkdir);
+      }
+    });
+
+    proc.on("error", () => {
+      if (entry.status === "running") entry.status = "exited";
+      entry.exitCode = entry.exitCode ?? 1;
+      // Auto-cleanup isolated workdir on error too
+      if (entry.isolatedWorkdir) {
+        cleanupWorkdir(entry.isolatedWorkdir);
+      }
+    });
+
+    this.sessions.set(sessionId, entry);
+    return sessionId;
+  }
+
+  /** Check if a session is still running. */
+  poll(sessionId: string): { running: boolean; exitCode: number | null; status: SessionStatus } | null {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return null;
+    return {
+      running: entry.status === "running",
+      exitCode: entry.exitCode,
+      status: entry.status,
+    };
+  }
+
+  /** Get buffered stdout/stderr from offset. */
+  log(sessionId: string, offset = 0): { stdout: string; stderr: string; offset: number } | null {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return null;
+    return {
+      stdout: entry.stdout.slice(offset),
+      stderr: entry.stderr.slice(offset),
+      offset: entry.stdout.length,
+    };
+  }
+
+  /** Write data to the session's stdin. */
+  write(sessionId: string, data: string): boolean {
+    const entry = this.sessions.get(sessionId);
+    if (!entry || entry.status !== "running") return false;
+    try {
+      entry.proc.stdin?.write(data, "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Send SIGTERM to the session process. */
+  kill(sessionId: string): boolean {
+    const entry = this.sessions.get(sessionId);
+    if (!entry || entry.status !== "running") return false;
+    entry.status = "killed";
+    entry.proc.kill("SIGTERM");
+    return true;
+  }
+
+  /** List all sessions with their status. */
+  list(): SessionInfo[] {
+    const result: SessionInfo[] = [];
+    for (const [sessionId, entry] of this.sessions) {
+      result.push({
+        sessionId,
+        model: entry.model,
+        status: entry.status,
+        startTime: entry.startTime,
+        exitCode: entry.exitCode,
+        isolatedWorkdir: entry.isolatedWorkdir,
+      });
+    }
+    return result;
+  }
+
+  /** Remove sessions older than SESSION_TTL_MS. Kill running ones first. Clean up isolated workdirs. */
+  cleanup(): void {
+    const now = Date.now();
+    for (const [sessionId, entry] of this.sessions) {
+      if (now - entry.startTime > SESSION_TTL_MS) {
+        if (entry.status === "running") {
+          entry.proc.kill("SIGTERM");
+          entry.status = "killed";
+        }
+        // Clean up isolated workdir if it wasn't cleaned on exit
+        if (entry.isolatedWorkdir) {
+          cleanupWorkdir(entry.isolatedWorkdir);
+        }
+        this.sessions.delete(sessionId);
+      }
+    }
+    // Sweep orphaned workdirs from crashed sessions
+    sweepOrphanedWorkdirs();
+  }
+
+  /** Stop the cleanup timer (for graceful shutdown). */
+  stop(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    // Kill all running sessions and clean up their workdirs
+    for (const [, entry] of this.sessions) {
+      if (entry.status === "running") {
+        entry.proc.kill("SIGTERM");
+        entry.status = "killed";
+      }
+      if (entry.isolatedWorkdir) {
+        cleanupWorkdir(entry.isolatedWorkdir);
+      }
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────
+  // Internal: resolve CLI command + args for a model
+  // ────────────────────────────────────────────────────────────────────────────
+
+  private resolveCliCommand(
+    model: string,
+    prompt: string,
+    opts: SpawnOptions
+  ): { cmd: string; args: string[]; cwd: string; useStdin: boolean } {
+    const normalized = model.startsWith("vllm/") ? model.slice(5) : model;
+    const stripPfx = (id: string) => { const s = id.indexOf("/"); return s === -1 ? id : id.slice(s + 1); };
+    const modelName = stripPfx(normalized);
+
+    if (normalized.startsWith("cli-gemini/")) {
+      return {
+        cmd: "gemini",
+        args: ["-m", modelName, "-p", ""],
+        cwd: opts.workdir ?? tmpdir(),
+        useStdin: true,
+      };
+    }
+
+    if (normalized.startsWith("cli-claude/")) {
+      return {
+        cmd: "claude",
+        args: ["-p", "--output-format", "text", "--permission-mode", "plan", "--tools", "", "--model", modelName],
+        cwd: opts.workdir ?? homedir(),
+        useStdin: true,
+      };
+    }
+
+    if (normalized.startsWith("openai-codex/")) {
+      const cwd = opts.workdir ?? homedir();
+      // Ensure git repo for Codex
+      if (!existsSync(join(cwd, ".git"))) {
+        try { execSync("git init", { cwd, stdio: "ignore" }); } catch { /* best effort */ }
+      }
+      return {
+        cmd: "codex",
+        args: ["--model", modelName, "--quiet", "--full-auto"],
+        cwd,
+        useStdin: true,
+      };
+    }
+
+    if (normalized.startsWith("opencode/")) {
+      return {
+        cmd: "opencode",
+        args: ["run", prompt],
+        cwd: opts.workdir ?? homedir(),
+        useStdin: false,
+      };
+    }
+
+    if (normalized.startsWith("pi/")) {
+      return {
+        cmd: "pi",
+        args: ["-p", prompt],
+        cwd: opts.workdir ?? homedir(),
+        useStdin: false,
+      };
+    }
+
+    // Fallback: try as a generic CLI (stdin-based)
+    return {
+      cmd: modelName,
+      args: [],
+      cwd: opts.workdir ?? homedir(),
+      useStdin: true,
+    };
+  }
+}
+
+/** Shared singleton instance. */
+export const sessionManager = new SessionManager();