Typed Host Requests vs Ordinary Execution in Prime Agent Python Skills

Typed host requests delegate stateful operations to the TypeScript host via rlm.host_request(), while ordinary execution runs Python code directly inside the kernel's persistent REPL namespace.

Prime Agent enables Python-backed skills to interact with the surrounding TypeScript runtime through two distinct execution models. Understanding when to use typed host requests versus ordinary execution is essential for building secure, stateful agents that properly separate kernel-local computation from host-managed resources.

What Are Typed Host Requests?

Typed host requests are specialized calls that delegate authority to the TypeScript host for operations requiring persistent state management or sensitive operations. In packages/coding-agent/src/core/tools/ipython.ts, Python skills invoke these through rlm.host_request("<type>", payload), which serializes the request and sends it as a host_request event over the JSON-lines stdio bridge.

The TypeScript host validates the request and owns the resulting state transition. This pattern keeps critical logic—such as credentials, provider calls, usage accounting, and scheduling—outside the Python kernel. According to the documentation in packages/coding-agent/docs/rlm.md, this approach is used for capabilities where "authoritative state belongs outside the kernel."

Common implementations include:

• goal.get and goal.set for persistent goal state management
• agent_message.send for inter-agent communication
• rlm_heartbeat and compact for agent lifecycle management

# Typed host request fetching a goal state

reply = await rlm.host_request("goal.get", {"type": "goal.complete"})
print(reply)  # Host returns the authoritative goal state

What Is Ordinary Execution?

Ordinary execution refers to direct Python code evaluation inside the persistent REPL environment. When skills use await rlm("task"), await rlm.run("task"), or standard Python statements, the code executes locally within the kernel process without host validation.

State lives inside the REPL's namespace, allowing the Python environment to read files, import modules, and manipulate local variables. Results return as standard result or display events through the same stdio bridge, but the host does not intermediate in the computation.

# Ordinary execution spawning a child agent

handle = await rlm("Review the authentication flow", name="auth-reviewer")
print(handle.rlm_child_id, handle.session_dir)

# Child runs independently; results arrive via ordinary agent_message events

Key Differences Between Typed Host Requests and Ordinary Execution

The architectural distinction centers on state ownership and security boundaries:

Aspect	Typed Host Requests	Ordinary Execution
State Authority	TypeScript host validates requests and owns state transitions	Python kernel maintains local state in REPL namespace
Transport	host_request events via JSON-lines stdio to ReplKernelManager, then forwarded to AgentSession	Direct kernel execution; results returned as result or display events
Security	Sensitive operations (credentials, scheduling) remain outside Python	Python code has full access to filesystem and kernel state
Typical Uses	Goal management, agent messaging, heartbeat, compaction	Arbitrary scripts, skill functions, child agent spawning

As described in packages/coding-agent/docs/rlm-runtime.md, the host-request flow ensures that "state and policy remain in the TypeScript host" while the kernel performs computational work.

When to Use Each Pattern in Prime Agent

Use typed host requests when your skill needs to:

• Persist data across sessions using goal operations
• Send messages to other agents through agent_message
• Trigger lifecycle events like rlm_heartbeat or compact
• Access host-managed resources that require validation

Use ordinary execution when your skill needs to:

• Run computational algorithms or data processing
• Spawn child agents via the rlm() API
• Execute bash commands or file system operations
• Maintain temporary variables during a single session

Implementation in the Source Code

The separation between these patterns is implemented across several key files in the PrimeIntellect-ai/prime-agent repository:

• packages/coding-agent/src/core/kernel/repl-manager.ts (lines 17-33): Implements the stdio protocol, validates host_request frames, and dispatches them to the host's AgentSession
• packages/coding-agent/src/core/tools/ipython.ts: Provides the Python rlm shim exposing both host_request and ordinary RLM calls
• packages/coding-agent/docs/rlm.md: Documents the host bridge architecture and typed request patterns
• packages/coding-agent/docs/rlm-runtime.md: Details the runtime architecture distinguishing host-request flows from local execution

Summary

• Typed host requests use rlm.host_request() to delegate stateful operations to the TypeScript host, ensuring security and persistence for goals, messaging, and lifecycle events.
• Ordinary execution runs Python code directly in the kernel REPL, providing full computational access but keeping state local to the session.
• The ReplKernelManager in repl-manager.ts routes typed requests to the host while allowing ordinary code to execute within the kernel namespace.
• Choose typed host requests for cross-session state and inter-agent communication; use ordinary execution for computational tasks and local file operations.

Frequently Asked Questions

How does rlm.host_request() differ from calling rlm() directly?

rlm.host_request() serializes the call as a structured event sent to the TypeScript host for validation and state management, while direct rlm() calls execute Python code locally within the kernel's REPL environment without host intermediation.

Can ordinary execution access host-managed goals?

No. Accessing persistent goals requires typed host requests via rlm.host_request("goal.get", ...) because the host owns the authoritative goal state. Ordinary execution can only manipulate temporary variables within the current kernel session.

What happens if a typed host request fails validation?

The TypeScript host rejects the request before any state transition occurs, returning an error to the Python kernel through the stdio bridge. This prevents invalid operations from affecting shared resources like agent messaging or goal states.

Where is the stdio bridge protocol defined?

The JSON-lines stdio bridge implementation resides in packages/coding-agent/src/core/kernel/repl-manager.ts, which handles both host_request events for typed requests and standard execution results, forwarding typed requests to the AgentSession for processing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}