The Python Surface: How Prime Agent Turns Model Actions into Programs
Prime Agent's defining control surface is not a menu of specialized buttons but a persistent Python environment exposed through the ipython tool. This chapter follows what happens when a repository task enters that environment: how the model composes inspection and command work, what persists between turns, and why the TypeScript host still owns the authoritative parts of execution. The result is a useful distinction for working with Prime Agent: Python is where the model programs its activity, not where the whole agent system or its trust boundary disappears.
The kernel is a workspace for computation, not a second chat
Suppose a user asks Prime Agent to review a repository's authentication changes and report whether the relevant checks cover the new behavior. The task begins with ordinary-looking actions: locate the likely files, inspect their relationships, run the project's checks, and compare the results with the question. The important difference is that Prime Agent does not require the model to treat each action as a separate conversational request.
The model receives one built-in tool, ipython, and uses it as a control environment. Through Python it can read and edit files, run project commands, inspect data, transform results, and invoke installed capabilities. A search can produce a list of candidate files; that list can remain in a variable while the model reads only the relevant material. A command result can be parsed into a structured value instead of being copied into a new prompt. A helper function can encode a small recurring operation. The model is still deciding what to do, but the intermediate work has a place to live that is more precise than prose in a chat transcript.
That is the practical meaning of treating context as a variable. Context is not only text the model must reread. It can be a collection, a parsed report, a path set, a task handle, or a function that turns one observed form into another. Prime Agent's RLM documentation describes the Python surface as the place where the model composes capabilities as code. The code does not make the reasoning automatic; it gives the reasoning a stateful medium in which one step can become input to the next.
The distinction becomes clearer if the review changes direction. An initial search might reveal that authentication behavior is split between a configuration layer and an integration test. Instead of restating the first search in a later turn, the model can retain the paths and its parsed observations, then inspect the new dependency. If the check emits a large result, the model can transform it into the small set of failures relevant to the current question. If a Python-backed skill is installed for a specialized audit, the model can call that capability from the same environment. The visible interaction remains conversational, but the work between messages is programmatic.
Persistence here has a specific scope. Variables, imports, functions, parsed results, and task handles can survive across tool calls and compaction. That lets a long task keep useful working state even when the model no longer sees every earlier message in full. It does not mean that every result becomes a permanent project record. A value in the kernel namespace is not automatically a saved artifact that another person can inspect, and a retained import is not a guarantee that the underlying external data remains unchanged.
Three kinds of state should therefore be kept separate. The Python namespace is short-to-medium-term working state for the current control process. The session transcript records the interaction and can support restoration, branching, or later review. Project files and other artifacts are the durable evidence that can survive independently of the model's current context. Prime Agent makes the first two more capable, but a consequential conclusion still belongs in an inspectable artifact when someone must verify it later.
Take the review request one step further. The model might keep a set of authentication-related files, a normalized list of failing checks, and a note about which result still needs confirmation. Those values let it change the order of inspection without rebuilding the search. They also make the next action explicit: read the integration test, compare it with the configuration path, or run a narrower command. The gain is not that Python has supplied an answer. The gain is that the model can preserve the intermediate objects that support a reasoned answer and can transform them as the question becomes more precise. In a review, that may mean keeping the distinction between a test that passed, a test that was never run, and a test whose output was inconclusive. Those are different facts, and a stateful control surface makes it easier to carry the distinction forward instead of compressing all three into a confident sentence.
That working state has an important limit: it belongs to the live kernel and its session lifecycle. If another person needs to audit the conclusion, a variable name is not enough. The relevant finding, command result, or changed file has to be represented in the session record or in a project artifact that can be inspected without reconstructing the kernel's memory. The RLM design reduces the cost of maintaining working context; it does not remove the need to decide which context deserves durable publication.
This separation also explains why the model-facing tool is called a control environment rather than a full execution engine. The TypeScript side continues to implement the provider calls, session persistence, child lifecycles, and safety policy. Python can ask the host to perform an authoritative operation, but it does not become the owner of that operation merely because the request originated in a Python cell. The kernel is where the model expresses a plan; the host is where Prime Agent applies the system's execution rules.
The one-tool design has an important concurrency consequence. One Python kernel has one shared namespace, and ordinary cells are serialized. If one cell is modifying a working value, another ordinary cell does not run beside it and silently observe a half-updated namespace. This is a straightforward way to preserve the meaning of persistent state, but it is not the same as making the whole agent single-threaded. Prime Agent can run independent child-agent runtimes concurrently because those children have separate sessions and execution contexts. Parallel delegation is a host-mediated property of separate runtimes, not simultaneous mutation of one Python workspace.
For the repository review, the distinction suggests a disciplined rhythm. Use the kernel for operations whose outputs will be combined: find the relevant files, normalize the results, preserve the observations, and then use them to choose the next inspection. Do not mistake a retained variable for completed reasoning. The model still has to decide which evidence matters, what a failing check means, and whether a change is safe to make. The Python surface reduces the friction between those decisions; it does not supply the decisions themselves.
The host keeps the authority
The boundary becomes visible when a Python operation is more than ordinary local computation. Prime Agent's runtime uses a host bridge in which the Python process and TypeScript session exchange newline-delimited JSON messages. A normal file or project-command operation can return its output to the kernel. A typed host request follows a different path: Python sends a request, the TypeScript session dispatches the authoritative operation, and the result comes back to the waiting cell.
The following sequence captures the distinction without treating the diagram as a literal script for every task:
The host's role is not ornamental. Provider credentials and model execution have to remain under a component that understands the session and its configured policies. Transcript writes and session transitions need one authority so that a Python helper cannot accidentally create a second, conflicting persistence system. Child creation, scheduling, and lifecycle decisions need the same host that owns the parent agent. Prime Agent's architecture documentation assigns those responsibilities to the TypeScript host and AgentSession, while the Python runtime supplies the model-facing bridge.
This division also gives the system a meaningful failure surface. A Python cell can finish ordinary computation while a host request is waiting for an authoritative response. The response is not the child's future answer or a general promise that work has completed; it is the result of the particular host operation that was requested. If a project command fails, the model receives a command failure to interpret. If an operation is rejected by host policy, the Python call raises an error rather than silently turning an invalid request into a different action. The boundary preserves the difference between “the model wrote code,” “the workspace returned a result,” and “the host accepted a lifecycle transition.”
It also prevents an attractive but dangerous simplification: because Python can call many things, Python must be a sandbox. It is not. The kernel runs model-generated Python and project commands with the worker's operating-system permissions. The worker and kernel process boundaries help with lifecycle and failure containment, but the repository explicitly says they are not security isolation. A Python cell can be a convenient place to express a controlled review, yet it is still acting in an environment whose permissions must be treated as real.
That matters for installed capabilities. A Python-backed skill adds an importable package to the persistent kernel, while a TypeScript extension can participate in host-level events, tools, and policy. Both can make the model's working surface more useful, but neither should be accepted merely because Prime Agent can load it. The repository treats skills, extensions, packages, and project instructions as trusted inputs. A user who wants to inspect an unfamiliar repository or run generated code in a restricted setting needs an external sandbox or restricted environment; the built-in process split is not a substitute.
Keeping authority in the host has a corresponding cost. The model must understand which actions are ordinary Python work and which actions cross into a host-managed lifecycle. A short Python call can conceal a meaningful transition if the reader only looks at the syntax rather than the contract behind it. Observability and review therefore depend on clear results, durable artifacts, and an honest description of what was accepted, what ran, and what remains pending. The one-tool surface is compact for the model, but it concentrates the need for careful composition in the model's code.
This is why a persistent control environment is more than a convenience feature. It changes the unit of coordination. The model can preserve intermediate data, build a small computation around the current repository, and ask the host to carry out operations that belong to the session authority. At the same time, the design refuses to erase the boundary between working state and durable state, or between process containment and security isolation.
Once that boundary is in place, recursive delegation becomes easier to understand. A parent does not call a mysterious function that returns another model's answer. It uses the Python surface to send a specific host request that admits a separate child runtime. The next question is therefore not simply whether Prime Agent can spawn agents, but what the spawn contract returns, how a child communicates later, and how the parent remains responsible for the result.