Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
11.8 KB
Raw Blame
/**
 * Persisted registry of managed OpenCode engine processes.
 *
 * The engine URL/port live only in memory (ServerConfig), so an unclean
 * OmniRush.ai server exit orphans its engine child with no record to clean up.
 * Packaged desktop builds have a `ps`-based sweep, but dev builds and Windows
 * have nothing. This registry records every managed spawn on disk so the next
 * server boot can reap provable orphans — and nothing else.
 *
 * Reaping errs toward NOT killing: a leaked orphan is recoverable on a later
 * boot, killing a stranger's process is not. A recorded pid is only killed
 * when its owning server is gone, the pid still looks like the engine we
 * spawned (command match), and the recorded per-spawn credentials do not
 * prove the port now belongs to someone else.
 */
import { spawnSync } from "node:child_process";
import { mkdir, readFile } from "node:fs/promises";
import { basename, join } from "node:path";

import { runtimeStorageDir } from "./runtime-db.js";
import { loopbackFetch } from "./server-fetch.js";
import type { ServerConfig } from "./types.js";
import { writeFileAtomic } from "./atomic-write.js";

export type EngineInstanceRole = "starting" | "primary" | "draining";

export type EngineInstanceRecord = {
  /** Unique per spawn. */
  id: string;
  /** Engine child process id. */
  pid: number;
  /** Loopback port the engine reported at readiness. */
  port: number;
  /** Base URL parsed from the engine's readiness line. */
  url: string;
  startedAt: number;
  role: EngineInstanceRole;
  /** Unique per OmniRush.ai server boot that spawned this engine. */
  serverRunId: string;
  /** Pid of the OmniRush.ai server process that owns this engine. */
  ownerPid: number;
  /** `Basic <base64>` header for this spawn's random engine credentials. */
  authProbe: string;
  /** Binary the engine was spawned from. */
  bin: string;
};

type EngineRegistryFile = {
  version: 1;
  entries: EngineInstanceRecord[];
};

export type EngineReapResult = {
  killed: number[];
  spared: number[];
  dropped: number[];
};

