packages prime agent runtime

Python runtime

Active contributors: kt, Sebastian Müller, Seth Karten

prime-agent-runtime is the Python side of the IPython-harness programming model. It is a small package (rlm, version 0.1.0, Python >= 3.10) that runs inside the persistent Jupyter kernel that Prime Agent keeps as the model's main tool. It gives the model callable recursion (rlm(...)), a persistent harness-state store, the bridge for MCP-based tool integrations, and CLI helpers for Python skills. Execution itself stays in the TypeScript host: the kernel-side code mostly marshals requests to the host over Jupyter comms and back.

Purpose

• Provide the rlm object the kernel namespace binds, so the model can spawn recursive subagents, search models, and manage its own subagent registry.
• Provide harness, a persistent CRUD store for prompt notes, memory items, skill records, subagent specs, and recorded refinement events.
• Provide McpIntegration, the base class that Python skill packages subclass to expose MCP server tools as plain await-able methods.
• Provide skill.cli / run_cli so a skill's run() can be invoked from a shell console script.

Directory layout

prime-agent-runtime/
├── pyproject.toml        # Hatchling build, deps: ipykernel, nest-asyncio, tyro
├── src/
│   └── rlm/
│       ├── __init__.py   # rlm callable, harness, host_request, subagent registry API
│       ├── harness.py    # HarnessState CRUD store, HarnessEntry, RefinementEvent
│       ├── mcp_base.py   # McpIntegration base class for MCP-client integrations
│       └── skill.py      # run_cli / cli helpers for skill console scripts
└── test/                 # pytest (unittest-style)
    ├── test_harness.py
    ├── test_mcp_base.py
    ├── test_subagent_registry.py
    └── test_agent_message_skill.py

Key abstractions

Type	Full path	Description
rlm (callable module)	prime-agent-runtime/src/rlm/__init__.py	Kernel-namespace object; rlm(prompt) spawns a recursive subagent, plus rlm.find_models, rlm.list_subagents, rlm.delete_subagent
harness / get_harness_state	prime-agent-runtime/src/rlm/harness.py	Persistent CRUD store for prompt, memory, skill, and subagent entries plus refinement events
HarnessState	prime-agent-runtime/src/rlm/harness.py	File-backed store (JSON, schema 1) with local/global scoping and out-of-process write detection
HarnessEntry	prime-agent-runtime/src/rlm/harness.py	One record: id, kind, title, content, path, scope, reference, arguments, metadata, timestamps, version
McpIntegration	prime-agent-runtime/src/rlm/mcp_base.py	Base class for MCP-client skill packages; auto-binds server tools as async methods
host_request	prime-agent-runtime/src/rlm/__init__.py	Sends a typed request to the TypeScript host over a Jupyter comm (host.request) and awaits the reply
run_cli / cli	prime-agent-runtime/src/rlm/skill.py	Parse CLI args for a skill function with tyro and call its run()

How it works

Kernel namespace and the host bridge

When a kernel starts, packages/coding-agent injects bootstrap code (RLM_BOOTSTRAP_BASE_CODE in packages/coding-agent/src/core/tools/ipython.ts) that imports rlm and binds rlm in the kernel namespace. If prime-agent-runtime is missing, it installs a _PrimeAgentMissingRlm stub that raises an instructive error instead. The rlm module is callable (_CallableModule), so await rlm("prompt") works alongside rlm.run(...).

Kernel-to-host communication goes over Jupyter comms. host_request(request_type, payload) in prime-agent-runtime/src/rlm/__init__.py opens a comm with target host.request and awaits a reply; the TypeScript host dispatches on the type field. rlm.run sends "rlm.run" and returns a spawn handle (rlm_child_id, name, session_dir, model), never the child's answer; results arrive later through agent_message replies or files.

Harness state

HarnessState in prime-agent-runtime/src/rlm/harness.py is a JSON file (schema 1) holding four entry kinds (prompt, memory, skill, subagent) plus a refinement-event log. The default file is harness_state.json under the session's harness/ dir; local state resolves from RLM_HARNESS_STATE_DIR or RLM_SESSION_DIR, global state from RLM_GLOBAL_HARNESS_STATE_DIR, falling back to ~/.prime/agent. It records an mtime on each load/save and reloads when the file changed on disk, so host-side /refine writes are not clobbered by the long-lived kernel copy. In forked kernels the state is resolved per access (_HarnessProxy), because a state bound at import time would freeze the pre-fork, env-less resolution. Skill entries are validated to carry a Python reference (type: "python", an import, and a callable).

MCP integrations

