# Typed Host Requests vs Ordinary Execution in Prime Agent Python Skills

> Understand typed host requests vs ordinary execution in Prime Agent Python skills. Learn how typed host requests delegate stateful operations to the TypeScript host, while ordinary execution runs Python code directly within the...

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: deep-dive
- Published: 2026-09-05

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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

```python

# 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.

```python

# 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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm.md): Documents the host bridge architecture and typed request patterns
- [`packages/coding-agent/docs/rlm-runtime.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.