Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { invalidateModelObservation } from './modelObservation.js';
/**
* PortOS's client for the Codex **app-server** — the JSON-RPC-over-stdio
* endpoint OpenAI documents for embedding Codex in a product.
*
* This is the process half of `lib/codexAccount.js`: it spawns
* `codex app-server`, speaks the handshake, and exposes exactly the bounded
* account actions the Providers page needs — read the account, start a ChatGPT
* sign-in, cancel it, sign out. Nothing else in this phase: no threads, no
* turns, no inference (that is #5590).
*
* Rules this module exists to keep in one place:
*
* - **Codex owns the credentials.** PortOS never reads `~/.codex/auth.json`,
* never asks for a token, and never persists one. `account/read` is the
* source of truth; every payload crossing this boundary goes through
* `redactCodexPayload` before it can reach a log or an error context.
* - **Nothing starts at boot.** The child is spawned lazily, on an explicit
* request only, so a cold install makes no Codex process and no network
* call (AGENTS.md, "No cold-bootstrap LLM calls" — and this is stricter,
* since an OAuth flow is not something a boot sequence may begin).
* - **Every wait is bounded and settles once.** A request, the handshake, and
* a login each carry their own deadline; a child exit fails every pending
* request with a typed error rather than hanging the page forever.
* - **Writes are serialized.** JSON-RPC framing is newline-delimited, so two
* concurrent writers could interleave a frame. Every write is chained onto
* one tail promise.
*
* The readiness snapshot is CACHED and separately PEEKABLE: `GET /api/providers`
* decorates cards from `peekCodexAccountReadiness()`, which never spawns
* anything, while the Providers page's own explicit fetch is what fills that
* cache.
*/
import { mkdtemp, rm } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
import { spawn } from '../lib/childProcess.js';
import { killProcessTree, prepareWindowsSafeSpawn } from '../lib/bufferedSpawn.js';
import { ServerError } from '../lib/errorHandler.js';
import { createLineReader } from '../lib/streamLines.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import {
CODEX_APP_SERVER_ARGS,
CODEX_APP_SERVER_COMMAND,
CODEX_ERROR_CODES,
CODEX_NOTIFICATIONS,
CODEX_RPC,
deriveCodexAccountStatus,
describeCodexAccountStatus,
isCodexAuthError,
normalizeCodexAccount,
normalizeCodexLoginStart,
normalizeCodexRateLimits,
redactCodexMessage,
redactCodexPayload,
} from '../lib/codexAccount.js';
import {
CODEX_TEXT_THREAD_CONFIG,
CODEX_TEXT_TURN_SANDBOX,
CODEX_TURN_ERROR_CODES,
CODEX_TURN_NOTIFICATIONS,
CODEX_TURN_RPC,
applyCodexTurnEvent,
createTurnAccumulator,
finalizeCodexTurn,
normalizeCodexModels,
resolveCodexEffort,
} from '../lib/codexTurn.js';
/** The app-server answers a local read in milliseconds; a stall is a fault. */
const REQUEST_TIMEOUT_MS = 15_000;
/** Cold start pays for process launch and config load, so it gets more room. */
const HANDSHAKE_TIMEOUT_MS = 20_000;
/**
* How long a browser sign-in may stay pending before PortOS stops waiting. Long
* enough for a real OAuth round trip in another tab, short enough that an
* abandoned flow does not pin the card in `login-pending` until a restart.
*/
const LOGIN_TIMEOUT_MS = 5 * 60_000;
/**
* Matches the Providers page's poll cadence: a user who just signed in must see
* `ready` on the next tick, while a page reload landing on top of a poll reuses
* the answer instead of spawning a second read.
*/
const READINESS_TTL_MS = 15_000;
const CLIENT_INFO = Object.freeze({ name: 'PortOS', title: 'PortOS', version: '1' });
/** The live connection, or `null` when nothing is running. */
let connection = null;
/** Coalesces concurrent connects so one page load cannot spawn two children. */
let connecting = null;
/** The child being handshaken, before `connect()` can publish it as live. */
let connectingTarget = null;
/** `{ at, readiness }` — the last successful read. `null` = never probed. */
let readinessCache = null;
/** `{ loginId, startedAt, expiresAt, timer }` for a PortOS-initiated login. */
let pendingLogin = null;
/**
* Live text turns, keyed by threadId. One app-server connection serves every
* caller, so notifications are routed by thread rather than broadcast — a
* concurrent turn's deltas must never leak into another caller's answer.
*/
const activeTurns = new Map();
/**
* `{ at, models }` — the last successful `model/list`. `null` = NEVER FETCHED,
* which is not the same as a fetched catalog that is genuinely empty; a failed
* read leaves the last-known-good list in place rather than publishing "this
* account has no models".
*/
let modelsCache = null;
/**
* `{ code, message }` from the LAST `model/list` attempt, or `null` when the most
* recent attempt succeeded (or none has run). Cached beside — never inside —
* `modelsCache`, so a failed read stays distinguishable from a never-fetched
* one while the last-known-good list survives: a picker reading the peek can
* then say WHY it is showing the shipped list instead of the account's.
*/
let modelsError = null;
/** `{ until, category, message }` while the TEXT transport is benched. */
let textTransportBench = null;
/** The empty scratch directory generic text turns run in. Created lazily. */
let textTurnCwd = null;
/** Coalesces concurrent first-calls so only one scratch directory is created. */
let creatingTextTurnCwd = null;
/** Set by `stopCodexAppServer`, so a handshake that lands mid-shutdown is dropped. */
let stopped = false;
const codexError = (code, message, options = {}) => new ServerError(message, {
status: options.status ?? 502,
code,
context: options.context ?? {},
});
/**
* Where the `codex` binary is, or `null` when it is not on PortOS's PATH.
*
* A synchronous PATH walk, not a spawn — this is the gate that keeps a
* runtime-missing host from launching a child that can only fail with ENOENT.
*/
const resolveCodexBinary = () => findCommandOnPath(CODEX_APP_SERVER_COMMAND);
/**
* Fail every in-flight request and drop the connection.
*
* Called from the child's `exit`/`error` handlers and from `stop()`. Each
* pending entry is removed from the map BEFORE it is settled, so a rejection
* handler that immediately retries cannot see the same id twice.
*/
const teardown = (target, error) => {
if (!target) return;
const pendingEntries = [...target.pending.values()];
target.pending.clear();
target.closed = true;
for (const entry of pendingEntries) {
// Clearing matters more now that turns exist: a request deadline can be the
// full 5-minute turn timeout, and an unfired timer for an already-rejected
// request keeps a callback armed for the rest of that window.
clearTimeout(entry.timer);
entry.reject(error);
}
// A turn whose `turn/start` already answered has no pending request to reject,
// so losing the child would otherwise leave it waiting on a notification that
// can never arrive. Scoped to the LIVE connection: a stale target's late
// `exit` event must not kill turns running on the replacement that took over.
const wasLive = connection === target;
if (wasLive) {
connection = null;
failActiveTurns(error);
}
};
/**
* Fail every live text turn with `error`.
*
* Each entry is removed before it is settled, so a caller that immediately
* retries cannot observe the same thread id twice.
*/
function failActiveTurns(error) {
const turns = [...activeTurns.values()];
activeTurns.clear();
for (const turn of turns) turn.fail(error);
}
/** Reject the target and terminate its child unless it already stopped. */
const stopTarget = (target, error) => {
if (!target || target.closed) return;
teardown(target, error);
if (target.child.killed) return;
try {
// Not `child.kill()`: on Windows the child is the `cmd.exe /c` shim wrapper
// (see `openConnection`), and signalling it leaves the real codex process
// orphaned — still holding the JSON-RPC pipes PortOS just gave up on.
killProcessTree(target.child, 'SIGTERM');
} catch (err) {
console.error(`❌ Failed to stop Codex app-server: ${err.message}`);
}
};
/** Settle a pending login once, clearing its deadline. */
const settleLogin = (reason) => {
if (!pendingLogin) return;
clearTimeout(pendingLogin.timer);
pendingLogin = null;
if (reason) console.log(`🔑 Codex sign-in ${reason}`);
};
/**
* Notifications PortOS acts on. Everything else the app-server streams is for
* a thread/turn client and is ignored here.
*
* The account cache is dropped rather than patched: the notification says the
* state CHANGED, and re-reading `account/read` is one cheap local call, whereas
* merging a partial payload would invent state PortOS was not told.
*/
const handleNotification = (method, params) => {
routeTurnNotification(method, params);
if (method === CODEX_NOTIFICATIONS.accountUpdated || method === CODEX_NOTIFICATIONS.rateLimitsUpdated) {
readinessCache = null;
invalidateModelObservation('codex-account');
return;
}
if (method !== CODEX_NOTIFICATIONS.loginCompleted) return;
readinessCache = null;
invalidateModelObservation('codex-account');
// A sign-in that actually completed changed the ACCOUNT, whoever started it —
// so the cached catalog belongs to whoever was signed in before, and an
// auth/quota bench was benching a subscription that is no longer the current
// one. Both are invalidated ahead of the correlation check below, because a
// login another Codex client on this host started switches accounts just as
// completely as one PortOS started.
if (params?.success !== false) {
modelsCache = null;
modelsError = null;
clearCodexTextTransportBench();
}
const loginId = typeof params?.loginId === 'string' ? params.loginId : null;
// A completion for a login PortOS did not start still invalidates the caches
// above, but must not settle ours.
if (!pendingLogin || (loginId && loginId !== pendingLogin.loginId)) return;
settleLogin(params?.success === false ? 'failed' : 'completed');
};
/**
* Hand one server notification to the turn that owns its thread.
*
* Runs BEFORE the account handling so a turn keeps streaming even while an
* account notification is invalidating the readiness cache. A frame for a
* thread PortOS is not running is dropped, not logged: the app-server also
* streams a coding agent's own thread over this connection.
*/
const routeTurnNotification = (method, params) => {
const threadId = typeof params?.threadId === 'string' ? params.threadId : null;
if (!threadId) return;
const turn = activeTurns.get(threadId);
if (!turn) return;
// The accumulator is pure; a malformed frame can still throw inside a
// normalizer, and this runs on a stdout event handler where an uncaught
// throw would take down the node process.
// Whether the accumulator will accept this frame, computed BEFORE applying it
// (which may latch the turn id). The progress hook honours the same filters:
// streaming another turn's delta, or one that lands after this turn already
// failed, would show a consumer partial text from an answer PortOS is going to
// refuse.
const accepted = turn.acc.status === 'inProgress'
&& (!turn.acc.turnId || typeof params.turnId !== 'string' || params.turnId === turn.acc.turnId);
let terminal = false;
try {
terminal = applyCodexTurnEvent(turn.acc, method, params);
} catch (err) {
console.error(`❌ Codex turn event ${method} could not be applied: ${err.message}`);
return;
}
// Fired AFTER the accumulator, and in its own guard: a throwing hook must not
// skip the frame (the finished answer would silently lose that text), and an
// async hook's rejection is invisible to try/catch — unhandled here would be a
// process-level crash, since this runs on a stdout event outside any request.
if (accepted && turn.onDelta && method === CODEX_TURN_NOTIFICATIONS.agentMessageDelta
&& typeof params.delta === 'string') {
try {
Promise.resolve(turn.onDelta(params.delta))
.catch((err) => console.error(`❌ Codex turn progress hook rejected: ${err.message}`));
} catch (err) {
console.error(`❌ Codex turn progress hook failed: ${err.message}`);
}
}
if (terminal) turn.settle();
};
/** One decoded stdout line. Malformed input is logged and dropped, never thrown. */
const handleFrame = (target, line) => {
const text = line.trim();
if (text === '') return;
let frame = null;
try {
frame = JSON.parse(text);
} catch {
console.error(`❌ Codex app-server sent a frame PortOS could not parse (${text.length} chars)`);
return;
}
if (!frame || typeof frame !== 'object') return;
if (frame.id === undefined || frame.id === null) {
if (typeof frame.method === 'string') handleNotification(frame.method, frame.params);
return;
}
const entry = target.pending.get(frame.id);
if (!entry) return; // A late answer to a request that already timed out.
target.pending.delete(frame.id);
clearTimeout(entry.timer);
if (frame.error) {
// Scrubbed, not raw: this message is logged AND returned to the browser by
// the `/codex/*` routes, and an upstream failure can quote the credential
// that failed ("access_token=… expired").
const message = redactCodexMessage(frame.error?.message) ?? 'Codex app-server returned an error';
const rpcError = codexError(
isCodexAuthError(frame.error) ? CODEX_ERROR_CODES.authRevoked : CODEX_ERROR_CODES.protocol,
message,
{ context: { method: entry.method, error: redactCodexPayload(frame.error) } },
);
entry.reject(rpcError);
return;
}
entry.resolve(frame.result ?? null);
};
/**
* Write one JSON-RPC frame, chained onto the connection's write tail.
*
* The tail is what makes concurrent callers safe: `stdin.write` can return
* false mid-frame, and two unchained writers would interleave halves of two
* JSON lines into one unparseable stream.
*/
const writeFrame = (target, frame) => {
const write = target.writeTail.then(() => new Promise((resolve, reject) => {
if (target.closed || target.child.stdin.destroyed) {
reject(codexError(CODEX_ERROR_CODES.exited, 'The Codex app-server is no longer running.'));
return;
}
target.child.stdin.write(`${JSON.stringify(frame)}\n`, (err) => (err ? reject(err) : resolve()));
}));
// Keep the queue usable after failure while preserving this caller's error.
target.writeTail = write.catch(() => {});
return write;
};
/** A JSON-RPC request with its own deadline. Settles exactly once. */
const sendRequest = (target, method, params = {}, timeoutMs = REQUEST_TIMEOUT_MS) => new Promise((resolve, reject) => {
const id = target.nextId++;
const timer = setTimeout(() => {
if (!target.pending.delete(id)) return;
reject(codexError(CODEX_ERROR_CODES.timeout, `Codex app-server did not answer ${method} within ${Math.round(timeoutMs / 1000)}s.`));
}, timeoutMs);
timer.unref?.();
target.pending.set(id, { method, resolve, reject, timer });
writeFrame(target, { jsonrpc: '2.0', id, method, params }).catch((err) => {
if (!target.pending.delete(id)) return;
clearTimeout(timer);
reject(err);
});
});
/** A JSON-RPC notification — fire and forget, but still serialized. */
const sendNotification = (target, method, params = {}) =>
writeFrame(target, { jsonrpc: '2.0', method, params });
/**
* Spawn the app-server and complete the handshake, or throw a typed error.
*
* `spawn` can throw synchronously and the child can die before the handshake
* answers; both are caught here because this runs outside the Express request
* lifecycle, where an unhandled rejection from a process event kills the node.
*/
const openConnection = async () => {
const binary = resolveCodexBinary();
if (!binary) {
throw codexError(
CODEX_ERROR_CODES.runtimeMissing,
'The Codex CLI is not installed, so PortOS cannot check the ChatGPT account.',
{ status: 409 },
);
}
// `codex` installs as a `codex.cmd` npm shim on Windows, which `spawn()`
// refuses under `shell: false` — "spawn EINVAL", so every account read and
// ChatGPT sign-in failed there (#5838). The canonical wrap (see
// `prepareWindowsSafeSpawn` for why, and #1865) is a no-op off Windows and
// for a native `codex.exe`; this spawner was the last site bypassing it.
const { command, args } = prepareWindowsSafeSpawn(binary, [...CODEX_APP_SERVER_ARGS]);
let child = null;
try {
// Fixed argv, inherited env, no shell — nothing from a request or a stored
// provider record reaches this command line.
child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
} catch (err) {
throw codexError(CODEX_ERROR_CODES.startFailed, `Codex app-server failed to start: ${err.message}`);
}
const target = { child, pending: new Map(), nextId: 1, writeTail: Promise.resolve(), closed: false };
const reader = createLineReader((line) => handleFrame(target, line));
child.stdout?.on('data', reader.push);
// stderr is Codex's own diagnostics. Never forwarded to a client and never
// parsed — the protocol answer is the only thing PortOS acts on.
child.stderr?.on('data', () => {});
child.stdin?.on('error', (err) => console.error(`❌ Codex app-server stdin: ${err.message}`));
child.on('error', (err) => {
teardown(target, codexError(CODEX_ERROR_CODES.startFailed, `Codex app-server failed to start: ${err.message}`));
settleLogin('ended because the Codex app-server stopped');
});
child.on('exit', (code, signal) => {
reader.flush();
teardown(target, codexError(
CODEX_ERROR_CODES.exited,
`The Codex app-server exited (${signal ? `signal ${signal}` : `code ${code}`}).`,
));
settleLogin('ended because the Codex app-server stopped');
});
connectingTarget = target;
try {
await sendRequest(target, CODEX_RPC.initialize, { clientInfo: CLIENT_INFO }, HANDSHAKE_TIMEOUT_MS);
await sendNotification(target, CODEX_RPC.initialized, {});
console.log('🔌 Codex app-server connected');
return target;
} catch (err) {
// A handshake timeout/rejection happens before `connect()` can publish the
// target in `connection`; clean up here so the child cannot become an
// orphan that later account checks cannot see or stop.
stopTarget(target, err);
throw err;
}
};
/** The live connection, opening one if needed. One connect in flight at a time. */
const connect = async () => {
if (connection && !connection.closed) return connection;
if (!connecting) {
connecting = openConnection()
.then((target) => {
// Shutdown may have run while this handshake was in flight. Publishing
// now would leave a dead handle behind that the next call would replace
// with a fresh child — after the graceful-shutdown hook already ran.
if (stopped) {
stopTarget(target, codexError(CODEX_ERROR_CODES.exited, 'PortOS shut down the Codex app-server.'));
throw codexError(CODEX_ERROR_CODES.exited, 'PortOS is shutting down the Codex app-server.');
}
connection = target;
return target;
})
.finally(() => { connecting = null; connectingTarget = null; });
}
return connecting;
};
/** A request against a fresh-or-existing connection. */
const call = async (method, params = {}, timeoutMs = REQUEST_TIMEOUT_MS) =>
sendRequest(await connect(), method, params, timeoutMs);
const loginSnapshot = () => (pendingLogin
? { loginId: pendingLogin.loginId, startedAt: pendingLogin.startedAt, expiresAt: pendingLogin.expiresAt }
: null);
const buildReadiness = ({ runtimeInstalled, accountFetched, account, rateLimits, error }) => {
const status = deriveCodexAccountStatus({
runtimeInstalled,
accountFetched,
account,
rateLimits,
loginPending: pendingLogin !== null,
error,
});
return {
status,
detail: describeCodexAccountStatus(status, account),
runtimeInstalled,
// Published, not derived downstream: `account: null` alone cannot tell a
// successful read that found no account (SIGNED OUT) from a read that never
// answered (UNKNOWN), and every consumer would have to re-derive it.
accountFetched,
account,
rateLimits,
login: loginSnapshot(),
error,
checkedAt: Date.now(),
};
};
/**
* Read the account and the quota window, and fold both into one readiness
* verdict.
*
* The two reads are independent on purpose. A quota read that fails leaves
* `rateLimits: null` — NOT FETCHED — and a signed-in account still reports
* `ready`, because "PortOS could not read the usage window" is not "you are out
* of quota". Only the account read can move the verdict off `unknown`.
*/
const readReadiness = async () => {
const runtimeInstalled = resolveCodexBinary() !== null;
if (!runtimeInstalled) {
return buildReadiness({ runtimeInstalled: false, accountFetched: false, account: null, rateLimits: null, error: null });
}
let account = null;
let accountFetched = false;
let error = null;
try {
account = normalizeCodexAccount(await call(CODEX_RPC.accountRead));
accountFetched = true;
} catch (err) {
error = { code: err.code || CODEX_ERROR_CODES.protocol, message: err.message };
console.error(`❌ Codex account/read failed: ${err.message}`);
}
let rateLimits = null;
if (accountFetched && account) {
try {
rateLimits = normalizeCodexRateLimits(await call(CODEX_RPC.rateLimitsRead));
} catch (err) {
// Sentinel, not a verdict: an unread quota stays `null` and the account
// keeps whatever status it earned.
console.error(`❌ Codex rate-limit read failed: ${err.message}`);
}
}
// Deliberately does NOT clear a bench. `ready` is far weaker evidence than it
// looks: a per-session budget can be spent while the account's 5h/weekly
// windows sit at 60%, and a quota read that merely FAILED also lands on
// `ready` (an unread window is not an exhausted one). Clearing on either would
// unbench a still-spent subscription on the Providers page's next 15s poll,
// and loop that way for the whole window. The bench expires on the reset time
// Codex itself reported; only an explicit sign-in or sign-out clears it early.
return buildReadiness({ runtimeInstalled: true, accountFetched, account, rateLimits, error });
};
/**
* The current Codex account readiness, from cache unless `fresh` is set or the
* cache has aged out.
*
* LAZY: the only callers are the Providers page's explicit fetch and an
* explicitly requested run. Nothing on the boot path may call this.
*/
export async function getCodexAccountReadiness({ fresh = false } = {}) {
if (!fresh && readinessCache && Date.now() - readinessCache.at < READINESS_TTL_MS) {
// Recompute the envelope so a login that started or expired since the read
// is reflected without paying for another round trip — but keep the ORIGINAL
// `checkedAt`, or a cache hit would claim a freshness it does not have.
return { ...buildReadiness(readinessCache.readiness), checkedAt: readinessCache.readiness.checkedAt };
}
const readiness = await readReadiness();
readinessCache = { at: Date.now(), readiness };
return readiness;
}
/**
* The cached readiness, or `null` when nothing has probed it yet.
*
* Spawns nothing and awaits nothing, so `GET /api/providers` can decorate cards
* with it on a hot cache while a cold one publishes an honest "unprobed"
* instead of an accusation.
*/
export function peekCodexAccountReadiness() {
if (!readinessCache) return null;
if (Date.now() - readinessCache.at >= READINESS_TTL_MS) return null;
return readinessCache.readiness;
}
/**
* Start an explicit ChatGPT sign-in and hand back only what the browser needs.
*
* Never called implicitly: an OAuth flow is a user action, so this runs from a
* POST and from nowhere else. A second call while one is pending is refused
* rather than silently replacing it — two live `loginId`s would leave the
* completion notification unable to say which flow finished.
*
* @param {object} [options]
* @param {boolean} [options.deviceCode] — use the device-code flow (a URL plus
* a short code) instead of opening a browser URL directly.
*/
export async function startCodexChatGptLogin({ deviceCode = false } = {}) {
if (pendingLogin) {
throw codexError(CODEX_ERROR_CODES.loginFailed, 'A ChatGPT sign-in is already in progress. Finish or cancel it first.', { status: 409 });
}
const result = await call(CODEX_RPC.loginStart, { type: deviceCode ? 'chatgptDeviceCode' : 'chatgpt' });
const login = normalizeCodexLoginStart(result);
const startedAt = Date.now();
const timer = setTimeout(() => {
readinessCache = null;
settleLogin('timed out');
}, LOGIN_TIMEOUT_MS);
timer.unref?.();
pendingLogin = { loginId: login.loginId, startedAt, expiresAt: startedAt + LOGIN_TIMEOUT_MS, timer };
readinessCache = null;
console.log('🔑 Codex ChatGPT sign-in started');
return { ...login, startedAt, expiresAt: startedAt + LOGIN_TIMEOUT_MS };
}
/**
* Cancel the sign-in this PortOS started.
*
* The id is checked against the pending login before anything is sent, so a
* stale page cannot cancel a flow the user started afterwards.
*/
export async function cancelCodexChatGptLogin(loginId) {
if (!pendingLogin || pendingLogin.loginId !== loginId) {
throw codexError(CODEX_ERROR_CODES.unknownLogin, 'That ChatGPT sign-in is no longer in progress.', { status: 409 });
}
try {
await call(CODEX_RPC.loginCancel, { loginId });
} finally {
// The flow is over for PortOS either way: a cancel the app-server refused
// must not strand the card in `login-pending` forever.
settleLogin('cancelled');
readinessCache = null;
}
return getCodexAccountReadiness({ fresh: true });
}
/** Sign out of ChatGPT. Codex drops its own credentials; PortOS holds none. */
export async function codexLogout() {
await call(CODEX_RPC.logout);
settleLogin('ended by sign-out');
readinessCache = null;
modelsCache = null;
modelsError = null;
// Signing out invalidates whatever the bench was waiting on, and signing back
// in must not inherit the previous account's cooldown.
clearCodexTextTransportBench();
console.log('🔒 Codex ChatGPT account signed out');
return getCodexAccountReadiness({ fresh: true });
}
/* ------------------------------------------------------------------------- *
* Text inference (#5590)
*
* Everything below serves the SUBSCRIPTION TEXT TRANSPORT — the second, opt-in
* capability of the `codex` provider record. It is deliberately separate from
* the CLI/TUI coding harness: a Brain or JIRA summary runs here, in an empty
* throwaway directory under a read-only no-network sandbox with no MCP servers
* and no web search, while a CoS coding task keeps going through
* `executeCliRun` with the workspace it was given.
* ------------------------------------------------------------------------- */
/** A turn is a network round trip against a frontier model — not a local read. */
const TURN_TIMEOUT_MS = 300_000;
/** The catalog changes when a plan does. Long enough to not re-list per call. */
const MODELS_TTL_MS = 10 * 60_000;
/** A real catalog is tens of models; this only bounds a misbehaving server. */
const MODEL_LIST_MAX_PAGES = 20;
/**
* The empty directory every generic text turn runs in.
*
* Outside the PortOS checkout and outside `data/`, so even a sandbox escape
* would land somewhere with nothing in it. Created once per process and reused;
* `mkdtemp` guarantees it is fresh and unshared.
*/
const ensureTextTurnCwd = async () => {
if (textTurnCwd) return textTurnCwd;
// Coalesced the same way `connect()` is: two turns starting together would
// otherwise each `mkdtemp`, and the loser's directory would leak for the life
// of the process because only one path can be remembered.
if (!creatingTextTurnCwd) {
creatingTextTurnCwd = mkdtemp(join(tmpdir(), 'portos-codex-text-'))
.then((dir) => { textTurnCwd = dir; return dir; })
.finally(() => { creatingTextTurnCwd = null; });
}
return creatingTextTurnCwd;
};
/**
* Is the text transport benched right now?
*
* Returns `null` when it is usable, or `{ until, category, message }` while a
* quota/auth failure is still in its cooldown. Benching is SCOPED TO THE
* TRANSPORT on purpose: an exhausted subscription window must not take the
* `codex` coding harness — which the user may still want for a task that is
* already mid-flight — off the board as a side effect.
*/
export function getCodexTextTransportBench() {
if (!textTransportBench) return null;
if (Date.now() >= textTransportBench.until) {
textTransportBench = null;
return null;
}
return { ...textTransportBench };
}
/**
* Bench the text transport for `waitMs`.
*
* The DURATION is the caller's, resolved from the shared cooldown policy in
* `lib/providerCooldown.js`, so a quota exhaustion waits the same window here
* as it does on every other path. A longer bench never shortens an existing
* one.
*/
export function benchCodexTextTransport({ waitMs, category, message } = {}) {
const until = Date.now() + Math.max(Number(waitMs) || 0, 0);
if (textTransportBench && textTransportBench.until >= until) return getCodexTextTransportBench();
textTransportBench = { until, category: category || null, message: message || null };
console.log(`⚠️ Codex subscription text transport benched for ${Math.round((until - Date.now()) / 60000)}m: ${category || 'unknown'}`);
return getCodexTextTransportBench();
}
/** Clear the bench — used when the account is re-read as ready, and by tests. */
export function clearCodexTextTransportBench() {
textTransportBench = null;
}
/**
* The models this ChatGPT account may run, from the app-server catalog.
*
* `null` means NEVER FETCHED and `[]` means fetched-and-empty; a failed read
* returns the last-known-good list rather than either. That distinction is what
* lets the Providers page tell "we have not asked yet" from "this plan really
* has no models", and stops one transient failure from emptying a good picker.
*
* LAZY: only an explicit request reaches this. Nothing on the boot path may.
*/
export async function listCodexModels({ fresh = false } = {}) {
if (!fresh && modelsCache && Date.now() - modelsCache.at < MODELS_TTL_MS) {
return { models: modelsCache.models, fetchedAt: modelsCache.at, error: null };
}
try {
// Follow `nextCursor`. A truncated catalog is not just a short picker: a
// model on a later page is absent from `cachedModelEntry`, so its effort is
// sent unclamped — the exact failure the clamp exists to prevent. The page
// cap bounds a server that never stops handing back a cursor.
const models = [];
let cursor = null;
for (let page = 0; page < MODEL_LIST_MAX_PAGES; page += 1) {
const result = normalizeCodexModels(await call(CODEX_TURN_RPC.modelList, cursor ? { cursor } : {}));
models.push(...result.models);
cursor = result.nextCursor;
if (!cursor) break;
}
if (cursor) {
// A truncated catalog is not a successful read: caching it would replace a
// complete last-known-good list with a partial one, and reporting
// `error: null` would tell the client the picker is authoritative.
console.error(`❌ Codex model/list stopped after ${MODEL_LIST_MAX_PAGES} pages with a cursor still pending`);
throw new Error(`model/list did not finish paginating within ${MODEL_LIST_MAX_PAGES} pages`);
}
modelsCache = { at: Date.now(), models };
modelsError = null;
return { models, fetchedAt: modelsCache.at, error: null };
} catch (err) {
console.error(`❌ Codex model/list failed: ${err.message}`);
modelsError = { code: err.code || CODEX_ERROR_CODES.protocol, message: err.message };
return {
models: modelsCache ? modelsCache.models : null,
fetchedAt: modelsCache ? modelsCache.at : null,
error: modelsError,
};
}
}
/** The cached catalog without spawning anything. `null` = never fetched. */
export function peekCodexModels() {
return modelsCache ? { models: modelsCache.models, fetchedAt: modelsCache.at } : null;
}
/**
* The cached catalog as the three-state shape a picker needs, without spawning
* anything. `models: null` = NEVER FETCHED, `[]` = fetched and genuinely empty,
* and a populated array is this account's real catalog; `error` is set when the
* last attempt failed, in which case `models` is the last-known-good list (or
* `null` if there never was one). A caller must fall back to its shipped list
* for every state except a successful read — that is the whole point of keeping
* the three apart.
*
* CACHE-ONLY, like `peekCodexAccountReadiness`: this is what the providers list
* may call on a render path, where spawning `codex app-server` is forbidden.
*/
export function peekCodexModelCatalog() {
return {
models: modelsCache ? modelsCache.models : null,
fetchedAt: modelsCache ? modelsCache.at : null,
error: modelsError,
};
}
/** The catalog entry for `modelId`, or `null` when the catalog is unknown. */
const cachedModelEntry = (modelId) => {
if (!modelId || !modelsCache?.models) return null;
return modelsCache.models.find((entry) => entry.id === modelId) ?? null;
};
/** The one shape a caller's Stop takes, wherever in a turn it is noticed. */
const turnCancelledError = () =>
codexError(CODEX_TURN_ERROR_CODES.turnInterrupted, 'The Codex turn was cancelled.', { status: 499 });
/**
* Best-effort: tell the app-server to stop working a turn PortOS has abandoned,
* so a cancelled request does not keep burning subscription quota.
*
* Sent on the connection that OWNS the thread, and only while it is still alive
* — routing it through `call` would reconnect, spawning a whole new app-server
* to interrupt a thread that only existed in the dead one. Fire and forget: the
* caller is already gone, and nothing downstream waits on the acknowledgement.
*/
const interruptCodexTurn = (owner, threadId, turnId) => {
if (!turnId || !owner || owner.closed) return;
sendRequest(owner, CODEX_TURN_RPC.turnInterrupt, { threadId, turnId })
.catch((err) => console.error(`❌ Codex turn interrupt failed: ${err.message}`));
};
/**
* Await `request`, but give up the moment the caller's Stop lands.
*
* Without this a Stop raised WHILE an RPC is in flight is invisible until that
* RPC answers or hits its own deadline — up to 15s on `thread/start` and the
* whole 5-minute turn deadline on `turn/start` against a stalled app-server.
*
* `Promise.race` settles on the first, but the LOSER keeps running: a raced-away
* `sendRequest` still answers (or times out) later. That matters for
* `turn/start` — a turn the app-server accepted after the caller walked away
* would otherwise generate with nothing telling it to stop, which is worse for
* quota than the wait this removes. `onAbandoned` is that compensating path; it
* runs outside any request lifecycle, so it is guarded here rather than trusted
* to bubble.
*/
const raceCodexAbort = (request, signal, onAbandoned = null) => {
if (!signal) return request;
let abandoned = false;
let onAbort = null;
const cancelled = new Promise((_, reject) => {
onAbort = () => { abandoned = true; reject(turnCancelledError()); };
if (signal.aborted) onAbort();
else signal.addEventListener('abort', onAbort, { once: true });
});
// The race hands the caller whichever settles first, so the loser's rejection
// would otherwise be an UNHANDLED one — a process-level crash under Node's
// default policy. Both sides are parked before they can reject.
cancelled.catch(() => {});
const watched = request.then((result) => {
if (!abandoned) return result;
// The Stop already won: this response arrived for a caller that is gone.
if (onAbandoned) {
try { onAbandoned(result); } catch (err) {
console.error(`❌ Codex abandoned-response cleanup failed: ${err.message}`);
}
}
return result;
});
watched.catch(() => {});
return Promise.race([watched, cancelled])
.finally(() => signal.removeEventListener('abort', onAbort));
};
/**
* Run ONE bounded text turn against the ChatGPT subscription.
*
* Resolves `{ text, usage, model, effort, effortClamped }`, or rejects with a
* typed `ServerError`. It never resolves with partial text: an interrupted or
* failed turn rejects, so a caller parsing JSON can't be handed half an object.
*
* @param {object} options
* @param {string} options.prompt — the only thing the model is given
* @param {string|null} [options.model] — a catalog id; null uses Codex's default
* @param {string|null} [options.effort] — clamped against the model's catalog entry
* @param {number} [options.timeoutMs]
* @param {AbortSignal|null} [options.signal] — aborting interrupts the turn
* @param {(delta: string) => void} [options.onDelta] — live progress
* @param {object|null} [options.responseSchema] — JSON Schema constraining the
* final assistant message, when the caller needs structured output
*/
export async function runCodexTextTurn({
prompt,
model = null,
effort = null,
timeoutMs = TURN_TIMEOUT_MS,
signal = null,
onDelta = null,
responseSchema = null,
} = {}) {
if (typeof prompt !== 'string' || prompt.trim() === '') {
throw codexError(CODEX_ERROR_CODES.protocol, 'A Codex text turn needs a prompt.', { status: 400 });
}
// An already-aborted signal fires no 'abort' event when a listener is added
// later, so the caller's cancellation has to be honoured here or the turn runs
// (and bills) for an answer nobody is waiting for.
if (signal?.aborted) {
throw turnCancelledError();
}
const benched = getCodexTextTransportBench();
if (benched) {
throw codexError(
CODEX_TURN_ERROR_CODES.transportBenched,
benched.message || 'The ChatGPT subscription is temporarily unavailable.',
{ status: 503, context: { category: benched.category, until: benched.until } },
);
}
const cwd = await ensureTextTurnCwd();
const { effort: resolvedEffort, clamped, reason } = resolveCodexEffort(effort, cachedModelEntry(model));
if (clamped) console.log(`⚠️ Codex effort clamped: ${reason}`);
// The whole turn is pinned to ONE connection, resolved up front rather than
// per request. A thread lives inside a single app-server process, so a
// mid-turn reconnect could not continue it — and `call`'s reconnect would
// silently send this turn's frames to a child that has never heard of its
// thread id.
const owner = await connect();
// `connect()` can spawn and handshake a whole app-server child, which is the
// longest await in this function. Re-read the signal before paying for a
// thread the caller has already abandoned — the up-front check above ran
// several awaits ago, and no listener is registered yet.
if (signal?.aborted) {
throw turnCancelledError();
}
// Raced against the signal: a Stop pressed during the handshake must not wait
// out `REQUEST_TIMEOUT_MS`. No compensation is needed here — the thread is
// ephemeral and no turn exists yet, so nothing is left running to interrupt.
const started = await raceCodexAbort(sendRequest(owner, CODEX_TURN_RPC.threadStart, {
...CODEX_TEXT_THREAD_CONFIG,
cwd,
...(model ? { model } : {}),
}, REQUEST_TIMEOUT_MS), signal);
const threadId = typeof started?.thread?.id === 'string' ? started.thread.id : null;
if (!threadId) {
throw codexError(CODEX_ERROR_CODES.protocol, 'Codex started a thread with no id.');
}
const acc = createTurnAccumulator({ threadId });
let settle = null;
let fail = null;
const finished = new Promise((resolve, reject) => { settle = resolve; fail = reject; });
// `finished` is not awaited until `turn/start` answers, and it can be rejected
// before then (a lost child, an abort, the deadline). Without this parked
// handler that rejection is an UNHANDLED one — which is a process-level crash
// under Node's default policy, not a test-only nuisance. The real error still
// surfaces from the `await finished` below.
finished.catch(() => {});
// Registered BEFORE `turn/start` is sent: the first delta can arrive before
// that request's own response does, and an unregistered thread drops frames.
activeTurns.set(threadId, {
acc,
settle: () => settle(),
fail: (err) => fail(err),
onDelta: typeof onDelta === 'function' ? onDelta : null,
});
const timer = setTimeout(() => {
fail(codexError(CODEX_ERROR_CODES.timeout, `The Codex turn did not finish within ${Math.round(timeoutMs / 1000)}s.`));
}, timeoutMs);
timer.unref?.();
const onAbort = () => fail(turnCancelledError());
// An AbortSignal fires its 'abort' event exactly once; a listener added after
// the fact never runs. An abort raised during `connect()`/`thread/start` has
// to be honoured by re-reading the flag, or the turn streams for the whole
// deadline and bills for an answer nobody is waiting for.
if (signal?.aborted) onAbort();
else signal?.addEventListener('abort', onAbort, { once: true });
try {
// Already aborted: `onAbort` has rejected `finished`, so awaiting it here
// surfaces the cancellation WITHOUT dispatching a turn — no quota is spent,
// and Stop does not have to wait out a `turn/start` response that would
// only be thrown away. The `finally` below still runs the shared cleanup.
if (signal?.aborted) await finished;
// Raced the same way, but this one CAN leave a live turn behind: the
// app-server may accept the turn just after the Stop won. `onAbandoned`
// interrupts it with the id that late response carries, which the `finally`
// below cannot do because `acc.turnId` was never set. The `activeTurns`
// guard is what tells the two apart — the `finally` has already deleted the
// entry by the time an abandoned response lands, whereas a response the
// normal path is still reading finds the thread registered.
const response = await raceCodexAbort(sendRequest(owner, CODEX_TURN_RPC.turnStart, {
threadId,
input: [{ type: 'text', text: prompt }],
sandboxPolicy: { ...CODEX_TEXT_TURN_SANDBOX },
approvalPolicy: CODEX_TEXT_THREAD_CONFIG.approvalPolicy,
...(model ? { model } : {}),
...(resolvedEffort ? { effort: resolvedEffort } : {}),
...(responseSchema ? { outputSchema: responseSchema } : {}),
}, timeoutMs), signal, (late) => {
if (activeTurns.has(threadId)) return;
interruptCodexTurn(owner, threadId, typeof late?.turn?.id === 'string' ? late.turn.id : null);
});
const turnId = typeof response?.turn?.id === 'string' ? response.turn.id : null;
if (turnId) acc.turnId = turnId;
// A turn that completed before its own response was read leaves the
// accumulator terminal with nobody to settle it.
if (acc.status !== 'inProgress') settle();
await finished;
const result = finalizeCodexTurn(acc);
if (result.error) {
throw codexError(
result.canceled ? CODEX_TURN_ERROR_CODES.turnInterrupted : CODEX_TURN_ERROR_CODES.turnFailed,
result.error,
{ context: { category: result.category } },
);
}
// The model Codex ACTUALLY ran, which is the thread's answer rather than the
// request's — a caller that passed `null` still gets told what served it.
const ranModel = typeof started.model === 'string' && started.model ? started.model : (model ?? null);
return { ...result, model: ranModel, effort: resolvedEffort, effortClamped: clamped, clampReason: reason };
} finally {
clearTimeout(timer);
signal?.removeEventListener('abort', onAbort);
// Delete BEFORE the interrupt: this is the flag a late `turn/start`
// response reads to decide whether the turn it carries still has an owner.
activeTurns.delete(threadId);
if (acc.status === 'inProgress') interruptCodexTurn(owner, threadId, acc.turnId);
}
}
/**
* Terminate the app-server child, if one is running.
*
* Registered with the graceful-shutdown sequence so PortOS never leaves an
* orphaned Codex process behind. Safe to call when nothing is running.
*/
export async function stopCodexAppServer() {
// Set FIRST and never cleared: `connect()` checks it before publishing a
// handshake that finished mid-shutdown, so a late resolve cannot leave a live
// `connection` behind for the next call to reuse — or, worse, hand it a closed
// one and have it spawn a replacement child after the shutdown hook ran.
stopped = true;
settleLogin(null);
readinessCache = null;
modelsCache = null;
modelsError = null;
// The child goes down BEFORE any await. `teardown` decides whether to fail
// live turns by comparing `connection` to the dying target, so `connection`
// must still point at it here; and an await first would let a concurrent
// connect publish itself into the gap.
const target = connection || connectingTarget;
if (target && !target.closed) {
stopTarget(target, codexError(CODEX_ERROR_CODES.exited, 'PortOS is shutting down the Codex app-server.'));
console.log('🔌 Codex app-server stopped');
}
connection = null;
// Drain a scratch directory that is still being created, or its `mkdtemp`
// resolves after shutdown and leaves the directory behind for good.
const pending = creatingTextTurnCwd
? await creatingTextTurnCwd.catch(() => null)
: null;
const scratch = textTurnCwd || pending;
textTurnCwd = null;
creatingTextTurnCwd = null;
if (scratch) {
await rm(scratch, { recursive: true, force: true })
.catch((err) => console.error(`❌ Failed to remove the Codex text scratch directory: ${err.message}`));
}
}
/**
* Test-only: how many turns are still registered.
*
* A leaked entry is invisible from the outside — it neither fails a turn nor
* throws — but it strands the accumulator and misroutes every later event for
* that thread id, so the cancellation paths assert against it directly.
*/
export function __codexActiveTurnCount() {
return activeTurns.size;
}
/** Test-only: drop every module-level handle so a suite starts clean. */
export function __resetCodexAppServer() {
if (pendingLogin) clearTimeout(pendingLogin.timer);
pendingLogin = null;
readinessCache = null;
connection = null;
connecting = null;
connectingTarget = null;
activeTurns.clear();
modelsCache = null;
modelsError = null;
textTransportBench = null;
textTurnCwd = null;
creatingTextTurnCwd = null;
stopped = false;
}