Skip to main content

Crate kernel

Crate kernel 

Source
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.py and 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.rs checks 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 with fields.
snapshot
Host-side snapshot authentication (port of snapshot-auth.ts) and the kernel’s snapshot/restore reports (KernelSnapshotReport / KernelRestoreReport of kernel.ts).
snapshot_store
Where the snapshot signing key lives (snapshot-auth.ts loadSnapshotKey, secretToolKeyring): ULTRON_RLM_SNAPSHOT_KEY_STORE = file (default) keeps <agentDir>/rlm-snapshot.key; auto moves the key into the OS keyring when one answers (through libsecret’s secret-tool), leaving a marker file; keyring insists on the keyring and otherwise uses a key for this process only. Exposure reduction, not secrecy: model code runs as the same user. secret-tool is found on the session’s PATH only, 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§

CellError
EchoHandler
Test handler: replies {"type": kind, "payload": payload}, and refuses test.fail with “refused test.fail”.
ExecutionResult
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.
KernelError
A failed call: the kernel failed, was shut down, the call was cancelled, or its request could not be sent.
KernelOptions
KernelReply
A call’s full reply: the result plus the snapshot or restore report a done frame carried (kernel.ts KernelExecutionResult with snapshot? / restore?), and, on the first cell after a recovery, what it restored and lost.
KernelResourceLimits
Per-kernel resource limits; 0 disables one. Resource limits, not isolation.
LimitOverrides
Explicit limits that take precedence over the environment.
Link
A Signal::link listener, removed when this drops.
Signal
Cancellation, like an AbortSignal: aborted once, with a reason. A call’s signal cancels it; the signal a HostHandler receives is aborted when its cell completes or fails.
TreeMemoryOptions
How a kernel caps the memory of its whole process tree (tree_memory).

Enums§

Status

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§

HostHandler
Serves host requests from Python (await rlm.host_request(type, payload) and every API built on it). Runs on its own thread per request; signal is 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). Err becomes a RuntimeError with 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_ALLOW lists names (comma-separated) to pass through anyway.
kernel_resource_limits
Limits from ULTRON_RLM_MAX_MEMORY_MB and ULTRON_RLM_MAX_CPU_SECONDS (read through lookup), 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’s Number reads it), else 20 KB, within 1 KB..128 KiB.
sees
Whether viewer’s kernel sees work owned by owner: the root lane sees every lane’s, a child lane its own.