Skip to content

A local plugin for image-heavy chats in Codex, Claude Code and other agents: earlier images stop going out with every message, and the model fetches the one it needs by its ID, also after compaction.

10.7 KB
Raw Blame
// Purpose: P3-2 — lifecycle of the engine (the local proxy): one instance per machine, `ensure` starts it in the
// background when it is not running, and it exits by itself once no Codex process is left (v0.11: and no plugin service
// of any platform checks in).
// v0.1-3 — an engine reports which code it runs (build and version). After a plugin update, the new plugin's `ensure`
// asks the older engine still running to retire: it stops listening at once, finishes what is in flight, then exits,
// and an engine of the new code takes the port.
// Input: the port; the plugin's own source folder; process lists from `tasklist` on Windows and `ps` on macOS and
// Linux. Output: health checks, a detached engine process.

import { execFile, spawn } from "node:child_process";
import { createHash } from "node:crypto";
import { readdirSync, readFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, posix } from "node:path";
import { fileURLToPath } from "node:url";

export const ENGINE_SERVICE = "codex-attachment-manager";
export const DEFAULT_PORT = 17891;
const here = dirname(fileURLToPath(import.meta.url));

// build and version are missing on engines from before v0.1-3.
export type Health = { ok: true; service: string; pid: number; startedAt: string; port: number; build?: string | null; version?: string | null; routingVersion?: number; routingPort?: number };
export type EngineState = "running" | "started" | "replaced" | "failed";

export function isEngineHealth(value: unknown): value is Health {
  const health = value as Partial<Health> | null;
  return !!health && health.ok === true && health.service === ENGINE_SERVICE && typeof health.pid === "number";
}

// Loopback only, and never through a system proxy: plain http.get on 127.0.0.1. v0.11: `client`, the platform whose
// plugin service is asking (ensureEngine): the engine stays while such checks keep coming (watchForClients).
export async function engineHealth(port = DEFAULT_PORT, timeoutMs = 800, client?: string): Promise<Health | null> {
  try {
    const response = await fetch(`http://127.0.0.1:${port}/__cam/health`, { signal: AbortSignal.timeout(timeoutMs), ...(client ? { headers: { "x-cam-client": client } } : {}) });
    const body = await response.json();
    return isEngineHealth(body) ? body : null;
  } catch {
    return null;
  }
}

// Which code a runtime folder holds: a hash of its .ts files, subfolders included (v0.11), line endings normalised (a
// copy made from a Windows checkout has CRLF). A flat folder hashes as before. null when the folder is gone, e.g. a
// plugin version Codex has removed.
export function buildOf(dir = here): string | null {
  try {
    const hash = createHash("sha256");
    const names = readdirSync(dir, { recursive: true, encoding: "utf8" }).map((name) => name.replaceAll("\\", "/"));
    for (const name of names.filter((file) => file.endsWith(".ts")).sort()) {
      hash.update(`${name}\0${readFileSync(join(dir, name), "utf8").replaceAll("\r\n", "\n")}\0`);
    }
    return hash.digest("hex").slice(0, 12);
  } catch {
    return null;
  }
}

// The plugin's version, from the manifest next to the runtime folder.
export function versionOf(dir = here): string | null {
  try {
    return JSON.parse(readFileSync(join(dir, "..", ".codex-plugin", "plugin.json"), "utf8")).version ?? null;
  } catch {
    return null;
  }
}

