01_runtime.md

Runtime SOT

Entrypoints

Path	Responsibility
bin/ocx.mjs	Published npm bin entry (Node shim). Resolves the bundled Bun binary (bun dependency), lazy-runs its install.js if only the placeholder stub is present, then execs src/cli/index.ts under Bun. Lets npm install -g work without a separately-installed Bun.
src/lib/bun-runtime.ts	Bundled-Bun resolution: isRealBunBinary() (size gate vs the ~450-byte placeholder stub), bundledBunPath(), durableBunPath() (path baked into service/shim artifacts).
src/cli/index.ts	ocx / opencodex CLI: init, start, stop, restore/eject, sync, status, login/logout, gui, service, update. After help/version early exits, ordinary commands run the bounded best-effort Codex-shim auto-restore policy before dispatch. Keeps the #!/usr/bin/env bun shebang for from-source dev (bun run src/cli/index.ts).
src/server/index.ts	Bun server entrypoint: startServer, /v1/responses HTTP + WebSocket routing, exact POST /v1/images/generations and POST /v1/images/edits routing, /v1/models, /v1/* JSON 404 guard, GUI fallback, and facade re-exports for split server modules.
src/server/images.ts	Standalone Images data plane: default OpenAI or explicit custom-provider selection, Codex account affinity, bounded opaque request relay, single-attempt upstream fetch, pool health recording, and safe response/cancellation relay.
src/config.ts	~/.opencodex/config.json, defaults, PID path, env-value resolution, websocketsEnabled().
src/router.ts	Provider/model selection before adapter dispatch.
src/types.ts	Shared config, parsed request, adapter, and event types.
src/reasoning-effort.ts	Codex reasoning-level definitions (low/medium/high/xhigh), per-model effort mapping, and catalog effort sanitization.
src/codex/shim.ts	Codex autostart shim: replaces the codex binary with a wrapper that auto-starts the proxy on demand. It skips startup for management subcommands even when value-taking global flags precede the subcommand, and transactionally restores complete, stable external launcher replacements without a watcher or PATH rediscovery.
src/service.ts	OS service manager (macOS launchd, Linux systemd, Windows schtasks): always-on proxy with crash restart.

The src/ root stays thin: process entry, shared config/types, router, bridge, service manager, and reasoning effort definitions live there. Feature code is grouped under src/adapters/, src/codex/, src/cli/, src/oauth/, src/providers/, src/responses/, src/server/, src/update/, src/usage/, src/vision/, src/web-search/, and src/lib/.

src/server/ is split by responsibility: index.ts owns the listener and route ordering; responses.ts owns Responses handling and compaction; images.ts owns the standalone Images relay; management-api.ts owns /api/*; lifecycle.ts, request-log.ts, relay.ts (incl. the shared createSseInspector SSE inspection factory), relay-eager.ts (#314 gated eager bounded passthrough relay), memory-watchdog.ts (warn-only RSS sampler), management/system-routes.ts (/api/system/*), and auth-cors.ts own server infrastructure (src/lib/bun-stream-caps.ts owns the Bun stream-capability gate); and static GUI, WebSocket bridge, port/liveness, decompression, and adapter-resolution helpers live in their own files.

Lifecycle

ocx start refuses a duplicate PID, starts the proxy, writes ~/.opencodex/ocx.pid, syncs Codex config/catalog, then serves until shutdown. Normal shutdown restores native Codex. Service mode sets OCX_SERVICE=1, so managed restarts do not repeatedly restore/reinject; explicit service stop and uninstall still restore.

An installed Codex shim is checked on ordinary CLI startup with a regular-file/1 MiB state bound plus bounded metadata and prefix reads. A complete replacement must produce identical fingerprints and prefixes across a 100 ms observation interval; changing launchers are silently deferred, while mixed sibling sets warn and defer as a unit. Guarded repair holds a self-identifying atomic-mkdir interprocess lock across its final revalidation, rename, shim write, and state commit. Its owner record uses the unique token as the filename, so stale-owner deletion cannot name a successor's record. An aged lock is reclaimed only when its owner PID is no longer alive and the same token, lock-directory identity, and owner fingerprint are still present immediately before deletion. Repair preflights every tracked sibling before mutation and rolls back earlier siblings in reverse order on a later race. Failures warn without changing the requested command's exit behavior. The probe uses read-only config diagnostics only for a confirmed candidate and never reads adjacent auth state.

The bridge enforces a heartbeat stall deadline: after 5 minutes (150 ticks at the default 2 s interval) of upstream silence with no real events, the stream is closed and the upstream request cancelled. If the adapter generator ends without an explicit done/error event, the response is marked incomplete rather than completed so Codex can distinguish a clean finish from a truncated stream.

The server exposes POST /api/stop which restores native Codex config, stops any installed service (to prevent respawn), and exits the process. The GUI sidebar stop button calls this endpoint.

Providers and adapters

Path	Responsibility
src/providers/registry.ts	Canonical provider presets for CLI, dashboard, OAuth, key providers, and metadata.
src/providers/derive.ts	Enrichment from provider presets into user config.
src/oauth/	OAuth providers, token storage, refresh, and auth-token resolution.
src/adapters/openai-responses.ts	Native OpenAI/ChatGPT Responses passthrough.
src/adapters/openai-chat.ts	OpenAI-compatible Chat Completions bridge.
src/adapters/anthropic.ts	Anthropic Messages bridge.
src/adapters/google.ts	Gemini bridge.
src/adapters/azure.ts	Azure OpenAI bridge.

Adapter output must stay in internal AdapterEvent form until bridge.ts converts it back to Responses SSE or WebSocket frames.