@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
279 lines (257 loc) • 12.3 kB
text/typescript
/**
* Dashboard-driven Codex app-server restart (#1046 follow-up).
*
* The defect: Codex builds a static model manager from the catalog once at
* app-server startup and never rereads the file, so an app-server that outlives a
* catalog write serves a roster that no longer exists on disk. Detection already
* existed and already fired — but it warns on stderr, and the thing keeping an SSH
* workspace's app-server alive is the Codex app, not a human at a terminal.
*
* This module is the consent boundary the startup path deliberately refuses to
* cross (see `warnIfStaleCodexAppServersAfterStartupWrite`): a login is not consent
* to interrupt an in-flight turn, but a dashboard click is.
*
* The route is a thin adapter over these two functions. Decisions live here so a
* test can drive every branch through {@link CodexRestartServiceIo} instead of
* mocking modules — a route test that could not stub this would really terminate
* the developer's own Codex.
*
* Plan and audit history: `devlog/_fin/260815_gui_codex_restart/010_phase1_backend_endpoint.md`.
*/
import {
collectCodexAppServerCatalogState,
collectCodexAppServerCatalogStateWithin,
DASHBOARD_CATALOG_STATE_DEADLINE_MS,
listCodexAppServerProcesses,
readProcessStartMsBatch,
resetCodexAppServerCatalogStateCache,
restartCodexAppServers,
} from "./app-server-processes";
import type { CodexAppServerProcessIo } from "./app-server-processes";
import type {
CodexAppServerStateResponse,
CodexDesktopRestartSummary,
CodexRestartResponse,
} from "../lib/codex-restart-contract";
import { getServerListenPort } from "../server/lifecycle";
async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
const { restartCodexDesktopApp } = await import("./desktop-app-restart");
const outcome = restartCodexDesktopApp({ allowHandoff: false });
return {
attempted: outcome.attempted,
stopped: outcome.stopped,
surviving: outcome.surviving,
relaunch: outcome.relaunch,
...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
};
}
export interface CodexRestartServiceIo {
/** Desktop-restart seam, so a route test cannot terminate the developer's own Codex. */
restartDesktopApp?: () => Promise<CodexDesktopRestartSummary>;
/** Process-layer seam, forwarded to every app-server-processes call. */
processIo?: CodexAppServerProcessIo;
/** Catalog refresh seam. Resolves to whether a catalog or cache write happened. */
syncCatalog?: (port?: number) => Promise<boolean>;
/**
* Live listen port. `config.port` names the PREFERRED port; after a fallback
* start the bound port differs, and syncing the preferred one would point Codex
* at a dead listener (same reason the CLI startup path passes the live port).
*/
listenPort?: () => number | undefined;
collectState?: typeof collectCodexAppServerCatalogState;
/** Deadline for the default dashboard state read (ms). */
stateDeadlineMs?: number;
listProcesses?: typeof listCodexAppServerProcesses;
restart?: typeof restartCodexAppServers;
resetStateCache?: () => void;
/** Start-time reader used to re-confirm process identity before signalling. */
readStartMs?: (pids: readonly number[]) => Map<number, number | null>;
}
/**
* Thrown by the final identity gate when a pid no longer belongs to the process
* that was classified. restartCodexAppServers turns a kill throw into a `failed`
* entry, which is the honest outcome: nothing was signalled and the caller is told.
*/
class CodexAppServerIdentityChanged extends Error {
constructor(pid: number) {
super(`codex app-server identity changed before signal (pid ${pid})`);
this.name = "CodexAppServerIdentityChanged";
}
}
/**
* Single-flight latch. Two dashboard surfaces can each hold their own controller,
* so a user can press restart twice while the first request is still syncing the
* catalog. Without this, the second call re-signals processes the first already
* terminated and both report success — and it widens the window in which a pid can
* be recycled between classification and signalling.
*/
let inFlight: Promise<CodexRestartResponse> | null = null;
/**
* Read-only state for the dashboard route. The default classifier is the bounded
* request-path read: on Windows the synchronous one runs PowerShell CIM enumeration
* inline, which measured 4-7s per call and stalled every listener, proxy traffic
* included, each time the Models page opened. A probe slower than the deadline answers
* `unknown` and keeps refreshing the cache. The restart path below keeps the
* synchronous reading because it acts on it.
*/
export async function readCodexAppServerState(
io: CodexRestartServiceIo = {},
): Promise<CodexAppServerStateResponse> {
const status = io.collectState
? io.collectState(io.processIo ?? {})
: await collectCodexAppServerCatalogStateWithin(
io.stateDeadlineMs ?? DASHBOARD_CATALOG_STATE_DEADLINE_MS,
io.processIo ?? {},
);
return { state: status.state, runningCount: status.processes.length };
}
export function performCodexRestart(
io: CodexRestartServiceIo = {},
): Promise<CodexRestartResponse> {
if (inFlight) return inFlight;
const run = runCodexRestart(io).finally(() => {
inFlight = null;
});
inFlight = run;
return run;
}
/** Test hook: drop the single-flight latch between cases. */
export function resetCodexRestartInFlightForTests(): void {
inFlight = null;
}
async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartResponse> {
// Refresh the catalog FIRST. A user pressing "restart Codex" wants the new
// roster; stopping app-servers before the write would hand the replacement the
// same stale file it just lost.
let synced = false;
try {
const port = (io.listenPort ?? getServerListenPort)();
synced = await (io.syncCatalog ?? defaultSyncCatalog)(port);
} catch {
// A sync failure must not block the restart: an operator whose picker is stale
// still benefits from the app-server exiting and rereading whatever is on disk.
}
// The classifier memoizes for 5s when every io field is defaulted, so a reading
// taken before the write above would otherwise be replayed after it.
(io.resetStateCache ?? resetCodexAppServerCatalogStateCache)();
const before = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});
// Done here, before the early returns, because the model picker lives in the DESKTOP
// app: "no app-server is running" is not a reason to leave a stale roster on screen,
// and an operator who pressed restart still wants the app back on the current catalog.
//
// allowHandoff is false and that is deliberate. The handoff waits for the CALLING
// process to exit, and this runs inside a long-lived proxy that does not, so every
// handoff started here would sit out its window and fail after the operator had
// already been told it was handed off. An honest refusal beats that.
const desktop = await (io.restartDesktopApp ?? defaultRestartDesktopApp)();
const nothingToDo = (): CodexRestartResponse => ({
desktopApp: desktop,
success: true,
stateBefore: before.state,
synced,
requested: [],
stopped: [],
surviving: [],
failed: [],
// Enumeration failure reads as `unknown`, never `not_running` (#857): a failed
// enumeration must not be reported as "nothing was running".
code: before.state === "unknown" ? "enumeration_unavailable" : "nothing_running",
});
// `unknown` is not only the empty enumeration-failure case: the classifier also
// returns it WITH processes when the catalog mtime or a start time is unreadable.
// In that state it has not established that any server predates the catalog, so
// signalling would kill a possibly-current app-server on a guess.
if (before.state === "unknown" || before.processes.length === 0) return nothingToDo();
// The classifier carries { pid, startedAtMs } and no command line, but
// restartCodexAppServers needs the full identity so it can refuse to signal a
// recycled pid. Re-list and intersect on pid rather than reconstructing an
// identity we never verified.
const classifiedStarts = new Map(
before.processes.map(entry => [entry.pid, entry.startedAtMs] as const),
);
const live = (io.listProcesses ?? listCodexAppServerProcesses)(io.processIo ?? {});
const candidates = live.filter(process => classifiedStarts.has(process.pid));
// A pid plus a command line is not an identity: a replacement app-server launched
// by the same Codex install has both. Re-read start times and drop any candidate
// whose process started after the reading we classified, so a recycled pid can
// never receive a signal meant for the process that held it.
const platform = io.processIo?.platform ?? process.platform;
const startsNow = candidates.length > 0
? (io.readStartMs ?? (pids => readProcessStartMsBatch(pids, platform)))(
candidates.map(process => process.pid),
)
: new Map<number, number | null>();
const targets = candidates.filter(process => {
const classified = classifiedStarts.get(process.pid) ?? null;
const current = startsNow.get(process.pid) ?? null;
// An unreadable start time on either side means we cannot prove sameness.
if (classified === null || current === null) return false;
return classified === current;
});
if (targets.length === 0) {
// Every classified process exited, or the pid now belongs to a different
// process. Reporting "stopped" would claim credit for work this request did
// not do.
return {
success: true,
stateBefore: before.state,
synced,
requested: [],
stopped: [],
surviving: [],
failed: [],
code: "nothing_running",
desktopApp: desktop,
};
}
// Final identity gate, applied at the moment of signalling rather than before it.
//
// restartCodexAppServers re-lists and compares pid+command-line immediately
// before SIGTERM, but a replacement app-server launched by the same Codex
// install has BOTH of those. The start time is the field that distinguishes
// them, and it is not part of that comparison, so the check above (done before
// the call) still leaves a window: the original can exit and a replacement can
// claim its pid in between.
//
// Wrapping `kill` closes the window: this runs inside restartCodexAppServers'
// own signalling loop, so the start time is re-read at the last possible moment.
// An unreadable start time refuses the signal — on a recycled pid, guessing
// costs the user the turn that is running right now.
const guardedProcessIo: CodexAppServerProcessIo = {
...(io.processIo ?? {}),
kill: (pid, signal) => {
const classified = classifiedStarts.get(pid) ?? null;
const current = (io.readStartMs ?? (pids => readProcessStartMsBatch(pids, platform)))([pid])
.get(pid) ?? null;
if (classified === null || current === null || classified !== current) {
throw new CodexAppServerIdentityChanged(pid);
}
const send = io.processIo?.kill ?? ((target: number, sig: NodeJS.Signals) => {
process.kill(target, sig);
});
send(pid, signal);
},
};
const result = (io.restart ?? restartCodexAppServers)(targets, guardedProcessIo);
const clean = result.surviving.length === 0 && result.failed.length === 0;
return {
desktopApp: desktop,
success: clean,
stateBefore: before.state,
synced,
requested: result.requested,
stopped: result.stopped,
surviving: result.surviving,
// Project { pid, error } down to pids: an OS error message can embed a path
// or the account name.
failed: result.failed.map(entry => entry.pid),
code: clean ? "stopped" : "partially_stopped",
};
}
async function defaultSyncCatalog(port?: number): Promise<boolean> {
const { syncModelsToCodex } = await import("./sync");
// `undefined` config takes syncModelsToCodex's own loadConfig() default; `null`
// log keeps this request path silent.
const result = await syncModelsToCodex(port, undefined, null);
return result.catalogWritten || result.cacheSynced;
}