@hellcoder/companion 0.96.0

package/server/codex-container-auth.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { hasContainerCodexAuth } from "./codex-container-auth.js";
+
+describe("hasContainerCodexAuth", () => {
+  let tempHome: string;
+  let prevHome: string | undefined;
+
+  beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "codex-auth-test-"));
+    prevHome = process.env.HOME;
+    process.env.HOME = tempHome;
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = prevHome;
+    }
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  it("returns true when OPENAI_API_KEY env var is provided", () => {
+    expect(hasContainerCodexAuth({ OPENAI_API_KEY: "sk-test" })).toBe(true);
+  });
+
+  it("returns true when CODEX_API_KEY env var is provided", () => {
+    expect(hasContainerCodexAuth({ CODEX_API_KEY: "sk-test" })).toBe(true);
+  });
+
+  it("returns true when ~/.codex/auth.json exists on host", () => {
+    const codexDir = join(tempHome, ".codex");
+    mkdirSync(codexDir, { recursive: true });
+    writeFileSync(join(codexDir, "auth.json"), '{"token":"x"}');
+
+    expect(hasContainerCodexAuth()).toBe(true);
+  });
+
+  it("returns false when neither env vars nor auth files are present", () => {
+    expect(hasContainerCodexAuth()).toBe(false);
+  });
+
+  it("returns false when only unrelated env vars are present", () => {
+    // Claude auth vars should NOT satisfy Codex auth
+    expect(hasContainerCodexAuth({ ANTHROPIC_API_KEY: "sk-ant-test" })).toBe(false);
+  });
+});

package/server/codex-container-auth.ts

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Returns true when Codex running inside a container has a plausible auth source:
+ * - explicit OpenAI auth env vars, or
+ * - known auth files under ~/.codex that can be copied into the container.
+ */
+export function hasContainerCodexAuth(envVars?: Record<string, string>): boolean {
+  if (
+    !!envVars?.OPENAI_API_KEY
+    || !!envVars?.CODEX_API_KEY
+  ) {
+    return true;
+  }
+
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  const candidates = [
+    join(home, ".codex", "auth.json"),
+  ];
+
+  return candidates.some((p) => existsSync(p));
+}

package/server/codex-home.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  DEFAULT_COMPANION_CODEX_HOME,
+  getLegacyCodexHome,
+  resolveCompanionCodexHome,
+  resolveCompanionCodexSessionHome,
+} from "./codex-home.js";
+
+describe("codex-home", () => {
+  it("DEFAULT_COMPANION_CODEX_HOME points to ~/.companion/codex-home", () => {
+    expect(DEFAULT_COMPANION_CODEX_HOME).toBe(
+      join(homedir(), ".companion", "codex-home"),
+    );
+  });
+
+  it("getLegacyCodexHome returns ~/.codex", () => {
+    expect(getLegacyCodexHome()).toBe(join(homedir(), ".codex"));
+  });
+
+  it("resolveCompanionCodexHome returns default when no explicit path given", () => {
+    expect(resolveCompanionCodexHome()).toBe(DEFAULT_COMPANION_CODEX_HOME);
+  });
+
+  it("resolveCompanionCodexHome uses explicit path when provided", () => {
+    const custom = "/tmp/my-codex-home";
+    expect(resolveCompanionCodexHome(custom)).toBe(custom);
+  });
+
+  // Regression: resolveCompanionCodexHome must NOT read process.env.CODEX_HOME
+  // because that points to the user's global ~/.codex and would break per-session isolation.
+  it("resolveCompanionCodexHome ignores process.env.CODEX_HOME", () => {
+    const original = process.env.CODEX_HOME;
+    try {
+      process.env.CODEX_HOME = "/tmp/global-codex";
+      expect(resolveCompanionCodexHome()).toBe(DEFAULT_COMPANION_CODEX_HOME);
+    } finally {
+      if (original === undefined) {
+        delete process.env.CODEX_HOME;
+      } else {
+        process.env.CODEX_HOME = original;
+      }
+    }
+  });
+
+  it("resolveCompanionCodexSessionHome appends sessionId to base", () => {
+    const sessionId = "abc-123";
+    expect(resolveCompanionCodexSessionHome(sessionId)).toBe(
+      join(DEFAULT_COMPANION_CODEX_HOME, sessionId),
+    );
+  });
+
+  it("resolveCompanionCodexSessionHome uses explicit path", () => {
+    const custom = "/tmp/my-codex-home";
+    const sessionId = "xyz-789";
+    expect(resolveCompanionCodexSessionHome(sessionId, custom)).toBe(
+      join(custom, sessionId),
+    );
+  });
+});