McpIntegration in prime-agent-runtime/src/rlm/mcp_base.py is subclassed by integration skill packages (for example a linear package). It targets a named MCP server, reads credentials from the host's auth.json under the mcp:<server> key, and on token expiry asks the host to refresh via host_request("mcp.refresh", ...). Tools are discovered lazily and bound as async methods through __getattr__, so the model writes issues = await linear.list_issues(team="Engineering"). The mcp SDK is imported lazily so import rlm never requires it. NotEnabled tells the model to direct the user to /mcp login, and McpToolError surfaces server-flagged tool errors.

Subagent registry

The kernel side exposes rlm.list_subagents() and rlm.delete_subagent(target) in prime-agent-runtime/src/rlm/__init__.py, both implemented as host_request calls ("rlm.list_subagents", "rlm.delete_subagent") that validate the returned entries into RLMSubagent records (rlm_child_id, session ids, session_name, session_dir, status in running/completed/error). The registry itself lives host-side in packages/coding-agent/src/core/rlm-runtime.ts (RlmSubagentRegistryEntry, createRlmListSubagentsHostHandler, createRlmDeleteSubagentHostHandler), which the parent session backs.

Skills as importable Python packages

prime-agent-runtime/src/rlm/skill.py provides run_cli(func), which parses CLI arguments for a skill function via tyro and prints a non-None result, and cli(), a console-script helper that imports the module named after sys.argv[0] and runs its run(). An example skill lives at packages/coding-agent/skills/agent-message, and prime-agent-runtime/test/test_agent_message_skill.py imports and exercises it directly.

How it is installed and launched

• Editable install: pip install -e prime-agent-runtime (dependencies: ipykernel, nest-asyncio, tyro).
• The kernel is bootstrapped automatically on first use by ensureKernelPython in packages/coding-agent/src/core/kernel/bootstrap.ts: if PRIME_AGENT_KERNEL_PYTHON is set it must be a Python with ipykernel and a current prime-agent-runtime installed; otherwise the host creates ~/.prime/agent/kernel-venv (override with PRIME_AGENT_KERNEL_VENV), installing Python, ipykernel, prime-agent-runtime, and default packages.
• Manual bootstrap: scripts/setup-kernel-venv.sh runs npx tsx packages/coding-agent/src/core/kernel/bootstrap-cli.ts, which calls ensureKernelPython() and prints the resolved kernel python.
• IpythonKernelProvisioner in packages/coding-agent/src/core/tools/ipython.ts owns the running KernelManager: it can prewarm() the kernel in the background, and ensure() starts or reuses it. Kernel startup runs under withKernelBootPermit from packages/coding-agent/src/core/kernel/boot-gate.ts so only one boot runs at a time.

Entry points for modification

• Add a kernel API: extend host_request handling in the TypeScript host (packages/coding-agent/src/core/kernel/index.ts exports HostRequestHandlers) and add a typed wrapper in prime-agent-runtime/src/rlm/__init__.py.
• Add an integration: subclass McpIntegration in a new skill package under packages/coding-agent/skills/.
• Change harness storage or the refinement log: prime-agent-runtime/src/rlm/harness.py, keeping the schema-versioned JSON format and disk-mtime sync.
• Change kernel bootstrap or venv setup: packages/coding-agent/src/core/kernel/bootstrap.ts and scripts/setup-kernel-venv.sh.

Key source files

Path	Purpose
prime-agent-runtime/pyproject.toml	Package metadata, build backend, dependencies
prime-agent-runtime/src/rlm/__init__.py	rlm callable, harness, host_request, run, find_models, subagent registry API, lazy MCP exports
prime-agent-runtime/src/rlm/harness.py	HarnessState CRUD store, HarnessEntry, RefinementEvent, scoping and disk sync
prime-agent-runtime/src/rlm/mcp_base.py	McpIntegration, McpToolError, NotEnabled
prime-agent-runtime/src/rlm/skill.py	run_cli and cli for skill console scripts
prime-agent-runtime/test/test_harness.py	Harness CRUD, scoping, refinement, disk sync tests
prime-agent-runtime/test/test_mcp_base.py	MCP integration, token resolution, tool binding tests
prime-agent-runtime/test/test_subagent_registry.py	rlm.list_subagents / rlm.delete_subagent tests
prime-agent-runtime/test/test_agent_message_skill.py	Tests for the agent-message skill package
packages/coding-agent/src/core/tools/ipython.ts	IpythonKernelProvisioner, bootstrap code, kernel tool
packages/coding-agent/src/core/kernel/bootstrap.ts	Kernel python resolution and venv setup

Related pages

• Coding agent - the full harness runtime
• RLM programming model - recursion, subagents, and the registry
• Session runtime - IPython kernel provisioning
• Skills - skills as Python packages
• Getting started - install instructions