// x.y.z order; anything after the numbers (a pre-release tag) is ignored.
export function compareVersions(a: string, b: string): number {
  const parts = (version: string) => version.split(/[^0-9.]/)[0].split(".").map((part) => Number(part) || 0);
  const [x, y] = [parts(a), parts(b)];
  for (let i = 0; i < Math.max(x.length, y.length); i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
  return 0;
}

// Only different code of a newer version replaces a running engine on its own; the same version with other code only
// when installing (`force`, cam install). A plugin server left over from before an update either finds its folder
// replaced (then it reads the new code, the same as the new engine's) or gone (no build), or it is an older version:
// none of them pushes the new engine out.
// v0.4: Codex and Claude Code each keep their own copy of the plugin, and both start this engine. Two copies of the
// same version with different code (one updated, the other not yet) would otherwise push each other's engine out over
// and over; until both are the same, the engine already running stays.
export function shouldReplace(running: Health, own: { build: string | null; version: string | null }, force = false): boolean {
  if (!own.build || running.build === own.build) return false;
  const newer = compareVersions(own.version ?? "0.0.0", running.version ?? "0.0.0");
  return newer > 0 || (force && newer === 0) || !running.build;
}

// Detached and hidden, so it outlives whoever asked for it (a plugin server instance, the CLI). Its working folder is
// not the plugin's: Windows will not delete a folder a running process works in, and Codex replaces the plugin's
// folder on every update and removes it on uninstall.
export function spawnEngine(port = DEFAULT_PORT, extraArgs: string[] = [], dir = here): number | undefined {
  const child = spawn(process.execPath, [join(dir, "proxy.ts"), "--port", String(port), ...extraArgs], { cwd: tmpdir(), detached: true, stdio: "ignore", windowsHide: true });
  child.unref();
  return child.pid;
}

// An engine from v0.1-3 on stops listening at once and exits after its open requests; an older one does not know the
// request, so it is stopped (Codex retries what was cut off).
export async function retireEngine(port: number, running: Health, by: string | null): Promise<void> {
  if (running.build) {
    try {
      const response = await fetch(`http://127.0.0.1:${port}/__cam/retire`, { method: "POST", headers: { "x-cam-build": by ?? "" }, signal: AbortSignal.timeout(2000) });
      if ((await response.json())?.retiring === true) return;
    } catch { /* stop it instead */ }
  }
  try { process.kill(running.pid); } catch { /* already gone */ }
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
// The build of each runtime folder, read again once for every different build a running engine reports.
const knownBuilds = new Map<string, { build: string | null; against: string | null | undefined }>();

export async function ensureEngine(options: { port?: number; waitMs?: number; extraArgs?: string[]; dir?: string; force?: boolean; client?: string } = {}): Promise<{ state: EngineState; health: Health | null; replaced?: Health }> {
  const port = options.port ?? DEFAULT_PORT;
  const dir = options.dir ?? here;
  const existing = await engineHealth(port, 800, options.client);
  let replaced: Health | undefined;
  if (existing) {
    const known = knownBuilds.get(dir);
    if (!known || (known.build !== existing.build && known.against !== existing.build)) knownBuilds.set(dir, { build: buildOf(dir), against: existing.build });
    const build = knownBuilds.get(dir)!.build;
    if (build === existing.build || !shouldReplace(existing, { build, version: versionOf(dir) }, options.force)) return { state: "running", health: existing };
    await retireEngine(port, existing, build);
    // A retiring engine closes its listener at once; a stopped one lets go of the port as it exits.
    for (let i = 0; i < 20 && (await engineHealth(port, 300))?.pid === existing.pid; i++) await sleep(150);
    replaced = existing;
  }
  spawnEngine(port, options.extraArgs, dir);
  const deadline = Date.now() + (options.waitMs ?? 8000);
  while (Date.now() < deadline) {
    await sleep(150);
    const health = await engineHealth(port);
    if (health && health.pid !== replaced?.pid) return { state: replaced ? "replaced" : "started", health, replaced };
  }
  return { state: "failed", health: null, replaced };
}

// `tasklist /FO CSV /NH` prints one quoted CSV row per process, or an INFO line when nothing matches.
export function countCodexProcesses(tasklistCsv: string): number {
  return tasklistCsv.split(/\r?\n/).filter((line) => /^"codex\.exe",/i.test(line.trim())).length;
}

// v0.1: `ps -A -o comm=` prints one executable per line: the bare name on Linux, the full path on macOS. Codex's
// command line and the app-server inside the desktop app are both named `codex`.
export function countCodexInPs(psOutput: string): number {
  return psOutput.split(/\r?\n/).filter((line) => posix.basename(line.trim()) === "codex").length;
}

// v0.4: Claude Code uses the engine too. Its command line and the desktop app are both `claude.exe` on Windows;
// `claude` (the command line) and `Claude` (the desktop app) on macOS and Linux.
export function countClaudeProcesses(tasklistCsv: string): number {
  return tasklistCsv.split(/\r?\n/).filter((line) => /^"claude\.exe",/i.test(line.trim())).length;
}

export function countClaudeInPs(psOutput: string): number {
  return psOutput.split(/\r?\n/).filter((line) => ["claude", "Claude"].includes(posix.basename(line.trim()))).length;
}

// The processes that may use the engine: Codex's and, since v0.4, Claude Code's.
export function listCodexProcesses(): Promise<number> {
  const windows = process.platform === "win32";
  const [file, args] = windows ? ["tasklist", ["/FO", "CSV", "/NH"]] : ["ps", ["-A", "-o", "comm="]];
  return new Promise((resolve) => {
    execFile(file, args, { windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
      // If the check itself fails, assume Codex is still there rather than shutting down under it.
      resolve(error ? 1 : windows ? countCodexProcesses(stdout) + countClaudeProcesses(stdout) : countCodexInPs(stdout) + countClaudeInPs(stdout));
    });
  });
}

// v0.11: a plugin service of any platform checks the engine every few seconds while its platform runs (plugin-server.ts);
// one checked within this long counts as a client still there.
export const CLIENT_SEEN_MS = 60_000;

// Exit only after `misses` checks in a row found no Codex (v0.4: and no Claude Code; v0.11: and no plugin service of
// another platform checking in, `lastClient`), so a restart does not stop the engine.
export function watchForClients(onGone: () => void, options: { intervalMs?: number; misses?: number; count?: () => Promise<number>; lastClient?: () => number } = {}): () => void {
  const processes = options.count ?? listCodexProcesses;
  const lastClient = options.lastClient ?? (() => 0);
  const count = async () => (Date.now() - lastClient() < CLIENT_SEEN_MS ? 1 : await processes());
  const needed = options.misses ?? 2;
  let missed = 0;
  const timer = setInterval(async () => {
    missed = (await count()) > 0 ? 0 : missed + 1;
    if (missed >= needed) { clearInterval(timer); onGone(); }
  }, options.intervalMs ?? 15_000);
  timer.unref();
  return () => clearInterval(timer);
}