Expand description
Supervisor for Ultron’s persistent Python kernel: a port of the host side of
packages/coding-agent/src/ultron/rlm/kernel.ts. The Python side is the unchanged runtime.py.
The kernel runs python runtime.py --protocol-fds in its own process group. Protocol frames (one JSON object per
line, at most 1 MiB) arrive on the kernel’s fd 3 and host messages go to its fd 4; stdin is /dev/null, and fd 1 and
fd 2 are plain output attributed to the running cell. After a cell, runtime.py writes a flush marker naming the
cell’s request id to fd 1 and fd 2 and then sends done, listing the markers it wrote; the cell resolves once the
host has read them, so the cell’s raw output is complete.
Calls block; cells run one at a time in call order. A Signal cancels a call: a queued call is rejected without
touching the kernel, a running one kills the kernel’s process tree. Any kernel failure (exit, protocol violation,
startup timeout, CPU backstop) rejects every pending call with an explicit error and loses the Python state; the
next call starts a fresh kernel. Host requests from Python go to a HostHandler, each on its own thread.
Snapshots (kernel.ts snapshot/restore): runtime.py writes a data-only snapshot of the namespace; the host
signs it with an HMAC key the kernel never sees and verifies the signature before the kernel may read it back.
With snapshot_path a new kernel restores it before its first call; once a started kernel failed or a running
call was cancelled it does not (kernel.ts never silently resurrects an older checkpoint). A ContinuityPolicy
replaces that rule: checkpoints follow every cell, a dead kernel is restarted and restored at once, and the next
cell result reports what was restored and lost (see continuity).
Re-exports§
pub use continuity::ContinuityPolicy;pub use continuity::ContinuityReport;pub use continuity::LostName;pub use snapshot::RestoreReport;pub use snapshot::SnapshotReport;pub use snapshot::load_or_create_snapshot_key;pub use snapshot::process_snapshot_key;pub use snapshot::sign_snapshot;pub use snapshot::verify_snapshot;pub use tree_memory::TreeMemoryBackend;
Modules§
- continuity
- Kernel state continuity (Rust-only; kernel.ts has none): the REPL’s state survives a kernel crash or restart.
- env
- The environment variables the kernel process and its Python runtime (
runtime.pyand its modules) read, where a subagent’s worktree lives, and the interpreter the kernel runs. - ops
- The host requests runtime.py’s clients (
packages/coding-agent/src/ultron/rlm/*.py) send, one row per op: the module that serves it, the payload keys it takes and the reply keys the clients read.tests/ops.rschecks the Python clients against this table (every op they send is a row, every row is sent, no key outside its row), and handlers refuse other payload keys withfields. - snapshot
- Host-side snapshot authentication (port of
snapshot-auth.ts) and the kernel’s snapshot/restore reports (KernelSnapshotReport/KernelRestoreReportof kernel.ts). - snapshot_
store - Where the snapshot signing key lives (
snapshot-auth.tsloadSnapshotKey,secretToolKeyring):ULTRON_RLM_SNAPSHOT_KEY_STORE=file(default) keeps<agentDir>/rlm-snapshot.key;automoves the key into the OS keyring when one answers (through libsecret’ssecret-tool), leaving a marker file;keyringinsists on the keyring and otherwise uses a key for this process only. Exposure reduction, not secrecy: model code runs as the same user.secret-toolis found on the session’sPATHonly, and runs with the session’s desktop variables. - store
- One JSON document replaced whole on every write (
HostModuleStore): the host modules’ documents, the shell job journal, the task journal, and the typed agents’ definitions and usage ledger. - tree_
memory - Whole-tree memory cap for a kernel: the kernel plus every process its cells spawn (tree-memory.ts).
Structs§
- Cell
Error - Echo
Handler - Test handler: replies
{"type": kind, "payload": payload}, and refusestest.failwith “refused test.fail”. - Execution
Result - What a cell (or another request) produced. Serializes as kernel.ts
KernelExecutionResult. - Kernel
- One kernel: a sequence of Python processes (generations), each replaced after a failure.
- Kernel
Error - A failed call: the kernel failed, was shut down, the call was cancelled, or its request could not be sent.
- Kernel
Options - Kernel
Reply - A call’s full reply: the result plus the snapshot or restore report a done frame carried (kernel.ts
KernelExecutionResultwithsnapshot?/restore?), and, on the first cell after a recovery, what it restored and lost. - Kernel
Resource Limits - Per-kernel resource limits; 0 disables one. Resource limits, not isolation.
- Limit
Overrides - Explicit limits that take precedence over the environment.
- Link
- A
Signal::linklistener, removed when this drops. - Signal
- Cancellation, like an
AbortSignal: aborted once, with a reason. A call’s signal cancels it; the signal aHostHandlerreceives is aborted when its cell completes or fails. - Tree
Memory Options - How a kernel caps the memory of its whole process tree (
tree_memory).
Enums§
Constants§
- ROOT_
LANE - The root agent’s lane; every other lane is a child’s (the session journal’s
session_journal::run::MAIN_LANE).
Traits§
- Host
Handler - Serves host requests from Python (
await rlm.host_request(type, payload)and every API built on it). Runs on its own thread per request;signalis aborted when the requesting cell completes, Python cancels the request, or the kernel fails. The outcome is still sent while the kernel lives (Python drops one nobody awaits).Errbecomes aRuntimeErrorwith that message in Python.
Functions§
- kernel_
environment - Environment for model-written Python: credentials and the session worker’s control variables are removed so the
kernel gets no ambient authority.
ULTRON_RLM_ENV_ALLOWlists names (comma-separated) to pass through anyway. - kernel_
resource_ limits - Limits from
ULTRON_RLM_MAX_MEMORY_MBandULTRON_RLM_MAX_CPU_SECONDS(read throughlookup), then overrides. A malformed value falls back to the default; a value over 2^53 - 1 is an error, as in TypeScript. - kill_
command_ group - SIGKILLs the process group the host created for one command (its leader’s
pgid), through [command_group_target]; whether a signal was sent. - rlm_
output_ budget - The byte budget for one cell’s captured stream:
ULTRON_RLM_OUTPUT_BYTES(as JavaScript’sNumberreads it), else 20 KB, within 1 KB..128 KiB. - sees
- Whether
viewer’s kernel sees work owned byowner: the root lane sees every lane’s, a child lane its own.