@seqyuan/annodex 0.1.11 → 0.1.12

package/lib/codex-server.ts

@@ -0,0 +1,796 @@
+/**
+ * Codex App-Server Process Manager
+ *
+ * Manages the lifecycle of `codex app-server` sub-processes — one per workspace (cwd).
+ * Provides WebSocket JSON-RPC connections to the app-server.
+ *
+ * Protocol: JSON-RPC 2.0 over WebSocket
+ *   - codex app-server --listen ws://127.0.0.1:{port}
+ *   - annodex connects as JSON-RPC client
+ *
+ * Key methods:
+ *   thread/start     - start new conversation thread
+ *   thread/resume    - continue existing thread
+ *   thread/fork      - branch from a point in history
+ *   thread/rollback  - navigate to a previous point
+ *   thread/compact/start - compact context
+ *   thread/list      - list all threads
+ *   thread/read      - read thread details
+ *   thread/name/set  - rename thread
+ */
+
+import { spawn, ChildProcess, execSync } from "child_process";
+import { WebSocket } from "ws";
+import { existsSync } from "fs";
+import { join } from "path";
+import { createServer } from "net";
+import { CompatProxy, chatCompletionsUrl, needsCompatProxy } from "./codex-compat-proxy";
+import type { ReasoningConfig } from "./provider-api";
+import type { ProviderConfig } from "./annodex-config";
+import { APP_NAME } from "./brand";
+import { normalizeProviderApi } from "./provider-api";
+import packageJson from "../package.json";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+
+export type CodexUserInput =
+  | { type: "text"; text: string; text_elements: unknown[] }
+  | { type: "image"; url: string }
+  | { type: "localImage"; path: string }
+  | { type: "skill"; name: string; path: string }
+  | { type: "mention"; name: string; path: string };
+
+export type CodexThreadItem =
+  | { type: "userMessage"; id: string; content: CodexUserInput[] }
+  | { type: "hookPrompt"; id: string; fragments: unknown[] }
+  | { type: "agentMessage"; id: string; text: string; phase?: string | null; memoryCitation?: unknown }
+  | { type: "reasoning"; id: string; summary?: string[]; content?: string[] }
+  | { type: "plan"; id: string; text: string }
+  | {
+      type: "commandExecution";
+      id: string;
+      command: string;
+      cwd?: string;
+      status?: string;
+      aggregatedOutput?: string | null;
+      exitCode?: number | null;
+      durationMs?: number | null;
+    }
+  | { type: "fileChange"; id: string; changes?: unknown[]; status?: string }
+  | {
+      type: "mcpToolCall";
+      id: string;
+      server: string;
+      tool: string;
+      status?: string;
+      arguments?: unknown;
+      result?: unknown;
+      error?: unknown;
+    }
+  | {
+      type: "dynamicToolCall";
+      id: string;
+      tool: string;
+      arguments?: unknown;
+      status?: string;
+      contentItems?: unknown[] | null;
+      success?: boolean | null;
+    }
+  | {
+      type: "collabAgentToolCall";
+      id: string;
+      tool: unknown;
+      status?: string;
+      senderThreadId?: string;
+      receiverThreadIds?: string[];
+      prompt?: string | null;
+      model?: string | null;
+      reasoningEffort?: unknown;
+      agentsStates?: unknown;
+    }
+  | { type: "webSearch"; id: string; query: string; action?: unknown }
+  | { type: "imageView"; id: string; path: string }
+  | { type: "imageGeneration"; id: string; status: string; revisedPrompt?: string | null; result?: string; savedPath?: string }
+  | { type: "enteredReviewMode"; id: string; review: string }
+  | { type: "exitedReviewMode"; id: string; review: string }
+  | { type: "contextCompaction"; id: string }
+  | { type: "unknown"; id: string; [key: string]: unknown };
+
+export interface CodexTurn {
+  id: string;
+  items: CodexThreadItem[];
+  status: "completed" | "interrupted" | "failed" | "inProgress" | string;
+  error?: { message?: string } | null;
+}
+
+export interface CodexThread {
+  id: string;
+  preview?: string;
+  name?: string | null;
+  cwd: string;
+  path?: string | null;
+  createdAt: number;
+  updatedAt: number;
+  modelProvider?: string;
+  status?: unknown;
+  turns?: CodexTurn[];
+  model?: string;
+}
+
+// ============================================================================
+// Codex app-server connection
+// ============================================================================
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export class CodexServerConnection {
+  private ws: WebSocket | null = null;
+  private pending = new Map<string | number, PendingRequest>();
+  private nextId = 1;
+  private notificationHandlers = new Map<string, Array<(params: unknown) => void>>();
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 5;
+  private reconnectDelay = 1000;
+  private _closed = false;
+
+  constructor(
+    public readonly cwd: string,
+    private readonly url: string,
+    public readonly serverKey: string,
+  ) {}
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  isClosed(): boolean {
+    return this._closed;
+  }
+
+  async connect(): Promise<void> {
+    // Dynamic import ws to avoid issues with Next.js bundling
+    const { default: WS } = await import("ws");
+    const wsUrl = this.url;
+    this._closed = false;
+
+    return new Promise((resolve, reject) => {
+      const ws = new WS(wsUrl);
+      this.ws = ws;
+
+      ws.on("open", () => {
+        this.reconnectAttempts = 0;
+        this.initialize().then(resolve).catch(reject);
+      });
+
+      ws.on("message", (data: Buffer) => {
+        try {
+          const msg = JSON.parse(data.toString()) as JsonRpcMessage;
+          this.handleMessage(msg);
+        } catch {
+          // ignore parse errors
+        }
+      });
+
+      ws.on("close", () => {
+        this.handleDisconnect();
+      });
+
+      ws.on("error", (err: Error) => {
+        if (this.reconnectAttempts === 0) {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private async initialize(): Promise<void> {
+    const result = await this.request("initialize", {
+      clientInfo: {
+        name: "annodex",
+        title: APP_NAME,
+        version: packageJson.version,
+      },
+      capabilities: {
+        experimentalApi: true,
+      },
+    }) as {
+      userAgent?: string;
+      codexHome?: string;
+    };
+    // Store server info for later use
+    (this as { serverInfo?: unknown }).serverInfo = result;
+  }
+
+  request(method: string, params?: unknown, timeoutMs = 300_000): Promise<unknown> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error(`Codex server not connected (method: ${method})`));
+    }
+
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Request timeout: ${method}`));
+      }, timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+
+      const request: JsonRpcRequest = {
+        jsonrpc: "2.0",
+        id,
+        method,
+        params,
+      };
+
+      this.ws!.send(JSON.stringify(request));
+    });
+  }
+
+  onNotification(method: string, handler: (params: unknown) => void): () => void {
+    const handlers = this.notificationHandlers.get(method) ?? [];
+    handlers.push(handler);
+    this.notificationHandlers.set(method, handlers);
+    return () => {
+      const list = this.notificationHandlers.get(method);
+      if (list) {
+        const idx = list.indexOf(handler);
+        if (idx !== -1) list.splice(idx, 1);
+      }
+    };
+  }
+
+  private handleMessage(msg: JsonRpcMessage): void {
+    if ("method" in msg && "id" in msg) {
+      this.respondToServerRequest(msg);
+      return;
+    }
+
+    if ("method" in msg && !("id" in msg)) {
+      // Notification
+      const handlers = this.notificationHandlers.get(msg.method);
+      if (handlers) {
+        for (const h of [...handlers]) h(msg.params);
+      }
+      return;
+    }
+
+    if ("id" in msg && ("result" in msg || "error" in msg)) {
+      // Response to our request
+      const pending = this.pending.get(msg.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pending.delete(msg.id);
+        if ("error" in msg && msg.error) {
+          pending.reject(new Error(msg.error.message ?? "JSON-RPC error"));
+        } else {
+          pending.resolve(msg.result);
+        }
+      }
+    }
+  }
+
+  private respondToServerRequest(msg: JsonRpcRequest): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+
+    const result = defaultServerRequestResult(msg.method);
+    const response: JsonRpcResponse = {
+      jsonrpc: "2.0",
+      id: msg.id,
+      result,
+    };
+    this.ws.send(JSON.stringify(response));
+  }
+
+  private handleDisconnect(): void {
+    // Reject all pending requests
+    for (const [, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Codex server disconnected"));
+    }
+    this.pending.clear();
+
+    if (this._closed) return;
+
+    // Auto-reconnect
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++;
+      const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
+      setTimeout(() => {
+        if (!this._closed) {
+          this.connect().catch(() => {});
+        }
+      }, delay);
+    }
+  }
+
+  close(): void {
+    this._closed = true;
+    this.ws?.close();
+    this.ws = null;
+  }
+}
+
+function defaultServerRequestResult(method: string): unknown {
+  switch (method) {
+    case "item/commandExecution/requestApproval":
+      return { decision: "decline" };
+    case "item/fileChange/requestApproval":
+      return { decision: "decline" };
+    case "applyPatchApproval":
+    case "execCommandApproval":
+      return { decision: "denied" };
+    case "item/tool/requestUserInput":
+      return { answers: {} };
+    case "mcpServer/elicitation/request":
+      return { action: "decline", content: null, _meta: null };
+    case "item/permissions/requestApproval":
+      return { permissions: {}, scope: "turn" };
+    case "item/tool/call":
+      return { contentItems: [], success: false };
+    case "account/chatgptAuthTokens/refresh":
+      return { accessToken: "", chatgptAccountId: "", chatgptPlanType: null };
+    default:
+      return {};
+  }
+}
+
+// ============================================================================
+// Server process manager
+// ============================================================================
+
+interface ServerInstance {
+  process: ChildProcess;
+  connection: CodexServerConnection;
+  compatProxy: CompatProxy | null;
+  port: number;
+  cwd: string;
+  refCount: number;
+  startPromise: Promise<CodexServerConnection> | null;
+}
+
+declare global {
+  var __codexServers: Map<string, ServerInstance> | undefined;
+}
+
+function stopInstance(instance: ServerInstance): void {
+  instance.connection?.close();
+  if (instance.process?.pid) {
+    try {
+      if (process.platform !== "win32") process.kill(-instance.process.pid, "SIGTERM");
+      else instance.process.kill("SIGTERM");
+    } catch {
+      try { instance.process.kill("SIGTERM"); } catch { /* ignore */ }
+    }
+  }
+  instance.compatProxy?.stop().catch(() => {});
+}
+
+function getServerRegistry(): Map<string, ServerInstance> {
+  if (!globalThis.__codexServers) {
+    globalThis.__codexServers = new Map();
+    const cleanup = () => {
+      globalThis.__codexServers?.forEach((inst) => {
+        stopInstance(inst);
+      });
+    };
+    process.once("exit", cleanup);
+    process.once("SIGINT", cleanup);
+    process.once("SIGTERM", cleanup);
+  }
+  return globalThis.__codexServers;
+}
+
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      server.close(() => {
+        if (addr && typeof addr === "object") resolve(addr.port);
+        else reject(new Error("Failed to allocate a local port"));
+      });
+    });
+  });
+}
+
+interface CodexExecutableOptions {
+  customPath?: string;
+}
+
+function getCodexExecutablePath(opts?: CodexExecutableOptions): string {
+  if (opts?.customPath) return opts.customPath;
+
+  // Try npm bin directory first (node_modules/.bin/codex)
+  const cwd = process.cwd();
+  const npmBinPaths = [
+    join(cwd, "node_modules", ".bin", "codex"),
+    join(cwd, "..", "..", "node_modules", ".bin", "codex"),
+  ];
+
+  for (const p of npmBinPaths) {
+    if (existsSync(p)) return p;
+  }
+
+  // Fall back to system path
+  return "codex";
+}
+
+export interface CodexServerEnv {
+  apiKey?: string;
+  baseUrl?: string;
+  api?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+  providerId?: string;
+  modelId?: string;
+  requiresOpenAiAuth?: boolean;
+  thinkingLevel?: string;
+  reasoningConfig?: ReasoningConfig;
+}
+
+function serverKeyFor(cwd: string, env?: CodexServerEnv): string {
+  const normalizedCwd = cwd.replace(/\/+$/, "") || cwd;
+  const providerKey = env?.providerId || env?.baseUrl || "default";
+  const baseUrlKey = env?.baseUrl?.replace(/\/+$/, "") || "default";
+  const protocolKey = env?.api || "default";
+  const apiKey = env?.apiKey || "default";
+  const contextKey = env?.contextWindow ? String(env.contextWindow) : "default";
+  // Include reasoning config fingerprint so switching models with different
+  // thinking params creates a new compat proxy instead of reusing a stale one.
+  const reasoningKey = env?.reasoningConfig
+    ? `${env.reasoningConfig.thinkingParam ?? ""}|${env.reasoningConfig.effortParam ?? ""}|${env.reasoningConfig.effortValueMode ?? ""}`
+    : "default";
+  return `${normalizedCwd}\0${providerKey}\0${baseUrlKey}\0${protocolKey}\0${apiKey}\0${contextKey}\0${reasoningKey}`;
+}
+
+/** Build CodexServerEnv from a provider + model config.  Shared between
+ *  rpc-manager (session start / model switch) and session-reader
+ *  (context loading). */
+export function codexServerEnvForModel(
+  providerConfig: ProviderConfig,
+  modelId: string | undefined,
+  thinkingLevel: string | undefined,
+): CodexServerEnv {
+  const modelDef = providerConfig.models.find((m) => m.id === modelId);
+  const api = modelDef?.api ?? providerConfig.api;
+  const reasoningConfig = modelDef?.reasoningConfig ?? providerConfig.reasoningConfig;
+  return {
+    apiKey: providerConfig.apiKey || undefined,
+    baseUrl: providerConfig.baseUrl || undefined,
+    api: api || undefined,
+    contextWindow: modelDef?.contextWindow || undefined,
+    providerId: providerConfig.id,
+    modelId,
+    requiresOpenAiAuth: providerConfig.requiresOpenAiAuth,
+    thinkingLevel,
+    reasoningConfig,
+  };
+}
+
+function resolveApiKey(value?: string): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith("!")) {
+    try {
+      return execSync(trimmed.slice(1), {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 10_000,
+      }).trim() || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed) && process.env[trimmed]) {
+    return process.env[trimmed];
+  }
+  return trimmed;
+}
+
+function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function tomlKeySegment(value: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(value) ? value : tomlString(value);
+}
+
+function wireApiFor(api: string | undefined, usingCompatProxy: boolean): "responses" | "chat" | null {
+  if (usingCompatProxy) return "responses";
+  const normalized = normalizeProviderApi(api);
+  if (normalized === "openai-responses") return "responses";
+  if (normalized === "openai-completions") return "chat";
+  return null;
+}
+
+export async function getOrCreateCodexServer(
+  cwd: string,
+  env?: CodexServerEnv,
+): Promise<CodexServerConnection> {
+  const registry = getServerRegistry();
+  const normalizedCwd = cwd.replace(/\/+$/, "") || cwd;
+  const registryKey = serverKeyFor(normalizedCwd, env);
+
+  const existing = registry.get(registryKey);
+  if (existing?.connection?.isConnected()) {
+    existing.refCount++;
+    return existing.connection;
+  }
+
+  // If there's a starting promise, wait for it
+  if (existing?.startPromise) {
+    try {
+      const connection = await existing.startPromise;
+      const started = registry.get(registryKey);
+      if (started) started.refCount++;
+      return connection;
+    } catch {
+      // Start failed, try again
+    }
+  } else if (existing) {
+    stopInstance(existing);
+    registry.delete(registryKey);
+  }
+
+  const port = await findFreePort();
+  const wsUrl = `ws://127.0.0.1:${port}`;
+  const executable = getCodexExecutablePath();
+
+  const startPromise = (async (): Promise<CodexServerConnection> => {
+    // Start compat proxy if the baseUrl needs Responses→Chat translation
+    let compatProxy: CompatProxy | null = null;
+    let actualBaseUrl = env?.baseUrl || undefined;
+    const resolvedApiKey = resolveApiKey(env?.apiKey);
+    const requiresOpenAiAuth = env?.requiresOpenAiAuth ?? Boolean(resolvedApiKey);
+    const normalizedApi = normalizeProviderApi(env?.api, actualBaseUrl, env?.providerId);
+    const usesChatApi = normalizedApi === "openai-completions";
+    let usingCompatProxy = false;
+    if (usesChatApi && actualBaseUrl && resolvedApiKey && needsCompatProxy(actualBaseUrl)) {
+      const chatUrl = chatCompletionsUrl(actualBaseUrl);
+      compatProxy = new CompatProxy({
+        targetUrl: chatUrl,
+        apiKey: resolvedApiKey,
+        defaultThinking: env?.thinkingLevel ?? "disabled",
+        reasoningConfig: env?.reasoningConfig,
+      });
+      try {
+        await compatProxy.start();
+        actualBaseUrl = compatProxy.getBaseUrl();
+        usingCompatProxy = true;
+        console.log(`[codex-server] Compat proxy started on port ${compatProxy.getPort()} for ${chatUrl}`);
+      } catch (err) {
+        console.error(`[codex-server] Failed to start compat proxy:`, err);
+        compatProxy = null;
+      }
+    }
+
+    // Build env for codex subprocess
+    const childEnv: NodeJS.ProcessEnv = { ...process.env };
+    if (resolvedApiKey) childEnv.OPENAI_API_KEY = resolvedApiKey;
+    if (actualBaseUrl) childEnv.OPENAI_BASE_URL = actualBaseUrl;
+
+    // Start the app-server process. Workspace selection is passed per request.
+    // Global -c config overrides MUST come BEFORE the `app-server` subcommand.
+    // Build -c flags first, then prepend app-server args.
+    const configFlags: string[] = [];
+    // Pass model context window if known (codex uses this for token budgeting)
+    if (env?.contextWindow && env.contextWindow > 0) {
+      configFlags.push("-c", `model_context_window=${env.contextWindow}`);
+    }
+    if (env?.providerId && actualBaseUrl) {
+      const providerKey = tomlKeySegment(env.providerId);
+      const wireApi = wireApiFor(normalizedApi, usingCompatProxy);
+      configFlags.push("-c", `model_provider=${tomlString(env.providerId)}`);
+      configFlags.push("-c", `model_providers.${providerKey}.name=${tomlString(env.providerId)}`);
+      configFlags.push("-c", `model_providers.${providerKey}.base_url=${tomlString(actualBaseUrl.replace(/\/+$/, ""))}`);
+      if (wireApi) {
+        configFlags.push("-c", `model_providers.${providerKey}.wire_api=${tomlString(wireApi)}`);
+      }
+      configFlags.push("-c", `model_providers.${providerKey}.requires_openai_auth=${requiresOpenAiAuth ? "true" : "false"}`);
+    }
+    const appServerArgs: string[] = [
+      ...configFlags,
+      "app-server",
+      "--listen", wsUrl,
+    ];
+    let connection: CodexServerConnection | null = null;
+    const proc = spawn(executable, appServerArgs, {
+      cwd: normalizedCwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: childEnv,
+      detached: process.platform !== "win32",
+    });
+
+    // Collect stderr for debugging
+    const stderrChunks: string[] = [];
+    proc.stderr?.on("data", (chunk: Buffer) => {
+      stderrChunks.push(chunk.toString());
+    });
+
+    proc.stdout?.on("data", () => {
+      // Codex app-server may output info to stdout
+    });
+
+    proc.on("error", (err) => {
+      console.error(`[codex-server] Process error for ${normalizedCwd}:`, err.message);
+    });
+    proc.on("exit", () => {
+      const current = registry.get(registryKey);
+      if (current?.process === proc) {
+        registry.delete(registryKey);
+        compatProxy?.stop().catch(() => {});
+        connection?.close();
+      }
+    });
+
+    // Wait for the server to be ready, then connect
+    // Give it a moment to start listening
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    connection = new CodexServerConnection(normalizedCwd, wsUrl, registryKey);
+
+    // Retry connecting a few times
+    for (let attempt = 0; attempt < 10; attempt++) {
+      try {
+        await connection.connect();
+        break;
+      } catch {
+        if (attempt < 9) {
+          await new Promise((r) => setTimeout(r, 500));
+        } else {
+          // Kill the process and throw
+          try {
+            if (process.platform !== "win32") process.kill(-proc.pid!, "SIGTERM");
+            else proc.kill("SIGTERM");
+          } catch {
+            proc.kill("SIGTERM");
+          }
+          await compatProxy?.stop().catch(() => {});
+          const stderr = stderrChunks.join("");
+          throw new Error(
+            `Failed to connect to codex app-server after 10 attempts.\n` +
+            `stderr: ${stderr.slice(-500)}`
+          );
+        }
+      }
+    }
+
+    // Register the instance
+    const instance: ServerInstance = {
+      process: proc,
+      connection,
+      compatProxy,
+      port,
+      cwd: normalizedCwd,
+      refCount: 1,
+      startPromise: null,
+    };
+    registry.set(registryKey, instance);
+
+    return connection;
+  })();
+
+  // Store the promise so concurrent callers can wait
+  const tempInstance: ServerInstance = {
+    process: null!,
+    connection: null!,
+    compatProxy: null,
+    port,
+    cwd: normalizedCwd,
+    refCount: 0,
+    startPromise,
+  };
+  registry.set(registryKey, tempInstance);
+
+  try {
+    return await startPromise;
+  } catch (err) {
+    registry.delete(registryKey);
+    throw err;
+  }
+}
+
+export function releaseCodexServer(cwd: string, env?: CodexServerEnv): void {
+  const registry = getServerRegistry();
+  const normalizedCwd = cwd.replace(/\/+$/, "") || cwd;
+  const instance = registry.get(serverKeyFor(normalizedCwd, env));
+  if (!instance) return;
+
+  instance.refCount--;
+  if (instance.refCount <= 0) {
+    stopInstance(instance);
+    registry.delete(serverKeyFor(normalizedCwd, env));
+  }
+}
+
+export function releaseCodexServerConnection(connection: CodexServerConnection): void {
+  const registry = getServerRegistry();
+  const instance = registry.get(connection.serverKey);
+  if (!instance) return;
+
+  instance.refCount--;
+  if (instance.refCount <= 0) {
+    stopInstance(instance);
+    registry.delete(connection.serverKey);
+  }
+}
+
+/**
+ * Get thread listing from a codex server connection.
+ */
+export async function listThreads(connection: CodexServerConnection, cwd?: string): Promise<CodexThread[]> {
+  const threads: CodexThread[] = [];
+  let cursor: string | null | undefined = null;
+  do {
+    const result = await connection.request("thread/list", {
+      ...(cursor ? { cursor } : {}),
+      ...(cwd ? { cwd } : {}),
+      limit: 100,
+      sortKey: "updated_at",
+      archived: false,
+    }) as { data?: CodexThread[]; nextCursor?: string | null };
+    threads.push(...(result.data ?? []));
+    cursor = result.nextCursor ?? null;
+  } while (cursor);
+  return threads;
+}
+
+/**
+ * Read full thread details (messages, items, etc.)
+ */
+export async function readThread(connection: CodexServerConnection, threadId: string): Promise<CodexThread | null> {
+  const result = await connection.request("thread/read", { threadId, includeTurns: true }) as {
+    thread?: CodexThread;
+  };
+  return result.thread ?? null;
+}
+
+export function getServerForCwd(cwd: string): CodexServerConnection | undefined {
+  const registry = getServerRegistry();
+  const normalizedCwd = cwd.replace(/\/+$/, "") || cwd;
+  for (const instance of registry.values()) {
+    if (instance.cwd === normalizedCwd && instance.connection?.isConnected()) return instance.connection;
+  }
+  return undefined;
+}
+
+/**
+ * Shutdown all codex server instances gracefully.
+ */
+export function shutdownAllCodexServers(): void {
+  const registry = getServerRegistry();
+  for (const [, inst] of registry) {
+    stopInstance(inst);
+  }
+  registry.clear();
+}