Kernel — the persistent Python kernel + continual harness
Owns: the persistent kernel's mechanism — kernel_exec/state/refine, the sidecar protocol, and the tool bridge. Not for: the composable provider runtime (harness.md).
Plan 015. Implements persistent execution and learned state for operant under the
replace, never duplicate contract, extended with the RLM-lite tool bridge.
Host-side source: crates/operant-core/src/tools/kernel/ (mod, runtime,
sidecar, kernel_tool, harness_tools, tool_bridge); sidecar:
kernel-sidecar/kernel_sidecar/server.py.
What you get
| Tool | Purpose |
|---|---|
kernel_exec |
Run Python in a persistent kernel: variables and imports survive across turns. Cells support top-level await. With the bridge enabled, cells can call allowlisted operant tools: await operant_tool("file_list", {...}) — one call replaces dozens of model turns for sweeps/batches. |
kernel_state |
Read the continual-harness store: prompt (behavioral policy addendums) and subagent (reusable delegation specs), scoped local (THIS session) or global (cross-session). |
kernel_refine |
Record or apply an evidence-backed refinement. With edits[]: all-or-nothing CRUD with a snapshot kept for byte-exact rollback. |
Architecture
model ─▶ kernel_* tools (Rust, gated "kernel" toolset)
│ NDJSON JSON-RPC over stdio
▼
KernelSidecarSupervisor ─ spawns ─▶ kernel-sidecar (python ≥3.11)
├─ SessionKernel (persistent namespaces)
└─ HarnessService (live vendored rlm)
kernel cells ─ await operant_tool(...) ─▶ host dispatches through the SAME
approval gate as direct calls
Policy lives in the Rust host (allowlist, caps, approval parity); state lives in
the sidecar. The harness imports vendored rlm package from the
pinned vendor/vendored rlm submodule — git submodule update --remote pulls
upstream improvements with no code changes here.
Session lifecycle
- Per-turn cache:
injection_block()caches the[continual harness]text for 5s per session, so concurrent tool calls within one turn pay at most one sidecar roundtrip. Anykernel_refine/kernel_statewrite invalidates the cache. - Session GC:
<state_dir>/sessions/<id>dirs older thansession_gc_ttl_hours(default 168h, 0 = disabled) are pruned at startup and every ~hour by the idle reaper. Best-effort, never blocks boot.
Executable skills (SKILL.toml [reference], plan 016)
When [tools.kernel.pyskill] enabled = true and the import is allowlisted, a skill can bind a Python callable directly into the kernel:
[skill]
name = "pdf-extract"
description = "Extract text from PDFs"
[reference]
type = "python"
import = "my_pdf_lib"
callable = "extract_text"
call_pattern = "await extract_text(path)"
import/callableare bound viakernel.bind_skill(import, callable)into every session's globals on first use (ImportError is captured as_<callable>_import_error).call_patternis surfaced in the volatile[continual harness]suffix asexecutable skills: - pdf-extract: await extract_text(path) # from my_pdf_lib::extract_text.- Audit:
audit.rswarns when aSKILL.tomlcontains[reference]but the allowlist is empty orpyskill.enabledis false — the reference will be ignored at injection time. - Security:
allowed_importsis deny-by-default ([]). Supports exact ("my_pkg") and prefix ("my_pkg.*") globs, plus*/?wildcards. No auto-authoring in 016 — only hand-curated references.
Replaces / complements / untouched
- Replaces interactive stateless Python execution once
[tools.kernel] route_python_to_kernel = true:code_executionpython requests run in the session kernel ("via": "kernel"marker) and fall back to the subprocess path if the sidecar is down. - Complements agentmemory/MEMORY.md (facts) and skills (procedures): the harness holds ONLY the two kinds operant lacked — prompt notes and subagent specs — in per-session local stores plus one global store.
- Untouched: curator, SkillImprover, learning graph, SkillForge, SubAgentTool/delegation, MCP/cron/gateway.
- Feed-forward: with
harness_auto_learn = true, the existing background review fork may additionally emit prompt/subagent lessons viakernel_refine. No second review loop exists.
Configuration
[tools.kernel]
enabled = false # flip after provisioning (below)
python = "" # optional; ≥3.11 (auto-detected otherwise)
state_dir = "" # default ~/.local/share/operant/kernel/harness
sidecar_idle_secs = 1800 # idle child auto-exit (0 = never)
request_timeout_secs = 120 # per-cell wall clock
max_output_bytes = 200_000
route_python_to_kernel = false # phase-4 cutover switch
harness_auto_learn = false # phase-5 background-review lane
[tools.kernel.tool_bridge]
enabled = false
allowlist = ["file_list", "file_read", "web_search", "http_request"] # deny-by-default
max_calls_per_exec = 64
per_call_timeout_secs = 60
Provisioning
git submodule update --init --recursive # vendor/vendored rlm @ pinned tag
./scripts/check-kernel-sidecar.sh # uv pytest — must be green
Then set [tools.kernel] enabled = true (and the switches above as you
adopt them). kernel_exec self-reports diagnostics when the sidecar or
submodule is missing.
Security honesty (verbatim from upstream)
Neither the sidecar nor the kernel is a security sandbox: model-generated
Python runs with your user permissions. Mitigations are procedural: the tool
sits behind the same interactive approval gate as code_execution, bridged
tool calls re-enter that gate per call, and the allowlist denies by default.
Run untrusted workloads in an external sandbox.
Rollback: /kernel rollback semantics ship as the refine_rollback protocol;
every applied refinement event keeps its before-snapshot in
<state_dir>/<scope>/refinement-ledger.jsonl.