package/server/codex-home.ts

@@ -0,0 +1,26 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+
+export const DEFAULT_COMPANION_CODEX_HOME = join(
+  COMPANION_HOME,
+  "codex-home",
+);
+
+export function getLegacyCodexHome(): string {
+  return join(homedir(), ".codex");
+}
+
+export function resolveCompanionCodexHome(explicitCodexHome?: string): string {
+  // Intentionally do NOT fall back to process.env.CODEX_HOME here.
+  // That env var points to the user's global Codex home (~/.codex), which
+  // would break per-session isolation by nesting session dirs inside it.
+  return resolve(explicitCodexHome || DEFAULT_COMPANION_CODEX_HOME);
+}
+
+export function resolveCompanionCodexSessionHome(
+  sessionId: string,
+  explicitCodexHome?: string,
+): string {
+  return join(resolveCompanionCodexHome(explicitCodexHome), sessionId);
+}

package/server/codex-protocol-contract.test.ts

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+function readSnapshot(relativePath: string): string {
+  return readFileSync(resolve(process.cwd(), relativePath), "utf-8");
+}
+
+function extractMethods(tsSource: string): string[] {
+  const methods = [...tsSource.matchAll(/"method": "([^"]+)"/g)].map((m) => m[1]);
+  return Array.from(new Set(methods));
+}
+
+describe("Codex protocol compatibility (offline snapshot)", () => {
+  it("includes all Codex notifications handled by codex-adapter", () => {
+    const serverNotification = readSnapshot("server/protocol/codex-upstream/ServerNotification.ts.txt");
+    const methods = extractMethods(serverNotification);
+
+    for (const method of [
+      "item/started",
+      "item/agentMessage/delta",
+      "item/commandExecution/outputDelta",
+      "item/fileChange/outputDelta",
+      "item/reasoning/textDelta",
+      "item/reasoning/summaryTextDelta",
+      "item/reasoning/summaryPartAdded",
+      "item/mcpToolCall/progress",
+      "item/plan/delta",
+      "item/completed",
+      "rawResponseItem/completed",
+      "turn/started",
+      "turn/completed",
+      "turn/plan/updated",
+      "turn/diff/updated",
+      "thread/started",
+      "thread/tokenUsage/updated",
+      "account/updated",
+      "account/rateLimits/updated",
+      "account/login/completed",
+    ]) {
+      expect(methods).toContain(method);
+    }
+  });
+
+  it("includes all client methods used by codex-adapter", () => {
+    const clientRequest = readSnapshot("server/protocol/codex-upstream/ClientRequest.ts.txt");
+    const methods = extractMethods(clientRequest);
+
+    for (const method of [
+      "initialize",
+      "thread/start",
+      "thread/resume",
+      "turn/start",
+      "turn/interrupt",
+      "account/rateLimits/read",
+    ]) {
+      expect(methods).toContain(method);
+    }
+  });
+
+  it("includes the client initialized notification used by codex-adapter", () => {
+    const clientNotification = readSnapshot("server/protocol/codex-upstream/ClientNotification.ts.txt");
+    const methods = extractMethods(clientNotification);
+    expect(methods).toContain("initialized");
+  });
+
+  it("includes all server requests handled by codex-adapter", () => {
+    const serverRequest = readSnapshot("server/protocol/codex-upstream/ServerRequest.ts.txt");
+    const methods = extractMethods(serverRequest);
+
+    for (const method of [
+      "item/commandExecution/requestApproval",
+      "item/fileChange/requestApproval",
+      "item/tool/requestUserInput",
+      "item/tool/call",
+      "applyPatchApproval",
+      "execCommandApproval",
+      "account/chatgptAuthTokens/refresh",
+    ]) {
+      expect(methods).toContain(method);
+    }
+  });
+
+  it("keeps DynamicToolCallParams shape expected by the adapter", () => {
+    const paramsType = readSnapshot("server/protocol/codex-upstream/v2/DynamicToolCallParams.ts.txt");
+    for (const field of ["threadId", "turnId", "callId", "tool", "arguments"]) {
+      expect(paramsType).toContain(`${field}:`);
+    }
+  });
+
+  it("keeps DynamicToolCallResponse shape expected by the adapter", () => {
+    const responseType = readSnapshot("server/protocol/codex-upstream/v2/DynamicToolCallResponse.ts.txt");
+    expect(responseType).toContain("contentItems:");
+    expect(responseType).toContain("success: boolean");
+  });
+});

