From 8bfef71c4a5b808da67bfb5a1ef02fa39dd1f391 Mon Sep 17 00:00:00 2001 From: Kevin Thomas Date: Fri, 8 May 2026 18:00:33 -0700 Subject: [PATCH] add rlm recursion bridge (#16) * feat: add rlm recursion bridge * fix: tighten rlm recursion bridge * fix: make rlm bootstrap nonfatal --- packages/coding-agent/docs/docs.json | 4 + packages/coding-agent/docs/index.md | 1 + .../docs/kernel-and-rlm-recursion.md | 637 ++++++++++++++++++ .../coding-agent/src/core/agent-session.ts | 201 +++++- .../coding-agent/src/core/kernel/index.ts | 114 +++- packages/coding-agent/src/core/prompts/rlm.ts | 2 +- packages/coding-agent/src/core/rlm-runtime.ts | 18 + .../coding-agent/src/core/system-prompt.ts | 5 +- .../coding-agent/src/core/tools/ipython.ts | 39 +- .../test/agent-session-recursion.test.ts | 240 +++++++ .../coding-agent/test/system-prompt.test.ts | 3 + prime-agent-runtime/pyproject.toml | 15 + prime-agent-runtime/src/rlm/__init__.py | 155 +++++ scripts/setup-kernel-venv.sh | 3 + 14 files changed, 1418 insertions(+), 19 deletions(-) create mode 100644 packages/coding-agent/docs/kernel-and-rlm-recursion.md create mode 100644 packages/coding-agent/src/core/rlm-runtime.ts create mode 100644 packages/coding-agent/test/agent-session-recursion.test.ts create mode 100644 prime-agent-runtime/pyproject.toml create mode 100644 prime-agent-runtime/src/rlm/__init__.py diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json index f96321d9f..9acdb8b1f 100644 --- a/packages/coding-agent/docs/docs.json +++ b/packages/coding-agent/docs/docs.json @@ -131,6 +131,10 @@ { "title": "Development", "path": "development.md" + }, + { + "title": "Kernel and RLM Recursion", + "path": "kernel-and-rlm-recursion.md" } ] } diff --git a/packages/coding-agent/docs/index.md b/packages/coding-agent/docs/index.md index a4294d3aa..91026366c 100644 --- a/packages/coding-agent/docs/index.md +++ b/packages/coding-agent/docs/index.md @@ -68,3 +68,4 @@ For the full first-run flow, see [Quickstart](quickstart.md). ## Development - [Development](development.md) - local setup, project structure, and debugging. +- [Kernel and RLM Recursion](kernel-and-rlm-recursion.md) - ZeroMQ kernel transport and recursive sub-agent execution. diff --git a/packages/coding-agent/docs/kernel-and-rlm-recursion.md b/packages/coding-agent/docs/kernel-and-rlm-recursion.md new file mode 100644 index 000000000..c68a5985b --- /dev/null +++ b/packages/coding-agent/docs/kernel-and-rlm-recursion.md @@ -0,0 +1,637 @@ +# Kernel and RLM Recursion + +This document explains the IPython kernel transport and the recursive `rlm` sub-agent bridge. + +The important design constraint is that the Python `rlm` package in the kernel is only a shim. It preserves the model-facing API from `rlm-harness`, but it does not run a child agent loop in Python. Child agents are run by the TypeScript host through the same `AgentSession` machinery as the parent. + +## High-Level Shape + +```text +AgentSession (TypeScript) + | + | owns an ipython tool + v +KernelManager (TypeScript) + | + | ZeroMQ Jupyter protocol + v +IPython kernel process (Python) + | + | has prime-agent-runtime installed as module "rlm" + v +model-executed Python code +``` + +When the model calls recursion: + +```python +result = await rlm.run("subtask") +print(result.answer) +``` + +the flow becomes: + +```text +Python rlm shim + | + | Jupyter comm target "rlm.run" + v +KernelManager comm handler + | + | calls parent AgentSession.runRlmChild(prompt) + v +child AgentSession + | + | same TS agent loop, providers, tools, skills, session storage + v +final assistant text + | + | Jupyter comm reply + v +Python RLMResult +``` + +## Files + +```text +packages/coding-agent/src/core/kernel/index.ts + ZeroMQ connection setup, Jupyter wire encoding, execute_request handling, + comm_open / comm_msg handling for rlm.run. + +packages/coding-agent/src/core/tools/ipython.ts + Tool wrapper around KernelManager. Starts the kernel and bootstraps the + rlm object into the user namespace. + +packages/coding-agent/src/core/agent-session.ts + Parent session owns recursion settings and implements runRlmChild(). + +packages/coding-agent/src/core/rlm-runtime.ts + TypeScript request/result types for the rlm.run bridge. + +prime-agent-runtime/src/rlm/__init__.py + Python shim installed into .kernel-venv. Exposes rlm, rlm.run(), + RLMResult, and TokenUsage. + +scripts/setup-kernel-venv.sh + Creates .kernel-venv and installs ipykernel plus prime-agent-runtime. +``` + +## ZeroMQ Jupyter Kernel Setup + +### Connection File + +`KernelManager` creates a temporary Jupyter connection file before spawning the kernel. + +The file contains local TCP ports and signing settings: + +```json +{ + "ip": "127.0.0.1", + "transport": "tcp", + "shell_port": 50000, + "iopub_port": 50001, + "stdin_port": 50002, + "control_port": 50003, + "hb_port": 50004, + "signature_scheme": "hmac-sha256", + "key": "...", + "kernel_name": "python3" +} +``` + +The current implementation picks a random high port range, writes the file under a temp directory, and starts: + +```bash +python -m ipykernel_launcher -f /tmp/prime-agent-kernel-.../connection.json +``` + +The kernel process inherits: + +- `cwd`: the agent session working directory. +- `env`: the process environment plus kernel-specific overrides such as `RLM_DEPTH`, `RLM_MAX_DEPTH`, and `RLM_SESSION_DIR`. + +### Channels Used + +Jupyter defines several channels. Prime Agent currently uses three: + +```text +shell channel + request/reply channel for execute_request and kernel_info_request + +iopub channel + publish/subscribe channel for stdout, stderr, execute_result, errors, + status changes, and comm_open messages from the kernel + +control channel + request/reply channel for interrupt_request, shutdown_request, and rlm + comm replies that must be delivered while execute_request is still active +``` + +The code creates: + +```text +shell -> ZeroMQ Dealer +iopub -> ZeroMQ Subscriber +control -> ZeroMQ Dealer +``` + +The Subscriber subscribes to the empty topic, which means it receives all IOPub messages. + +### Jupyter Message Encoding + +Each Jupyter message is sent as multipart ZeroMQ frames: + +```text + +signature +header +parent_header +metadata +content +``` + +`KernelManager.encode()` serializes the JSON parts and signs them with HMAC-SHA256 using the connection file key. `decode()` finds the `` delimiter and parses the four JSON frames after the signature. + +The header includes: + +```json +{ + "msg_id": "...", + "session": "...", + "username": "prime-agent", + "date": "...", + "msg_type": "execute_request", + "version": "5.3" +} +``` + +The `msg_id` is important because IOPub is shared. For ordinary execution output, the host only accepts messages whose `parent_header.msg_id` matches the active `execute_request`. + +### Kernel Startup + +Startup sequence: + +```text +KernelManager.start() + | + v +makeConnection() + | + | writes connection.json + v +spawn python -m ipykernel_launcher -f connection.json + | + v +connect shell, iopub, control sockets + | + v +subscribe to iopub + | + v +sleep briefly for ZeroMQ slow-joiner behavior + | + v +probeReady() + | + | sends kernel_info_request on shell + | waits for kernel_info_reply + v +state = "running" +``` + +The startup probe catches a common failure mode: the Python process starts but the kernel never binds or responds. If the probe times out, the manager shuts down and includes the kernel stderr tail in the error. + +### Executing Code + +The ipython tool calls: + +```typescript +KernelManager.execute(code, opts) +``` + +`execute()` serializes calls with `executionQueue`. This matters because the shell channel is a request/reply channel and the IPython kernel user namespace is shared. Two ordinary IPython cells should not execute concurrently in one kernel. + +Execution sequence: + +```text +execute(code) + | + v +send execute_request on shell + | + v +read iopub messages + | + | stream -> stdout / stderr + | execute_result -> final expression repr + | error -> traceback + | status idle -> cell is complete + v +return ExecuteResult +``` + +The returned shape is: + +```typescript +{ + stdout: string; + stderr: string; + result?: string; + status: "ok" | "error" | "aborted"; + error?: { ename: string; evalue: string; traceback: string[] }; + durationMs: number; +} +``` + +Abort handling sends `interrupt_request` on the control channel. The execute call then marks the result as aborted if the `AbortSignal` fired. + +### Kernel Restart And Cleanup + +`KernelManager.shutdown()` sends `shutdown_request` on the control channel, waits briefly, closes sockets, kills the child process as a fallback, removes the temp connection directory, and clears `startPromise`. + +`KernelManager.restart()` serializes behind any active execute call, shuts down, resets state to idle, clears stderr, and starts again. + +Process-wide cleanup is registered through `registerSessionResourceCleanup()`. Kernel managers carry an owner session id, so `cleanupSessionResources(sessionId)` only disposes kernels for that session. + +## IPython Tool Bootstrapping + +The ipython tool constructs a `KernelManager` lazily on first use. It resolves Python in this order: + +```text +PRIME_AGENT_KERNEL_PYTHON +~/.prime-agent/kernel-venv/bin/python +/.kernel-venv/bin/python +``` + +After the kernel starts, the tool bootstraps `rlm` into the user namespace: + +```python +try: + import rlm as _prime_agent_rlm_module + rlm = _prime_agent_rlm_module.rlm +except Exception: + rlm = _PrimeAgentMissingRlm() +``` + +This puts the callable `rlm` object in the global IPython namespace. The model can use either: + +```python +await rlm("subtask") +await rlm.run("subtask") +``` + +Both delegate to the same shim implementation. + +If `prime-agent-runtime` is missing from the kernel environment, startup remains non-fatal. The fallback `rlm` object raises a clear `RuntimeError` only when code actually calls `rlm.run(...)` or `rlm(...)`. + +## Python RLM Shim + +The Python shim lives in `prime-agent-runtime` and installs as import namespace `rlm`. + +It exports: + +```python +rlm +run(prompt: str, **kwargs) +RLMResult +TokenUsage +``` + +`RLMResult` matches the model-visible shape from `rlm-harness`: + +```python +result.answer # str +result.usage # TokenUsage +result.turns # int +result.session_dir # pathlib.Path | None +``` + +The shim also makes the module callable so `import rlm; await rlm("...")` can work, but the ipython tool normally injects the callable object directly as `rlm`. + +### Depth Check + +Before opening a comm, the shim reads: + +```text +RLM_DEPTH +RLM_MAX_DEPTH +``` + +Default max depth is 1. If `RLM_DEPTH >= RLM_MAX_DEPTH`, it raises: + +```text +RLM recursion depth limit reached (RLM_DEPTH=1, RLM_MAX_DEPTH=1) +``` + +This prevents depth-1 children from spawning grandchildren in v1. + +### Comm Open + +For an allowed call: + +```python +await rlm.run("subtask") +``` + +the shim: + +```text +creates asyncio Future +creates Jupyter Comm target "rlm.run" +registers on_msg callback +opens the comm with: + { + "type": "run", + "prompt": "subtask", + "kwargs": {} + } +awaits the Future +``` + +The callback converts host payloads into `RLMResult` or raises `RuntimeError`. + +The shim accepts `**kwargs` for API compatibility with `rlm-harness` and includes them in the comm payload. V1 does not apply any kwargs on the TypeScript side. Unsupported kwargs are rejected with a clear error instead of being ignored. + +### Why Control-Channel Comm Replies Exist + +IPython handles shell-channel messages serially. While a cell is running: + +```python +await rlm.run("subtask") +``` + +the kernel is still inside the active `execute_request` handler. If the TypeScript host replies with a normal shell-channel `comm_msg`, the kernel may not dispatch that message until the current execute request finishes. But the execute request cannot finish because it is awaiting the comm reply. + +That is a deadlock. + +The shim fixes the kernel side by registering `comm_msg` and `comm_close` handlers on the kernel control channel. The TypeScript host sends recursion replies over the control channel. The control channel can be processed while shell execution is still awaiting. + +Because control handlers may wake the Future from a different thread, the shim resolves with: + +```python +loop.call_soon_threadsafe(...) +``` + +## TypeScript Comm Handling + +`KernelManager.executeInner()` watches IOPub messages. Comm messages are handled before the normal parent `msg_id` filter: + +```text +for each iopub message: + if msg_type is comm_open / comm_msg / comm_close: + handleCommMessage(incoming) + continue + + if parent_header.msg_id != active execute_request: + ignore + + handle stdout / stderr / result / error / idle +``` + +This matters because `comm_open` messages may not use the active execute request as their parent. + +The comm handler tracks: + +```text +commTargets: comm_id -> target_name +handledRlmCommIds: comm ids already started +``` + +For target `rlm.run`, it starts work asynchronously: + +```text +comm_open target "rlm.run" + | + v +startRlmRunFromComm(comm_id, data) + | + v +handleRlmRunRequest(data) + | + v +options.rlmRunHandler({ prompt, kwargs }) + | + v +sendCommMessage(comm_id, { status: "ok", ...result }) +``` + +Errors are returned as: + +```json +{ + "status": "error", + "error": "message" +} +``` + +The send path uses `control` if available, then falls back to `shell`. + +## Child AgentSession Execution + +The root `AgentSession` passes this handler into the root kernel: + +```typescript +rlmRunHandler: ({ prompt, kwargs }) => this.runRlmChild(prompt, kwargs) +``` + +`runRlmChild()` is the TypeScript owner of actual recursion. + +Sequence: + +```text +runRlmChild(prompt) + | + | check current depth < max depth + | require selected model + v +create child session dir + | + | /sub-xxxxxxxx + v +create child SessionManager + | + | append model change + | append thinking level change + v +create child Agent + | + | copies parent streamFn, convertToLlm, provider hooks, + | transport settings, thinking budgets, retry settings + v +create child AgentSession + | + | own KernelManager + | same tools by name + | same resource loader and model registry + | RLM_DEPTH = parent depth + 1 + | RLM_MAX_DEPTH = parent max depth + | RLM_SESSION_DIR = child dir + v +child.prompt(prompt) + | + v +wait for idle + | + v +return final assistant text as answer +``` + +The child returns: + +```typescript +{ + answer: string; + usage: { + prompt_tokens: number; + completion_tokens: number; + }; + turns: number; + session_dir: string | null; +} +``` + +Usage is aggregated from assistant message usage: + +```text +prompt_tokens = input + cacheRead + cacheWrite +completion_tokens = output +``` + +Turns are counted as assistant messages in the child transcript. + +The answer is the child's final assistant text. This matches the RLM-1 training surface: the model stops calling tools and the final assistant text is the answer. + +### Cost Accounting + +`RLMResult.usage` reports the child session's token usage. The parent session's displayed usage and cost do not currently fold child usage into the parent assistant-message totals. Child cost is independent in v1 and should be read from the child result or child session until parent aggregation is added. + +## Session Directory Layout + +For a persisted root session: + +```text +~/.pi/agent/sessions// + 2026-..._.jsonl + 2026-..._/ + sub-dccb69c8/ + 2026-..._.jsonl + sub-.../ +``` + +The root RLM session dir is derived from the root JSONL session file path by removing `.jsonl`. Child directories are named `sub-xxxxxxxx`, matching the `rlm-harness` child directory convention. + +Each child kernel sees: + +```text +RLM_DEPTH=1 +RLM_MAX_DEPTH=1 +RLM_SESSION_DIR=/sub-xxxxxxxx +``` + +With the default max depth, a child attempting another `rlm.run()` fails before opening a comm. + +## Parallel Sub-Agents + +Python parallelism uses normal asyncio: + +```python +results = await asyncio.gather( + rlm("capital of Japan"), + rlm("capital of Brazil"), + rlm("capital of Egypt"), +) +print([r.answer for r in results]) +``` + +The flow is: + +```text +one IPython execute_request + | + v +three Python rlm calls + | + | each opens its own comm_id + v +KernelManager starts three runRlmChild() promises + | + v +three independent child AgentSessions + | + v +three comm replies + | + v +asyncio.gather resolves in the IPython cell +``` + +The root kernel still executes one cell. The concurrency comes from multiple comms and multiple child `AgentSession` instances, each with its own kernel. + +## What This Deliberately Does Not Do + +The runtime does not import or subprocess `rlm-harness`. + +The Python shim does not: + +- create child sessions itself +- call model providers +- run an agent loop +- know about TUI state +- know about skills beyond being importable in the kernel +- do cost tracking + +Those stay in TypeScript so children share the parent harness implementation: + +- `AgentSession` +- `KernelManager` +- provider registry and auth +- session storage +- cost and usage accounting +- skills loader +- slash-command and extension environment + +## Failure Modes + +Common failures and where they surface: + +```text +prime-agent-runtime missing from .kernel-venv + -> kernel startup succeeds + -> rlm.run raises RuntimeError with setup instructions when called + +RLM_DEPTH >= RLM_MAX_DEPTH + -> Python RuntimeError before comm_open + +no selected model + -> TS runRlmChild throws, Python receives RuntimeError + +unsupported rlm.run kwargs + -> TS runRlmChild throws "Unsupported rlm.run kwargs: ..." + +child provider error + -> child agent final error behavior is reflected in its final assistant state + +kernel comm reply sent on shell channel + -> deadlock risk while execute_request is awaiting + -> current implementation replies over control channel +``` + +## Validation Commands + +Single child: + +```bash +./pi-test.sh -p 'use the ipython tool to run `print((await rlm.run('"'"'What is the capital of Japan?'"'"')).answer)`' +``` + +Parallel children: + +```bash +./pi-test.sh -p 'use the ipython tool with asyncio.gather to call rlm.run() three times in parallel for: capital of Japan, capital of Brazil, capital of Egypt. Print only the three answers as a Python list.' +``` + +Depth cap: + +```bash +./pi-test.sh -p 'use the ipython tool to run `result = await rlm.run("use the ipython tool to execute this exact Python code and print the exception message: try:\n await rlm.run('\''nested'\'')\nexcept Exception as e:\n print(type(e).__name__, str(e))")\nprint(result.answer)`' +``` diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts index 53ed47e07..fb1f4d50b 100644 --- a/packages/coding-agent/src/core/agent-session.ts +++ b/packages/coding-agent/src/core/agent-session.ts @@ -13,17 +13,19 @@ * Modes use this class and add their own I/O layer on top. */ -import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; -import { basename, dirname, resolve } from "node:path"; -import type { +import { randomUUID } from "node:crypto"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { basename, dirname, join, resolve } from "node:path"; +import { Agent, - AgentEvent, - AgentMessage, - AgentState, - AgentTool, - ThinkingLevel, + type AgentEvent, + type AgentMessage, + type AgentState, + type AgentTool, + type ThinkingLevel, } from "@earendil-works/pi-agent-core"; -import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@earendil-works/pi-ai"; +import type { AssistantMessage, ImageContent, Message, Model, TextContent, Usage } from "@earendil-works/pi-ai"; import { clampThinkingLevel, cleanupSessionResources, @@ -81,8 +83,14 @@ import type { BashExecutionMessage, CustomMessage } from "./messages.js"; import type { ModelRegistry } from "./model-registry.js"; import { expandPromptTemplate, type PromptTemplate } from "./prompt-templates.js"; import type { ResourceExtensionPaths, ResourceLoader } from "./resource-loader.js"; -import type { BranchSummaryEntry, CompactionEntry, SessionManager } from "./session-manager.js"; -import { CURRENT_SESSION_VERSION, getLatestCompactionEntry, type SessionHeader } from "./session-manager.js"; +import type { RlmRunResult, RlmUsage } from "./rlm-runtime.js"; +import type { BranchSummaryEntry, CompactionEntry } from "./session-manager.js"; +import { + CURRENT_SESSION_VERSION, + getLatestCompactionEntry, + type SessionHeader, + SessionManager, +} from "./session-manager.js"; import type { SettingsManager } from "./settings-manager.js"; import type { SlashCommandInfo } from "./slash-commands.js"; import { createSyntheticSourceInfo, type SourceInfo } from "./source-info.js"; @@ -175,6 +183,12 @@ export interface AgentSessionConfig { extensionRunnerRef?: { current?: ExtensionRunner }; /** Session start event metadata emitted when extensions bind to this runtime. */ sessionStartEvent?: SessionStartEvent; + /** Current RLM recursion depth. Root sessions default to RLM_DEPTH or 0. */ + rlmDepth?: number; + /** Maximum RLM recursion depth. Defaults to RLM_MAX_DEPTH or 1. */ + rlmMaxDepth?: number; + /** Directory exposed to the kernel as RLM_SESSION_DIR. */ + rlmSessionDir?: string; } export interface ExtensionBindings { @@ -238,6 +252,26 @@ interface ToolDefinitionEntry { /** Standard thinking levels */ const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high"]; +function parseDepth(value: string | undefined, fallback: number, name: string): number { + if (value === undefined || value === "") { + return fallback; + } + const parsed = Number.parseInt(value, 10); + if (!Number.isFinite(parsed) || parsed < 0) { + throw new Error(`${name} must be a non-negative integer`); + } + return parsed; +} + +function emptyRlmUsage(): RlmUsage { + return { prompt_tokens: 0, completion_tokens: 0 }; +} + +function addUsage(total: RlmUsage, usage: Usage): void { + total.prompt_tokens += usage.input + usage.cacheRead + usage.cacheWrite; + total.completion_tokens += usage.output; +} + // ============================================================================ // AgentSession Class // ============================================================================ @@ -298,6 +332,9 @@ export class AgentSession { private _extensionErrorListener?: ExtensionErrorListener; private _extensionErrorUnsubscriber?: () => void; private _ipythonKernelManagerRef: { current?: KernelManager } = {}; + private _rlmDepth: number; + private _rlmMaxDepth: number; + private _rlmSessionDir?: string; // Model registry for API key resolution private _modelRegistry: ModelRegistry; @@ -326,6 +363,9 @@ export class AgentSession { this._allowedToolNames = config.allowedToolNames ? new Set(config.allowedToolNames) : undefined; this._baseToolsOverride = config.baseToolsOverride; this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" }; + this._rlmDepth = config.rlmDepth ?? parseDepth(process.env.RLM_DEPTH, 0, "RLM_DEPTH"); + this._rlmMaxDepth = config.rlmMaxDepth ?? parseDepth(process.env.RLM_MAX_DEPTH, 1, "RLM_MAX_DEPTH"); + this._rlmSessionDir = config.rlmSessionDir; // Always subscribe to agent events for internal handling // (session persistence, extensions, auto-compaction, retry logic) @@ -950,6 +990,7 @@ export class AgentSession { selectedTools: validToolNames, toolSnippets, promptGuidelines, + allowRecursion: this._rlmDepth < this._rlmMaxDepth, }; return buildSystemPrompt(this._baseSystemPromptOptions); } @@ -2350,7 +2391,12 @@ export class AgentSession { ]), ) : createAllToolDefinitions(this._cwd, { - ipython: { kernelManagerRef: this._ipythonKernelManagerRef }, + ipython: { + kernelManagerRef: this._ipythonKernelManagerRef, + env: this._rlmKernelEnv(), + sessionId: this.sessionId, + rlmRunHandler: ({ prompt, kwargs }) => this.runRlmChild(prompt, kwargs), + }, bash: { commandPrefix: shellCommandPrefix, shellPath }, }); @@ -2409,6 +2455,137 @@ export class AgentSession { } } + private _rlmKernelEnv(): Record { + return { + RLM_DEPTH: String(this._rlmDepth), + RLM_MAX_DEPTH: String(this._rlmMaxDepth), + RLM_SESSION_DIR: this._ensureRlmSessionDir(), + }; + } + + private _ensureRlmSessionDir(): string { + if (this._rlmSessionDir) { + mkdirSync(this._rlmSessionDir, { recursive: true }); + return this._rlmSessionDir; + } + + const sessionFile = this.sessionManager.getSessionFile(); + if (sessionFile) { + const dir = sessionFile.endsWith(".jsonl") ? sessionFile.slice(0, -".jsonl".length) : `${sessionFile}.rlm`; + mkdirSync(dir, { recursive: true }); + this._rlmSessionDir = dir; + return dir; + } + + this._rlmSessionDir = mkdtempSync(join(tmpdir(), "prime-agent-rlm-")); + return this._rlmSessionDir; + } + + private _createChildRlmSessionDir(): string { + const parentDir = this._ensureRlmSessionDir(); + for (let i = 0; i < 100; i++) { + const childDir = join(parentDir, `sub-${randomUUID().slice(0, 8)}`); + try { + mkdirSync(childDir); + return childDir; + } catch (error) { + if (error instanceof Error && "code" in error && error.code === "EEXIST") { + continue; + } + throw error; + } + } + throw new Error("Unable to create unique RLM child session directory"); + } + + private _usageForCurrentMessages(): RlmUsage { + const usage = emptyRlmUsage(); + for (const message of this.agent.state.messages) { + if (message.role === "assistant") { + addUsage(usage, (message as AssistantMessage).usage); + } + } + return usage; + } + + private _assistantTurnCount(): number { + return this.agent.state.messages.filter((message) => message.role === "assistant").length; + } + + async runRlmChild(prompt: string, kwargs: Record = {}): Promise { + const unsupportedKwargs = Object.keys(kwargs); + if (unsupportedKwargs.length > 0) { + throw new Error(`Unsupported rlm.run kwargs: ${unsupportedKwargs.sort().join(", ")}`); + } + if (this._rlmDepth >= this._rlmMaxDepth) { + throw new Error( + `RLM recursion depth limit reached (RLM_DEPTH=${this._rlmDepth}, RLM_MAX_DEPTH=${this._rlmMaxDepth})`, + ); + } + const model = this.model; + if (!model) { + throw new Error(formatNoModelSelectedMessage()); + } + + const childSessionDir = this._createChildRlmSessionDir(); + const childSessionManager = SessionManager.create(this._cwd, childSessionDir); + childSessionManager.appendModelChange(model.provider, model.id); + childSessionManager.appendThinkingLevelChange(this.thinkingLevel); + + const childAgent = new Agent({ + initialState: { + systemPrompt: "", + model, + thinkingLevel: this.thinkingLevel, + tools: [], + }, + convertToLlm: this.agent.convertToLlm, + transformContext: this.agent.transformContext, + streamFn: this.agent.streamFn, + getApiKey: this.agent.getApiKey, + onPayload: this.agent.onPayload, + onResponse: this.agent.onResponse, + steeringMode: this.settingsManager.getSteeringMode(), + followUpMode: this.settingsManager.getFollowUpMode(), + sessionId: childSessionManager.getSessionId(), + thinkingBudgets: this.settingsManager.getThinkingBudgets(), + transport: this.settingsManager.getTransport(), + maxRetryDelayMs: this.settingsManager.getProviderRetrySettings().maxRetryDelayMs, + toolExecution: this.agent.toolExecution, + }); + + const child = new AgentSession({ + agent: childAgent, + sessionManager: childSessionManager, + settingsManager: this.settingsManager, + cwd: this._cwd, + scopedModels: this._scopedModels, + resourceLoader: this._resourceLoader, + customTools: this._customTools, + modelRegistry: this._modelRegistry, + initialActiveToolNames: this.getActiveToolNames(), + allowedToolNames: this._allowedToolNames ? [...this._allowedToolNames] : undefined, + rlmDepth: this._rlmDepth + 1, + rlmMaxDepth: this._rlmMaxDepth, + rlmSessionDir: childSessionDir, + sessionStartEvent: { type: "session_start", reason: "startup" }, + }); + + try { + await child.prompt(prompt, { expandPromptTemplates: false, source: "extension" }); + await child.agent.waitForIdle(); + const answer = child.getLastAssistantText() ?? ""; + return { + answer, + usage: child._usageForCurrentMessages(), + turns: child._assistantTurnCount(), + session_dir: childSessionDir, + }; + } finally { + child.dispose(); + } + } + // ========================================================================= // Auto-Retry // ========================================================================= diff --git a/packages/coding-agent/src/core/kernel/index.ts b/packages/coding-agent/src/core/kernel/index.ts index e80f42cb7..1baeea9e2 100644 --- a/packages/coding-agent/src/core/kernel/index.ts +++ b/packages/coding-agent/src/core/kernel/index.ts @@ -8,6 +8,7 @@ import { setTimeout as sleep } from "node:timers/promises"; import { registerSessionResourceCleanup } from "@earendil-works/pi-ai"; import { v4 as uuid } from "uuid"; import { Dealer, Subscriber } from "zeromq"; +import type { RlmRunHandler, RlmRunResult } from "../rlm-runtime.js"; const DELIM = Buffer.from(""); const PROTOCOL_VERSION = "5.3"; @@ -19,6 +20,9 @@ export interface KernelManagerOptions { /** Python interpreter that has `ipykernel` available. */ python: string; cwd?: string; + env?: Record; + sessionId?: string; + rlmRunHandler?: RlmRunHandler; /** Default: "prime-agent". */ username?: string; } @@ -68,6 +72,14 @@ interface JupyterMessage { content: Record; } +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + // ---- wire format --------------------------------------------------------- function buildMessage( @@ -158,8 +170,12 @@ function makeConnection(): { info: ConnectionInfo; path: string; tempDir: string const liveKernels = new Set(); let signalHandlersInstalled = false; -registerSessionResourceCleanup(() => { - for (const k of liveKernels) k.dispose(); +registerSessionResourceCleanup((sessionId) => { + for (const k of liveKernels) { + if (!sessionId || k.ownerSessionId === sessionId) { + k.dispose(); + } + } }); function installSignalHandlersOnce(): void { @@ -190,8 +206,11 @@ function installSignalHandlersOnce(): void { // ---- kernel manager ------------------------------------------------------ export class KernelManager { - private readonly options: Required> & { cwd?: string }; + private readonly options: Required> & + Pick; private readonly session = uuid(); + private readonly commTargets = new Map(); + private readonly handledRlmCommIds = new Set(); private kernel?: ChildProcess; private shell?: Dealer; private iopub?: Subscriber; @@ -212,10 +231,17 @@ export class KernelManager { this.options = { python: options.python, cwd: options.cwd, + env: options.env, + sessionId: options.sessionId, + rlmRunHandler: options.rlmRunHandler, username: options.username ?? "prime-agent", }; } + get ownerSessionId(): string | undefined { + return this.options.sessionId; + } + async start(): Promise { if (!this.startPromise) { this.startPromise = this.doStart(); @@ -234,6 +260,7 @@ export class KernelManager { const kernel = spawn(this.options.python, ["-m", "ipykernel_launcher", "-f", connectionPath], { cwd: this.options.cwd, + env: this.options.env ? { ...process.env, ...this.options.env } : process.env, stdio: ["ignore", "pipe", "pipe"], }); this.kernel = kernel; @@ -392,9 +419,13 @@ export class KernelManager { for await (const frames of iopub) { const incoming = decode(frames); if (!incoming) continue; + const t = incoming.header.msg_type; + if (t === "comm_open" || t === "comm_msg" || t === "comm_close") { + this.handleCommMessage(incoming); + continue; + } if ((incoming.parent_header as { msg_id?: string }).msg_id !== requestMsgId) continue; - const t = incoming.header.msg_type; if (t === "stream") { const c = incoming.content as { name: "stdout" | "stderr"; text: string }; if (c.name === "stdout") { @@ -442,6 +473,81 @@ export class KernelManager { return { stdout, stderr, result, error, status, durationMs: Date.now() - started }; } + private handleCommMessage(incoming: JupyterMessage): void { + const msgType = incoming.header.msg_type; + const content = incoming.content; + const commId = content.comm_id; + if (typeof commId !== "string") { + return; + } + + if (msgType === "comm_close") { + this.commTargets.delete(commId); + this.handledRlmCommIds.delete(commId); + return; + } + + if (msgType === "comm_open") { + const targetName = content.target_name; + if (typeof targetName !== "string") { + return; + } + this.commTargets.set(commId, targetName); + if (targetName === "rlm.run") { + this.startRlmRunFromComm(commId, content.data); + } + return; + } + + const targetName = this.commTargets.get(commId); + if (msgType === "comm_msg" && targetName === "rlm.run") { + this.startRlmRunFromComm(commId, content.data); + } + } + + private startRlmRunFromComm(commId: string, data: unknown): void { + if (this.handledRlmCommIds.has(commId)) { + return; + } + this.handledRlmCommIds.add(commId); + + void (async () => { + try { + const result = await this.handleRlmRunRequest(data); + await this.sendCommMessage(commId, { status: "ok", ...result }); + } catch (error) { + await this.sendCommMessage(commId, { status: "error", error: errorMessage(error) }).catch(() => {}); + } + })(); + } + + private async handleRlmRunRequest(data: unknown): Promise { + const handler = this.options.rlmRunHandler; + if (!handler) { + throw new Error("rlm.run is not available in this session"); + } + if (!isRecord(data)) { + throw new Error("rlm.run comm payload must be an object"); + } + if (data.type !== "run") { + throw new Error("rlm.run comm payload must have type 'run'"); + } + if (typeof data.prompt !== "string") { + throw new Error("rlm.run prompt must be a string"); + } + const kwargs = isRecord(data.kwargs) ? data.kwargs : {}; + return handler({ prompt: data.prompt, kwargs }); + } + + private async sendCommMessage(commId: string, data: Record): Promise { + const channel = this.control ?? this.shell; + if (!channel || !this.connection) { + throw new Error("Kernel channel is not connected"); + } + const msg = buildMessage("comm_msg", { comm_id: commId, data }, this.session, this.options.username); + await channel.send(encode(msg, this.connection.key)); + } + private async interrupt(): Promise { if (!this.control || !this.connection) return; const msg = buildMessage("interrupt_request", {}, this.session, this.options.username); diff --git a/packages/coding-agent/src/core/prompts/rlm.ts b/packages/coding-agent/src/core/prompts/rlm.ts index 861523fae..08b9e9b5a 100644 --- a/packages/coding-agent/src/core/prompts/rlm.ts +++ b/packages/coding-agent/src/core/prompts/rlm.ts @@ -10,7 +10,7 @@ export interface RlmPromptOptions { export function buildRlmPrompt(options: RlmPromptOptions): string { const { cwd, skillsDir, messagesPath } = options; const installedSkills = options.installedSkills ?? []; - const allowRecursion = options.allowRecursion ?? false; + const allowRecursion = options.allowRecursion ?? true; const activeTools = options.activeTools ?? []; const parts = [ "You are a coding agent. You solve tasks by writing and executing code, observing results, and iterating one step at a time.", diff --git a/packages/coding-agent/src/core/rlm-runtime.ts b/packages/coding-agent/src/core/rlm-runtime.ts new file mode 100644 index 000000000..10a00d9d8 --- /dev/null +++ b/packages/coding-agent/src/core/rlm-runtime.ts @@ -0,0 +1,18 @@ +export interface RlmUsage { + prompt_tokens: number; + completion_tokens: number; +} + +export interface RlmRunRequest { + prompt: string; + kwargs: Record; +} + +export interface RlmRunResult { + answer: string; + usage: RlmUsage; + turns: number; + session_dir: string | null; +} + +export type RlmRunHandler = (request: RlmRunRequest) => Promise; diff --git a/packages/coding-agent/src/core/system-prompt.ts b/packages/coding-agent/src/core/system-prompt.ts index bf8dfa755..fc8b9c1c2 100644 --- a/packages/coding-agent/src/core/system-prompt.ts +++ b/packages/coding-agent/src/core/system-prompt.ts @@ -24,6 +24,8 @@ export interface BuildSystemPromptOptions { contextFiles?: Array<{ path: string; content: string }>; /** Pre-loaded skills. */ skills?: Skill[]; + /** Whether to include the model-facing rlm recursion guidance. */ + allowRecursion?: boolean; } /** Build the system prompt with tools, guidelines, and context */ @@ -37,6 +39,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions): string { messagesPath, contextFiles: providedContextFiles, skills: providedSkills, + allowRecursion, } = options; const promptCwd = cwd.replace(/\\/g, "/"); const promptMessagesPath = (messagesPath ?? "not persisted").replace(/\\/g, "/"); @@ -88,7 +91,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions): string { messagesPath: promptMessagesPath, installedSkills: skills.filter((skill) => !skill.disableModelInvocation).map((skill) => skill.name), activeTools: tools.filter((name) => name === "ipython" || name === "bash" || name === "edit"), - allowRecursion: false, + allowRecursion, }); const guidelines = formatPromptGuidelines(promptGuidelines); diff --git a/packages/coding-agent/src/core/tools/ipython.ts b/packages/coding-agent/src/core/tools/ipython.ts index 24bc410f1..a22c6c1b9 100644 --- a/packages/coding-agent/src/core/tools/ipython.ts +++ b/packages/coding-agent/src/core/tools/ipython.ts @@ -3,8 +3,31 @@ import type { AgentTool } from "@earendil-works/pi-agent-core"; import { type Static, Type } from "typebox"; import type { ToolDefinition } from "../extensions/types.js"; import { KernelManager, resolveKernelPython } from "../kernel/index.js"; +import type { RlmRunHandler } from "../rlm-runtime.js"; import { wrapToolDefinition } from "./tool-definition-wrapper.js"; +const RLM_BOOTSTRAP_CODE = ` +try: + import rlm as _prime_agent_rlm_module + rlm = _prime_agent_rlm_module.rlm +except Exception as _prime_agent_rlm_error: + _PRIME_AGENT_RLM_IMPORT_ERROR = str(_prime_agent_rlm_error) + + class _PrimeAgentMissingRlm: + async def run(self, prompt, **kwargs): + raise RuntimeError( + "prime-agent-runtime is not installed in this IPython kernel. " + "Run ./scripts/setup-kernel-venv.sh from the repo root, or set " + "PRIME_AGENT_KERNEL_PYTHON to a kernel environment with prime-agent-runtime installed. " + f"Import error: {_PRIME_AGENT_RLM_IMPORT_ERROR}" + ) + + async def __call__(self, prompt, **kwargs): + return await self.run(prompt, **kwargs) + + rlm = _PrimeAgentMissingRlm() +`.trim(); + const ipythonSchema = Type.Object({ code: Type.String({ description: @@ -24,6 +47,9 @@ export interface IpythonToolDetails { export interface IpythonToolOptions { /** Defaults to {@link resolveKernelPython}. Must have `ipykernel` installed. */ python?: string; + env?: Record; + sessionId?: string; + rlmRunHandler?: RlmRunHandler; /** Filled after the first kernel start so the owning session can restart it after compaction. */ kernelManagerRef?: { current?: KernelManager }; } @@ -49,8 +75,19 @@ export function createIpythonToolDefinition( "No Python interpreter with `ipykernel` was found. Run `./scripts/setup-kernel-venv.sh` from the repo root, or set PRIME_AGENT_KERNEL_PYTHON to point at a python that has ipykernel installed.", ); } - const m = new KernelManager({ python, cwd }); + const m = new KernelManager({ + python, + cwd, + env: options?.env, + sessionId: options?.sessionId, + rlmRunHandler: options?.rlmRunHandler, + }); await m.start(); + const bootstrap = await m.execute(RLM_BOOTSTRAP_CODE); + if (bootstrap.status !== "ok") { + const details = [bootstrap.stderr, bootstrap.error?.traceback.join("\n")].filter(Boolean).join("\n"); + throw new Error(`Failed to initialize rlm runtime in the IPython kernel:\n${details}`); + } if (options?.kernelManagerRef) { options.kernelManagerRef.current = m; } diff --git a/packages/coding-agent/test/agent-session-recursion.test.ts b/packages/coding-agent/test/agent-session-recursion.test.ts new file mode 100644 index 000000000..e90d46186 --- /dev/null +++ b/packages/coding-agent/test/agent-session-recursion.test.ts @@ -0,0 +1,240 @@ +import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { basename, join } from "node:path"; +import { setTimeout as sleep } from "node:timers/promises"; +import { Agent } from "@earendil-works/pi-agent-core"; +import { + type AssistantMessage, + type Context, + createAssistantMessageEventStream, + getModel, + type TextContent, +} from "@earendil-works/pi-ai"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; +import { AgentSession } from "../src/core/agent-session.js"; +import { AuthStorage } from "../src/core/auth-storage.js"; +import { KernelManager } from "../src/core/kernel/index.js"; +import { ModelRegistry } from "../src/core/model-registry.js"; +import { SessionManager } from "../src/core/session-manager.js"; +import { SettingsManager } from "../src/core/settings-manager.js"; +import { createTestResourceLoader } from "./utilities.js"; + +const model = getModel("anthropic", "claude-sonnet-4-5")!; + +function userText(context: Context): string { + const lastMessage = context.messages[context.messages.length - 1]; + if (!lastMessage || lastMessage.role !== "user") { + return ""; + } + if (typeof lastMessage.content === "string") { + return lastMessage.content; + } + return lastMessage.content + .filter((block): block is TextContent => block.type === "text") + .map((block) => block.text) + .join("\n"); +} + +function assistantMessage(text: string): AssistantMessage { + return { + role: "assistant", + content: [{ type: "text", text }], + api: model.api, + provider: model.provider, + model: model.id, + usage: { + input: 7, + output: 3, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 10, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }, + stopReason: "stop", + timestamp: Date.now(), + }; +} + +function streamAnswer(text: string): ReturnType { + const stream = createAssistantMessageEventStream(); + queueMicrotask(() => { + const message = assistantMessage(text); + stream.push({ type: "done", reason: "stop", message }); + }); + return stream; +} + +interface TestCommMessage { + header: { msg_type: string }; + parent_header: Record; + metadata: Record; + content: Record; +} + +interface KernelCommTestApi { + handleCommMessage(incoming: TestCommMessage): void; + sendCommMessage(commId: string, data: Record): Promise; +} + +interface CapturedCommReply { + commId: string; + data: Record; +} + +function rlmCommOpen(commId: string, prompt: string, kwargs: Record = {}): TestCommMessage { + return { + header: { msg_type: "comm_open" }, + parent_header: {}, + metadata: {}, + content: { + comm_id: commId, + target_name: "rlm.run", + data: { type: "run", prompt, kwargs }, + }, + }; +} + +async function waitFor(condition: () => boolean): Promise { + const deadline = Date.now() + 1000; + while (!condition()) { + if (Date.now() > deadline) { + throw new Error("Timed out waiting for condition"); + } + await sleep(10); + } +} + +describe("AgentSession rlm recursion", () => { + let tempDir: string; + let session: AgentSession | undefined; + + beforeEach(() => { + tempDir = join(tmpdir(), `pi-rlm-recursion-${Date.now()}-${Math.random().toString(36).slice(2)}`); + mkdirSync(tempDir, { recursive: true }); + }); + + afterEach(() => { + session?.dispose(); + session = undefined; + rmSync(tempDir, { recursive: true, force: true }); + }); + + function createSession(options: { depth?: number; maxDepth?: number } = {}): AgentSession { + const authStorage = AuthStorage.create(join(tempDir, "auth.json")); + authStorage.setRuntimeApiKey("anthropic", "test-key"); + const sessionManager = SessionManager.create(tempDir, join(tempDir, "sessions")); + const settingsManager = SettingsManager.create(tempDir, tempDir); + + const agent = new Agent({ + getApiKey: () => "test-key", + initialState: { + model, + systemPrompt: "", + tools: [], + thinkingLevel: "off", + }, + streamFn: (_model, context) => streamAnswer(`child answer: ${userText(context)}`), + }); + + session = new AgentSession({ + agent, + sessionManager, + settingsManager, + cwd: tempDir, + modelRegistry: ModelRegistry.create(authStorage, join(tempDir, "models.json")), + resourceLoader: createTestResourceLoader(), + rlmDepth: options.depth, + rlmMaxDepth: options.maxDepth, + }); + return session; + } + + it("runs a child session under a sub directory and returns an RLM-shaped result", async () => { + const root = createSession(); + + const result = await root.runRlmChild("summarize shard 1"); + + expect(result.answer).toBe("child answer: summarize shard 1"); + expect(result.usage).toEqual({ prompt_tokens: 7, completion_tokens: 3 }); + expect(result.turns).toBe(1); + expect(result.session_dir).not.toBeNull(); + expect(basename(result.session_dir!)).toMatch(/^sub-/); + expect(existsSync(result.session_dir!)).toBe(true); + expect(readdirSync(result.session_dir!).some((name) => name.endsWith(".jsonl"))).toBe(true); + }); + + it("rejects child creation at the configured recursion depth cap", async () => { + const root = createSession({ depth: 1, maxDepth: 1 }); + + await expect(root.runRlmChild("nested")).rejects.toThrow("RLM recursion depth limit reached"); + }); + + it("rejects unsupported rlm.run kwargs loudly", async () => { + const root = createSession(); + + await expect(root.runRlmChild("nested", { model: "other-model" })).rejects.toThrow( + "Unsupported rlm.run kwargs: model", + ); + }); + + it("runs parallel rlm comm requests independently", async () => { + let active = 0; + let maxActive = 0; + let started = 0; + let releaseChildren: () => void = () => {}; + const release = new Promise((resolve) => { + releaseChildren = resolve; + }); + const replies: CapturedCommReply[] = []; + const manager = new KernelManager({ + python: process.execPath, + rlmRunHandler: async ({ prompt }) => { + active++; + started++; + maxActive = Math.max(maxActive, active); + await release; + active--; + return { + answer: `answer:${prompt}`, + usage: { prompt_tokens: 1, completion_tokens: 1 }, + turns: 1, + session_dir: null, + }; + }, + }); + + try { + const kernel = manager as unknown as KernelCommTestApi; + kernel.sendCommMessage = async (commId, data) => { + replies.push({ commId, data }); + }; + + kernel.handleCommMessage(rlmCommOpen("comm-a", "first")); + kernel.handleCommMessage(rlmCommOpen("comm-b", "second")); + + await waitFor(() => started === 2); + expect(maxActive).toBe(2); + + releaseChildren(); + await waitFor(() => replies.length === 2); + + const byCommId = new Map(replies.map((reply) => [reply.commId, reply.data])); + expect(byCommId.get("comm-a")).toEqual({ + status: "ok", + answer: "answer:first", + usage: { prompt_tokens: 1, completion_tokens: 1 }, + turns: 1, + session_dir: null, + }); + expect(byCommId.get("comm-b")).toEqual({ + status: "ok", + answer: "answer:second", + usage: { prompt_tokens: 1, completion_tokens: 1 }, + turns: 1, + session_dir: null, + }); + } finally { + manager.dispose(); + } + }); +}); diff --git a/packages/coding-agent/test/system-prompt.test.ts b/packages/coding-agent/test/system-prompt.test.ts index 9682f2c4b..d20bca413 100644 --- a/packages/coding-agent/test/system-prompt.test.ts +++ b/packages/coding-agent/test/system-prompt.test.ts @@ -26,6 +26,7 @@ describe("buildRlmPrompt", () => { messagesPath: "/repo/.pi/sessions/session.jsonl", installedSkills: ["websearch"], activeTools: ["ipython"], + allowRecursion: false, }); expect(prompt).toBe( @@ -60,6 +61,8 @@ describe("buildSystemPrompt", () => { expect(prompt).toContain("You are a coding agent."); expect(prompt).toContain("Working directory: /repo"); expect(prompt).toContain("Conversation log: /repo/.pi/sessions/session.jsonl"); + expect(prompt).toContain("await rlm('sub-task')"); + expect(prompt).toContain("asyncio.gather"); expect(prompt).toContain("Call at most one built-in tool per turn."); expect(prompt).not.toContain("# IPython Kernel Guidance"); expect(prompt).not.toContain("Available tools:"); diff --git a/prime-agent-runtime/pyproject.toml b/prime-agent-runtime/pyproject.toml new file mode 100644 index 000000000..519f960b5 --- /dev/null +++ b/prime-agent-runtime/pyproject.toml @@ -0,0 +1,15 @@ +[project] +name = "prime-agent-runtime" +version = "0.1.0" +description = "Kernel-side runtime shim for Prime Agent recursion" +requires-python = ">=3.10" +dependencies = [ + "ipykernel", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["src/rlm"] diff --git a/prime-agent-runtime/src/rlm/__init__.py b/prime-agent-runtime/src/rlm/__init__.py new file mode 100644 index 000000000..984cb0621 --- /dev/null +++ b/prime-agent-runtime/src/rlm/__init__.py @@ -0,0 +1,155 @@ +"""Tiny rlm-compatible kernel shim for Prime Agent.""" + +from __future__ import annotations + +import asyncio +import os +import sys +import types +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any + +try: + from ipykernel.comm import Comm +except Exception: # pragma: no cover - depends on ipykernel version + Comm = None # type: ignore[assignment] + +try: + from IPython import get_ipython +except Exception: # pragma: no cover - only available in kernels + get_ipython = None # type: ignore[assignment] + + +@dataclass +class TokenUsage: + prompt_tokens: int = 0 + completion_tokens: int = 0 + + @property + def total(self) -> int: + return self.prompt_tokens + self.completion_tokens + + +@dataclass +class RLMResult: + answer: str + session_dir: Path | None = None + usage: TokenUsage = field(default_factory=TokenUsage) + turns: int = 0 + + +def _env_int(name: str, default: int) -> int: + raw = os.environ.get(name) + if raw is None or raw == "": + return default + try: + return int(raw) + except ValueError as exc: + raise RuntimeError(f"{name} must be an integer, got {raw!r}") from exc + + +def _ensure_recursion_allowed() -> None: + depth = _env_int("RLM_DEPTH", 0) + max_depth = _env_int("RLM_MAX_DEPTH", 1) + if depth >= max_depth: + raise RuntimeError( + f"RLM recursion depth limit reached " + f"(RLM_DEPTH={depth}, RLM_MAX_DEPTH={max_depth})" + ) + + +def _install_control_comm_handlers() -> None: + """Let comm replies arrive on the control channel during an execute_request.""" + if get_ipython is None: + return + shell = get_ipython() + kernel = getattr(shell, "kernel", None) + comm_manager = getattr(kernel, "comm_manager", None) + control_handlers = getattr(kernel, "control_handlers", None) + if comm_manager is None or not isinstance(control_handlers, dict): + return + control_handlers.setdefault("comm_msg", comm_manager.comm_msg) + control_handlers.setdefault("comm_close", comm_manager.comm_close) + + +def _result_from_payload(payload: dict[str, Any]) -> RLMResult: + usage_payload = payload.get("usage") + usage = TokenUsage() + if isinstance(usage_payload, dict): + usage = TokenUsage( + prompt_tokens=int(usage_payload.get("prompt_tokens", 0)), + completion_tokens=int(usage_payload.get("completion_tokens", 0)), + ) + + session_dir_payload = payload.get("session_dir") + session_dir = Path(session_dir_payload) if isinstance(session_dir_payload, str) else None + return RLMResult( + answer=str(payload.get("answer", "")), + usage=usage, + turns=int(payload.get("turns", 0)), + session_dir=session_dir, + ) + + +async def run(prompt: str, **kwargs: Any) -> RLMResult: + """Run a recursive Prime Agent child through the TypeScript host.""" + if not isinstance(prompt, str): + raise TypeError(f"prompt must be str, got {type(prompt).__name__}") + _ensure_recursion_allowed() + if Comm is None: + raise RuntimeError("Jupyter comm support is unavailable in this kernel") + _install_control_comm_handlers() + + loop = asyncio.get_running_loop() + future: asyncio.Future[RLMResult] = loop.create_future() + comm = Comm(target_name="rlm.run", primary=False) + + def _on_msg(msg: dict[str, Any]) -> None: + content = msg.get("content", {}) + data = content.get("data", {}) if isinstance(content, dict) else {} + if not isinstance(data, dict): + return + + status = data.get("status") + if status == "ok": + def _resolve_result() -> None: + if not future.done(): + future.set_result(_result_from_payload(data)) + comm.close() + + loop.call_soon_threadsafe(_resolve_result) + return + if status == "error": + message = data.get("error") or "rlm.run failed" + def _resolve_error() -> None: + if not future.done(): + future.set_exception(RuntimeError(str(message))) + comm.close() + + loop.call_soon_threadsafe(_resolve_error) + + comm.on_msg(_on_msg) + comm.open(data={"type": "run", "prompt": prompt, "kwargs": kwargs}) + return await future + + +class _RLMCallable: + async def run(self, prompt: str, **kwargs: Any) -> RLMResult: + return await run(prompt, **kwargs) + + async def __call__(self, prompt: str, **kwargs: Any) -> RLMResult: + return await run(prompt, **kwargs) + + +rlm = _RLMCallable() + + +class _CallableModule(types.ModuleType): + async def __call__(self, prompt: str, **kwargs: Any) -> RLMResult: + return await run(prompt, **kwargs) + + +sys.modules[__name__].__class__ = _CallableModule + +__all__ = ["RLMResult", "TokenUsage", "rlm", "run"] diff --git a/scripts/setup-kernel-venv.sh b/scripts/setup-kernel-venv.sh index 3d8ab2564..523e8c5d6 100755 --- a/scripts/setup-kernel-venv.sh +++ b/scripts/setup-kernel-venv.sh @@ -20,6 +20,9 @@ uv venv --python 3.12 .kernel-venv echo ">>> installing ipykernel" uv pip install --python .kernel-venv/bin/python ipykernel +echo ">>> installing prime-agent-runtime" +uv pip install --python .kernel-venv/bin/python -e ./prime-agent-runtime + echo echo "Done. The ipython tool will use this venv automatically." echo "Override with PRIME_AGENT_KERNEL_PYTHON=/path/to/python." -- knotmirror 0.0.1