type EngineRegistryLogger = {
  log: (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
};

export function engineRegistryFilePath(config: ServerConfig): string {
  return join(runtimeStorageDir(config), "engine-instances.json");
}

export function buildEngineAuthProbeHeader(username: string, password: string): string {
  return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function parseEntry(value: unknown): EngineInstanceRecord | null {
  if (!isRecord(value)) return null;
  const pid = Number(value.pid);
  const port = Number(value.port);
  const ownerPid = Number(value.ownerPid);
  if (typeof value.id !== "string" || !value.id.trim()) return null;
  if (!Number.isInteger(pid) || pid <= 0) return null;
  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
  if (!Number.isInteger(ownerPid) || ownerPid <= 0) return null;
  if (typeof value.url !== "string" || !value.url.trim()) return null;
  const role = value.role === "primary" || value.role === "draining" || value.role === "starting"
    ? value.role
    : "primary";
  return {
    id: value.id,
    pid,
    port,
    url: value.url,
    startedAt: Number(value.startedAt) || 0,
    role,
    serverRunId: typeof value.serverRunId === "string" ? value.serverRunId : "",
    ownerPid,
    authProbe: typeof value.authProbe === "string" ? value.authProbe : "",
    bin: typeof value.bin === "string" ? value.bin : "",
  };
}

async function readRegistryFile(path: string): Promise<EngineInstanceRecord[]> {
  const content = await readFile(path, "utf8").catch(() => undefined);
  if (!content) return [];
  try {
    const parsed: unknown = JSON.parse(content);
    if (!isRecord(parsed) || !Array.isArray(parsed.entries)) return [];
    return parsed.entries
      .map(parseEntry)
      .filter((entry): entry is EngineInstanceRecord => entry !== null);
  } catch {
    // A corrupt registry must never block startup; treat it as empty and let
    // the next write replace it.
    return [];
  }
}

// Serialize writes per path so concurrent register/remove calls can never
// interleave a stale read-modify-write over a newer one.
const registryWriteQueue = new Map<string, Promise<unknown>>();

async function mutateRegistry(
  config: ServerConfig,
  mutate: (entries: EngineInstanceRecord[]) => EngineInstanceRecord[],
): Promise<EngineInstanceRecord[]> {
  const path = engineRegistryFilePath(config);
  const job = async (): Promise<EngineInstanceRecord[]> => {
    const entries = mutate(await readRegistryFile(path));
    const payload: EngineRegistryFile = { version: 1, entries };
    await mkdir(runtimeStorageDir(config), { recursive: true });
    // 0600: the auth probe header embeds this spawn's engine credentials.
    // A failed write leaves no temp file behind and rejects this job only.
    await writeFileAtomic(path, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
    return entries;
  };
  const previous = registryWriteQueue.get(path) ?? Promise.resolve();
  const next = previous.then(job, job);
  registryWriteQueue.set(path, next);
  return await next;
}

export async function readEngineRegistry(config: ServerConfig): Promise<EngineInstanceRecord[]> {
  return readRegistryFile(engineRegistryFilePath(config));
}

export async function registerEngineInstance(
  config: ServerConfig,
  record: EngineInstanceRecord,
): Promise<void> {
  await mutateRegistry(config, (entries) => [
    ...entries.filter((entry) => entry.id !== record.id),
    record,
  ]);
}

export async function updateEngineInstanceRole(
  config: ServerConfig,
  id: string,
  role: EngineInstanceRole,
): Promise<void> {
  await mutateRegistry(config, (entries) =>
    entries.map((entry) => (entry.id === id ? { ...entry, role } : entry)),
  );
}

export async function removeEngineInstance(config: ServerConfig, id: string): Promise<void> {
  await mutateRegistry(config, (entries) => entries.filter((entry) => entry.id !== id));
}

function processAlive(pid: number): boolean {
  if (!Number.isInteger(pid) || pid <= 0) return false;
  try {
    process.kill(pid, 0);
    return true;
  } catch (error) {
    // EPERM means the pid exists but belongs to another user.
    return (error as NodeJS.ErrnoException).code === "EPERM";
  }
}

/**
 * Best-effort command line for a pid. Returns null when it cannot be read —
 * callers must treat null as "unknown", never as "not the engine".
 */
function processCommand(pid: number): string | null {
  try {
    if (process.platform === "win32") {
      const result = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8" });
      if (result.status !== 0) return null;
      const row = String(result.stdout ?? "").split(/\r?\n/).find((line) => line.includes(`"${pid}"`));
      if (!row) return null;
      const command = row.split('","')[0]?.replace(/^"/, "");
      return command?.trim() || null;
    }
    const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
    if (result.status !== 0) return null;
    const command = String(result.stdout ?? "").trim();
    return command || null;
  } catch {
    return null;
  }
}

function commandMatchesEngine(command: string, bin: string): boolean {
  const lower = command.toLowerCase();
  if (/(^|[/\\ ])opencode[^/\\ ]*( |$)/.test(lower) && lower.includes("serve")) return true;
  const binBase = basename(bin.trim()).toLowerCase();
  return binBase.length > 0 && lower.includes(binBase);
}

type ProbeOutcome = "ours" | "stranger" | "unreachable";

async function probeEngineIdentity(entry: EngineInstanceRecord, timeoutMs: number): Promise<ProbeOutcome> {
  let target: string;
  try {
    target = new URL("/global/health", entry.url).toString();
  } catch {
    return "unreachable";
  }
  try {
    const response = await loopbackFetch(target, {
      headers: entry.authProbe ? { Authorization: entry.authProbe } : {},
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (response.ok) return "ours";
    if (response.status === 401 || response.status === 403) return "stranger";
    return "unreachable";
  } catch {
    return "unreachable";
  }
}

function killEngineProcess(pid: number): void {
  if (process.platform === "win32") {
    // /T kills the tree so engine-spawned children (stdio MCPs, LSPs) go too.
    spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { encoding: "utf8" });
    return;
  }
  try {
    process.kill(pid, "SIGTERM");
  } catch {
    return;
  }
}

async function delay(ms: number): Promise<void> {
  await new Promise((resolve) => setTimeout(resolve, ms));
}

/**
 * Kill engine processes recorded by dead OmniRush.ai servers, drop entries that
 * can no longer be verified, and keep entries whose owning server is alive.
 *
 * Kill requires all of: the recorded owner process is gone, the recorded pid
 * is alive AND its command still looks like the engine we spawned, and the
 * identity probe did not prove the port belongs to a different process.
 */
export async function reapOrphanEngineInstances(
  config: ServerConfig,
  options?: { logger?: EngineRegistryLogger; probeTimeoutMs?: number; killWaitMs?: number },
): Promise<EngineReapResult> {
  const probeTimeoutMs = options?.probeTimeoutMs ?? 1000;
  const killWaitMs = options?.killWaitMs ?? 1000;
  const result: EngineReapResult = { killed: [], spared: [], dropped: [] };
  const kept: EngineInstanceRecord[] = [];
  const toKill: EngineInstanceRecord[] = [];

  for (const entry of await readEngineRegistry(config)) {
    if (entry.ownerPid === process.pid || processAlive(entry.ownerPid)) {
      // A live OmniRush.ai server (possibly the CLI next to the desktop) still
      // owns this engine.
      kept.push(entry);
      result.spared.push(entry.pid);
      continue;
    }
    if (!processAlive(entry.pid)) {
      result.dropped.push(entry.pid);
      continue;
    }
    const command = processCommand(entry.pid);
    if (command !== null && !commandMatchesEngine(command, entry.bin)) {
      // Pid was reused by an unrelated process.
      result.dropped.push(entry.pid);
      continue;
    }
    const probe = await probeEngineIdentity(entry, probeTimeoutMs);
    if (probe === "stranger") {
      // The port answers with different credentials, so we cannot prove the
      // recorded pid is still ours. Drop the record rather than risk a kill.
      result.dropped.push(entry.pid);
      continue;
    }
    if (command === null && probe !== "ours") {
      // No command evidence and no credential evidence: never kill blind.
      result.dropped.push(entry.pid);
      continue;
    }
    toKill.push(entry);
  }

  for (const entry of toKill) {
    killEngineProcess(entry.pid);
  }
  if (toKill.length > 0 && process.platform !== "win32") {
    await delay(killWaitMs);
    for (const entry of toKill) {
      if (processAlive(entry.pid)) {
        try {
          process.kill(entry.pid, "SIGKILL");
        } catch {
          // Exited between the check and the kill.
        }
      }
    }
  }
  for (const entry of toKill) {
    result.killed.push(entry.pid);
    options?.logger?.log("info", `Reaped orphaned managed OmniRush engine (pid ${entry.pid}).`, {
      "engine.pid": entry.pid,
      "engine.port": entry.port,
      "engine.owner_pid": entry.ownerPid,
      "engine.role": entry.role,
    });
  }

  await mutateRegistry(config, (entries) => {
    const removed = new Set([...result.killed, ...result.dropped]);
    const surviving = entries.filter((entry) => !removed.has(entry.pid));
    // Preserve records added while the reap was scanning.
    const known = new Set(kept.map((entry) => entry.id));
    return [...kept, ...surviving.filter((entry) => !known.has(entry.id))];
  }).catch(() => undefined);

  return result;
}