package/server/codex-protocol-drift.test.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+function readFile(relativePath: string): string {
+  return readFileSync(resolve(process.cwd(), relativePath), "utf-8");
+}
+
+function extractMethods(tsSource: string): Set<string> {
+  return new Set([...tsSource.matchAll(/"method": "([^"]+)"/g)].map((m) => m[1]));
+}
+
+function extractCaseMethods(source: string, start: string, end: string): Set<string> {
+  const afterStart = source.split(start)[1];
+  if (!afterStart) return new Set();
+  const block = afterStart.split(end)[0] || "";
+  return new Set([...block.matchAll(/case "([^"]+)":/g)].map((m) => m[1]));
+}
+
+describe("Codex adapter method drift vs upstream protocol snapshot", () => {
+  it("keeps handled methods aligned with the upstream protocol (or explicit legacy allowlist)", () => {
+    const adapter = readFile("server/codex-adapter.ts");
+
+    const handledNotifications = extractCaseMethods(
+      adapter,
+      "private handleNotification(method: string, params: Record<string, unknown>): void {",
+      "private handleRequest(method: string, id: number, params: Record<string, unknown>): void {",
+    );
+
+    const handledRequests = extractCaseMethods(
+      adapter,
+      "private handleRequest(method: string, id: number, params: Record<string, unknown>): void {",
+      "private handleCommandApproval(jsonRpcId: number, params: Record<string, unknown>): void {",
+    );
+
+    const calledClientMethods = new Set(
+      [...adapter.matchAll(/this\.transport\.(?:call|notify)\("([^"]+)"/g)].map((m) => m[1]),
+    );
+
+    const upstreamServerNotifications = extractMethods(readFile("server/protocol/codex-upstream/ServerNotification.ts.txt"));
+    const upstreamServerRequests = extractMethods(readFile("server/protocol/codex-upstream/ServerRequest.ts.txt"));
+    const upstreamClientRequests = extractMethods(readFile("server/protocol/codex-upstream/ClientRequest.ts.txt"));
+    const upstreamClientNotifications = extractMethods(readFile("server/protocol/codex-upstream/ClientNotification.ts.txt"));
+
+    const legacyNotifications = new Set([
+      "item/updated",
+      // Legacy alias still observed in recordings; upstream snapshot currently
+      // models the same payload under item/reasoning/textDelta.
+      "item/reasoning/delta",
+      // Status notification observed in production logs but not yet present in
+      // the pinned upstream snapshot files.
+      "thread/status/changed",
+      "codex/event/stream_error",
+      "codex/event/error",
+      "codex/event/token_count",
+      "codex/event/agent_message_delta",
+      "codex/event/agent_message_content_delta",
+      "codex/event/reasoning_content_delta",
+      "codex/event/agent_message",
+      "codex/event/item_started",
+      "codex/event/item_completed",
+      "codex/event/exec_command_begin",
+      "codex/event/exec_command_output_delta",
+      "codex/event/exec_command_end",
+      "codex/event/turn_diff",
+      "codex/event/terminal_interaction",
+      "codex/event/patch_apply_begin",
+      "codex/event/patch_apply_end",
+      "codex/event/user_message",
+      "codex/event/task_started",
+      "codex/event/task_complete",
+      "codex/event/mcp_startup_complete",
+      "codex/event/context_compacted",
+      "codex/event/agent_reasoning",
+      "codex/event/agent_reasoning_delta",
+      "codex/event/agent_reasoning_section_break",
+      // Bare "error" notification for transient stream disconnections.
+      "error",
+      // Per-server MCP startup progress updates.
+      "mcpServer/startupStatus/updated",
+      // Context compaction event (v2 form of codex/event/context_compacted).
+      "thread/compacted",
+      // Informational warnings from Codex runtime.
+      "configWarning",
+      "deprecationNotice",
+      "codex/event/deprecation_notice",
+      // Legacy event variants for MCP startup, turn abort, image viewing, web search.
+      "codex/event/mcp_startup_update",
+      "codex/event/turn_aborted",
+      "codex/event/view_image_tool_call",
+      "codex/event/web_search_begin",
+      "codex/event/web_search_end",
+      // Companion-internal notification emitted by codex-ws-proxy.cjs on
+      // WebSocket reconnection — not part of the upstream Codex protocol.
+      "companion/wsReconnected",
+    ]);
+
+    const legacyServerRequests = new Set([
+      "item/mcpToolCall/requestApproval",
+    ]);
+
+    for (const method of handledNotifications) {
+      expect(
+        upstreamServerNotifications.has(method) || legacyNotifications.has(method),
+        `Unhandled by upstream snapshot (notification): ${method}`,
+      ).toBe(true);
+    }
+
+    for (const method of handledRequests) {
+      expect(
+        upstreamServerRequests.has(method) || legacyServerRequests.has(method),
+        `Unhandled by upstream snapshot (server request): ${method}`,
+      ).toBe(true);
+    }
+
+    for (const method of calledClientMethods) {
+      expect(
+        upstreamClientRequests.has(method) || upstreamClientNotifications.has(method),
+        `Unhandled by upstream snapshot (client method): ${method}`,
+      ).toBe(true);
+    }
+  });
+});

package/server/codex-ws-proxy.cjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+"use strict";
+
+// Bridges newline-delimited JSON on stdin/stdout to WebSocket text frames for
+// Codex app-server. Runs in real Node (not Bun) so the `ws` package handles the
+// Codex Rust server handshake correctly with perMessageDeflate disabled.
+
+const readline = require("node:readline");
+const WebSocket = require("ws");
+
+const url = process.argv[2];
+const timeoutMs = Number(process.argv[3] || "30000");
+const pongTimeoutArg = process.argv[4];
+
+if (!url) {
+  process.stderr.write("[codex-ws-proxy] Missing URL argument\n");
+  process.exit(2);
+}
+
+let ws = null;
+let opened = false;
+let closed = false;
+let exiting = false;
+let queue = [];
+let connectAttempt = 0;
+const startedAt = Date.now();
+
+// Reconnection state — after a successful initial connection, transient
+// WebSocket drops are retried with exponential backoff before giving up.
+const MAX_RECONNECT_ATTEMPTS = 10;
+const RECONNECT_BASE_MS = 200;
+const RECONNECT_MAX_MS = 5000;
+let reconnecting = false;
+let reconnectAttempt = 0;
+
+// Heartbeat — detect zombie WebSocket connections where the TCP socket is open
+// but the remote Codex process has stopped responding.
+const PING_INTERVAL_MS = 30000;
+const PONG_TIMEOUT_MS = pongTimeoutArg ? Number(pongTimeoutArg) : 30000;
+let pingTimer = null;
+let pongTimer = null;
+
+function log(msg) {
+  process.stderr.write(`[codex-ws-proxy] ${msg}\n`);
+}
+
+function startHeartbeat() {
+  stopHeartbeat();
+  pingTimer = setInterval(() => {
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    if (pongTimer) { clearTimeout(pongTimer); pongTimer = null; }
+    ws.ping();
+    pongTimer = setTimeout(() => {
+      log("Pong timeout — connection appears dead");
+      try { ws.terminate(); } catch {}
+      // terminate() fires the close event which triggers scheduleReconnect
+    }, PONG_TIMEOUT_MS);
+  }, PING_INTERVAL_MS);
+}
+
+function stopHeartbeat() {
+  if (pingTimer) { clearInterval(pingTimer); pingTimer = null; }
+  if (pongTimer) { clearTimeout(pongTimer); pongTimer = null; }
+}
+
+function decodeMessageData(data) {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString("utf8");
+  if (Array.isArray(data)) return Buffer.concat(data.map((x) => Buffer.from(x))).toString("utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  return String(data);
+}
+
+function flushQueue() {
+  if (!ws || ws.readyState !== WebSocket.OPEN || queue.length === 0) return;
+  for (const line of queue) {
+    ws.send(line);
+  }
+  queue = [];
+}
+
+function failAndExit(message, code = 1) {
+  if (exiting) return;
+  exiting = true;
+  stopHeartbeat();
+  log(message);
+  try { if (ws) ws.close(); } catch {}
+  process.exit(code);
+}
+
+/**
+ * Attempt to reconnect after a post-open WebSocket drop.
+ * Uses exponential backoff up to MAX_RECONNECT_ATTEMPTS before giving up.
+ */
+function scheduleReconnect(reason) {
+  if (closed || exiting) return;
+  stopHeartbeat();
+  reconnectAttempt++;
+  if (reconnectAttempt > MAX_RECONNECT_ATTEMPTS) {
+    failAndExit(`WebSocket reconnection failed after ${MAX_RECONNECT_ATTEMPTS} attempts (last: ${reason})`);
+    return;
+  }
+
+  reconnecting = true;
+  const delay = Math.min(RECONNECT_BASE_MS * Math.pow(2, reconnectAttempt - 1), RECONNECT_MAX_MS);
+  log(`Reconnecting in ${delay}ms (attempt ${reconnectAttempt}/${MAX_RECONNECT_ATTEMPTS}) — ${reason}`);
+  setTimeout(connect, delay);
+}
+
+function connect() {
+  if (closed || exiting) return;
+
+  // During initial connection (before first successful open), enforce timeout.
+  if (!opened) {
+    connectAttempt += 1;
+    const elapsed = Date.now() - startedAt;
+    if (elapsed > timeoutMs) {
+      failAndExit(`Failed to connect within ${timeoutMs}ms`);
+      return;
+    }
+  }
+
+  ws = new WebSocket(url, { perMessageDeflate: false });
+
+  ws.once("open", () => {
+    if (!opened) {
+      opened = true;
+    }
+    const wasReconnect = reconnecting;
+    if (reconnecting) {
+      log(`Reconnected successfully (attempt ${reconnectAttempt})`);
+      reconnecting = false;
+      reconnectAttempt = 0;
+    }
+    startHeartbeat();
+    flushQueue();
+    // Notify the adapter AFTER flushing any buffered messages so stale Codex
+    // responses from the pre-drop session are delivered before the adapter
+    // rejects all pending calls and cleans up.
+    if (wasReconnect) {
+      const reconnectNotification = JSON.stringify({
+        method: "companion/wsReconnected",
+        params: {},
+      });
+      process.stdout.write(reconnectNotification + "\n");
+    }
+  });
+
+  ws.on("message", (data) => {
+    const raw = decodeMessageData(data);
+    // stdout is protocol channel: ONLY write payload lines
+    process.stdout.write(raw + "\n");
+  });
+
+  ws.on("pong", () => {
+    // Heartbeat response received — connection is alive
+    if (pongTimer) { clearTimeout(pongTimer); pongTimer = null; }
+  });
+
+  ws.once("close", (code, reason) => {
+    stopHeartbeat();
+    if (closed || exiting) return;
+    const why = reason ? ` reason=${reason}` : "";
+    // If connection closes before we ever opened, keep retrying until timeout.
+    if (!opened) {
+      setTimeout(connect, Math.min(100 * connectAttempt, 500));
+      return;
+    }
+    // Post-open close — attempt reconnection with backoff
+    scheduleReconnect(`WebSocket closed (code=${code}${why})`);
+  });
+
+  ws.once("error", (err) => {
+    if (closed || exiting) return;
+    // Retry during startup; after a successful connection, use reconnect logic.
+    if (!opened) {
+      setTimeout(connect, Math.min(100 * connectAttempt, 500));
+      return;
+    }
+    // Post-open error — attempt reconnection with backoff
+    scheduleReconnect(`WebSocket error: ${err && err.message ? err.message : String(err)}`);
+  });
+}
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity,
+});
+
+rl.on("line", (line) => {
+  if (closed || exiting) return;
+  if (!line) return;
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    queue.push(line);
+    return;
+  }
+  ws.send(line);
+});
+
+rl.on("close", () => {
+  closed = true;
+  stopHeartbeat();
+  try {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.close();
+    }
+  } catch {}
+  process.exit(0);
+});
+
+process.on("SIGINT", () => {
+  closed = true;
+  stopHeartbeat();
+  try { if (ws) ws.close(); } catch {}
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  closed = true;
+  stopHeartbeat();
+  try { if (ws) ws.close(); } catch {}
+  process.exit(0);
+});
+
+connect();