The kernel bootstrapper in bootstrap.ts manages the IPython kernel's Python environment—pinning Python 3.11, validating cached state via a schema version file, and pre-installing mandatory packages (ipykernel, prime-agent-runtime, dill) plus 12 optional RLM packages. Bootstrap operations are guarded by file-level locking and in-flight deduplication to prevent concurrent races, with optional forkserver acceleration (v0.2.4+) that spawns subagent kernels from a pre-imported template rather than cold booting each time.
The kernel bootstrapper lives in packages/coding-agent/src/core/kernel/bootstrap.ts and manages the IPython kernel's Python environment, pinning the managed Python version to 3.11 via the PYTHON_VERSION constant.[1] A BOOTSTRAP_SCHEMA = 8 constant tracks the bootstrap schema version; any change that invalidates a cached bootstrap environment must bump this constant.[1] The bootstrap version is persisted in a .bootstrap-version file alongside the environment, allowing the bootstrapper to detect and invalidate stale environments without running the full install.[1] The BootstrapVersion interface records schema number, ipykernel version, runtime version, snapshot (dill) version, extraUvArgs, and pythonSkills with their pyprojectHash; a hash mismatch forces a reinstall.[1]
Three Python packages are mandatory in every kernel environment: ipykernel, prime-agent-runtime, and dill.[1] dill is used exclusively for serializing the kernel's user namespace so it can be revived across session resume; it is intentionally not surfaced to the model as an importable package.[1]
The RLM kernel environment pre-installs 12 Python packages by default, defined in DEFAULT_RLM_EXTRA_PACKAGES: requests, httpx, pyyaml (imported as yaml), tomli, python-dotenv (imported as dotenv), pandas, numpy, scipy, beautifulsoup4 (imported as bs4), lxml, pydantic, and tyro.[1] Three derived arrays are exported from the same file — DEFAULT_RLM_EXTRA_UV_ARGS, DEFAULT_RLM_EXTRA_IMPORT_NAMES, and DEFAULT_RLM_EXTRA_IMPORT_LABELS — used for uv installation, import validation, and prompt generation respectively.[1]
uv is the Python package manager used by the bootstrapper; if it is absent, the fallback install command is curl -LsSf https://astral.sh/uv/install.sh | sh.[1]
The runtime readiness check asserts that rlm.harness and rlm.rlm.harness each expose all 13 required harness methods: create_memory, update_memory, delete_memory, create_skill, update_skill, delete_skill, create_subagent, update_subagent, delete_subagent, create_prompt_note, update_prompt_note, delete_prompt_note, and record_refinement.[1] The same check (RUNTIME_READY_CHECK) asserts that rlm does NOT have a background attribute (assert not hasattr(rlm, 'background')), enforcing that the removed background API is absent.[1] Additionally, the readiness check validates that HarnessEntry has reference and scope dataclass fields, that create_skill and update_skill accept a reference parameter, and that create_memory and get_harness_state accept a global_ parameter.[1]
Bootstrap concurrency is guarded by a file-level lock (BOOTSTRAP_LOCK_NAME = ".bootstrap.lock") with a 100 ms retry interval and a 30-second stale-lock timeout when the owning PID is absent.[1] An in-flight deduplication guard (inFlightEnsureKernelPython) ensures that concurrent callers sharing the same cache key share a single bootstrap promise rather than racing.[1] In v0.2.4, concurrent kernel boots during large subagent fan-outs were bounded by a process-wide semaphore with a default of min(16, 2*cores), overridable via PRIME_AGENT_MAX_CONCURRENT_KERNEL_BOOTS.[2] A parent-watchdog mechanism — spanning fork-server-script.ts, fork-server.ts, and kernel/index.ts — monitors the owning process and self-terminates the kernel when that owner dies, preventing orphaned kernel processes.
The EnsureKernelPythonOptions interface accepts an optional pythonSkills array (of KernelPythonSkill) and an optional onProgress callback of type KernelBootstrapProgressHandler for reporting bootstrap progress messages.[1] A host request contract layer in packages/coding-agent/src/core/kernel/index.ts establishes typed contracts governing how requests from the host environment flow into the kernel, validated via host-request-contract.test.ts and host-request-context.ts. In kernel/index.ts, ZMQ EAGAIN errors raised when the kernel socket is accessed before the kernel has fully started are suppressed, preventing those raw errors from leaking to callers. Corrupt REPL protocol frames are detected and repaired in repl-manager.ts and repl.py rather than propagated, preventing silent data corruption during IPython tool execution. The host-reply envelope in kernel communication is owned exclusively by the dispatcher; reply routing through repl-manager.ts, bootstrap.ts, agent-session.ts, and repl.py must use the dispatcher-owned envelope path.
In v0.2.3, the IPython kernel was changed to stay alive across compaction: variables, imports, and helpers the agent defined are no longer wiped, and the model is instead told which names remain defined.[3] In v0.2.4, a Python forkserver was added (on by default on Linux; opt out with PRIME_AGENT_KERNEL_FORKSERVER=0) that forks subagent kernels from one pre-imported template process instead of a full cold boot each time, with automatic fallback to direct spawn on any failure.[2]
Sources