Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

fix(coding-agent): dispatcher-owned host-reply envelope (#1836)

Sebastian Mülleraf14f066c3e2
diff --git a/packages/coding-agent/.changes/host-reply-envelope.md b/packages/coding-agent/.changes/host-reply-envelope.md
new file mode 100644
index 0000000000..73faedf91f
--- /dev/null
+++ b/packages/coding-agent/.changes/host-reply-envelope.md
@@ -0,0 +1 @@
+- Namespaced kernel host handler results so handler fields cannot overwrite host reply protocol metadata.
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index d60318ea77..1df004b2a4 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -2978,7 +2978,6 @@ export class AgentSession {
if (instructions !== undefined && typeof instructions !== "string") {
throw new Error("compact.run instructions must be a string when provided");
}
- // "status" is reserved by the host-request reply protocol; don't use it as a key.
if (!this.isStreaming) {
return {
scheduled: false,
diff --git a/packages/coding-agent/src/core/kernel/bootstrap.ts b/packages/coding-agent/src/core/kernel/bootstrap.ts
index 268411b59d..2390749308 100644
--- a/packages/coding-agent/src/core/kernel/bootstrap.ts
+++ b/packages/coding-agent/src/core/kernel/bootstrap.ts
@@ -50,7 +50,7 @@ const REQUIRED_HARNESS_METHODS = [
"delete_prompt_note",
"record_refinement",
];
-const RUNTIME_READY_CHECK = `import inspect; import rlm; from rlm import McpIntegration; import rlm.mcp as mcp; from rlm.harness import HarnessEntry; _harness_methods = ${JSON.stringify(REQUIRED_HARNESS_METHODS)}; assert callable(mcp.list_tools); assert callable(mcp.call_tool); assert hasattr(rlm, 'run'); assert callable(rlm); assert hasattr(rlm, 'rlm'); assert callable(rlm.rlm); assert callable(rlm.host_request); assert callable(rlm.find_models); assert callable(rlm.rlm.find_models); assert hasattr(rlm, 'harness'); assert hasattr(rlm, 'get_harness_state'); assert hasattr(rlm.rlm, 'harness'); assert hasattr(rlm.rlm, 'get_harness_state'); assert all(callable(getattr(_harness, _method, None)) for _harness in (rlm.harness, rlm.rlm.harness) for _method in _harness_methods); assert 'reference' in HarnessEntry.__dataclass_fields__; assert 'scope' in HarnessEntry.__dataclass_fields__; assert 'reference' in inspect.signature(rlm.harness.create_skill).parameters; assert 'reference' in inspect.signature(rlm.harness.update_skill).parameters; assert 'global_' in inspect.signature(rlm.harness.create_memory).parameters; assert 'global_' in inspect.signature(rlm.get_harness_state).parameters; assert not hasattr(rlm, 'background'); assert not hasattr(rlm.rlm, 'background'); from rlm.bash import BashHandle, BashResult; assert callable(rlm.bash); assert all(callable(getattr(BashHandle, _m, None)) for _m in ('tail', 'output', 'poll', 'kill')); assert {'exit_code', 'output', 'duration'} <= set(BashResult.__dataclass_fields__); import rlm.repl as _repl; assert callable(_repl.main); assert callable(_repl.emit); assert callable(_repl.host_request); assert callable(_repl.is_active); assert _repl.PROTOCOL_VERSION == 2; assert callable(rlm.emit); assert not hasattr(rlm, 'HOST_COMM_TARGET'); assert not hasattr(mcp, 'install_shutdown_hook')`;
+const RUNTIME_READY_CHECK = `import inspect; import rlm; from rlm import McpIntegration; import rlm.mcp as mcp; from rlm.harness import HarnessEntry; _harness_methods = ${JSON.stringify(REQUIRED_HARNESS_METHODS)}; assert callable(mcp.list_tools); assert callable(mcp.call_tool); assert hasattr(rlm, 'run'); assert callable(rlm); assert hasattr(rlm, 'rlm'); assert callable(rlm.rlm); assert callable(rlm.host_request); assert callable(rlm.find_models); assert callable(rlm.rlm.find_models); assert hasattr(rlm, 'harness'); assert hasattr(rlm, 'get_harness_state'); assert hasattr(rlm.rlm, 'harness'); assert hasattr(rlm.rlm, 'get_harness_state'); assert all(callable(getattr(_harness, _method, None)) for _harness in (rlm.harness, rlm.rlm.harness) for _method in _harness_methods); assert 'reference' in HarnessEntry.__dataclass_fields__; assert 'scope' in HarnessEntry.__dataclass_fields__; assert 'reference' in inspect.signature(rlm.harness.create_skill).parameters; assert 'reference' in inspect.signature(rlm.harness.update_skill).parameters; assert 'global_' in inspect.signature(rlm.harness.create_memory).parameters; assert 'global_' in inspect.signature(rlm.get_harness_state).parameters; assert not hasattr(rlm, 'background'); assert not hasattr(rlm.rlm, 'background'); from rlm.bash import BashHandle, BashResult; assert callable(rlm.bash); assert all(callable(getattr(BashHandle, _m, None)) for _m in ('tail', 'output', 'poll', 'kill')); assert {'exit_code', 'output', 'duration'} <= set(BashResult.__dataclass_fields__); import rlm.repl as _repl; assert callable(_repl.main); assert callable(_repl.emit); assert callable(_repl.host_request); assert callable(_repl.is_active); assert _repl.PROTOCOL_VERSION == 3; assert callable(rlm.emit); assert not hasattr(rlm, 'HOST_COMM_TARGET'); assert not hasattr(mcp, 'install_shutdown_hook')`;
const BOOTSTRAP_VERSION_FILE = ".bootstrap-version";
const BOOTSTRAP_LOCK_NAME = ".bootstrap.lock";
const BOOTSTRAP_LOCK_RETRY_MS = 100;
diff --git a/packages/coding-agent/src/core/kernel/repl-manager.ts b/packages/coding-agent/src/core/kernel/repl-manager.ts
index 28c39c3f0d..afd46757ec 100644
--- a/packages/coding-agent/src/core/kernel/repl-manager.ts
+++ b/packages/coding-agent/src/core/kernel/repl-manager.ts
@@ -47,7 +47,7 @@ import {
type SnapshotResult,
} from "./state-snapshot.js";
-const REPL_PROTOCOL_VERSION = 2;
+const REPL_PROTOCOL_VERSION = 3;
const READY_TIMEOUT_MS = 30_000;
// Runtime-minted host-request ids never repeat; the bound only guards a
// misbehaving runtime from growing the dedup set forever.
@@ -783,7 +783,7 @@ export class ReplKernelManager {
try {
const result = await this.handleHostRequest(data);
try {
- await this.writeLine({ type: "host_reply", id: requestId, data: { status: "ok", ...result } });
+ await this.writeLine({ type: "host_reply", id: requestId, data: { status: "ok", result } });
} catch (replyError) {
this.appendKernelDiagnostic(
`failed to send host request ok reply for ${requestId}: ${errorMessage(replyError)}`,
diff --git a/packages/coding-agent/src/core/kernel/shared.ts b/packages/coding-agent/src/core/kernel/shared.ts
index 5d08f027a2..287f8a28c8 100644
--- a/packages/coding-agent/src/core/kernel/shared.ts
+++ b/packages/coding-agent/src/core/kernel/shared.ts
@@ -26,7 +26,7 @@ export class KernelBusyAfterInterruptError extends Error {
/**
* Handles one typed request from Python code running in the kernel.
- * The returned record is sent back verbatim as the reply payload.
+ * The returned record is delivered verbatim to the Python caller.
*/
export type HostRequestHandler = (payload: Record<string, unknown>) => Promise<Record<string, unknown>>;
diff --git a/packages/coding-agent/test/kernel-goal-skill.test.ts b/packages/coding-agent/test/kernel-goal-skill.test.ts
index 8aef83c0de..71a544b640 100644
--- a/packages/coding-agent/test/kernel-goal-skill.test.ts
+++ b/packages/coding-agent/test/kernel-goal-skill.test.ts
@@ -124,7 +124,7 @@ except RuntimeError as error:
expect(reroute.stdout.trim()).toBe('RuntimeError: host request type "goal.get" is not available in this session');
});
- it("rejects replies with an unexpected status instead of hanging", async () => {
+ it("round-trips handler records with a status field", async () => {
provisioner = new IpythonKernelProvisioner(tempDir, {
pythonSkills: [bundledGoalSkill()],
hostHandlers: {
@@ -134,12 +134,10 @@ except RuntimeError as error:
const manager = await provisioner.ensure();
const result = await manager.execute(`
-try:
- await goal.get()
-except RuntimeError as error:
- print(f"RuntimeError: {error}")
+import json
+print(json.dumps(await goal.get(), sort_keys=True))
`);
expect(result.status).toBe("ok");
- expect(result.stdout.trim()).toBe("RuntimeError: host request goal.get returned unexpected status: 'partial'");
+ expect(JSON.parse(result.stdout.trim())).toEqual({ status: "partial" });
});
});
diff --git a/packages/coding-agent/test/repl-kernel-shutdown.test.ts b/packages/coding-agent/test/repl-kernel-shutdown.test.ts
index afdf78b1bb..4b93b11048 100644
--- a/packages/coding-agent/test/repl-kernel-shutdown.test.ts
+++ b/packages/coding-agent/test/repl-kernel-shutdown.test.ts
@@ -117,7 +117,7 @@ describe("ReplKernelManager graceful shutdown", () => {
{
"test.slow": async () => {
await handlerBlocked;
- return { answer: 42 };
+ return { answer: 42, status: "weird" };
},
},
);
@@ -130,7 +130,13 @@ describe("ReplKernelManager graceful shutdown", () => {
await dispose;
expect(internals.inFlightHostRequests.size).toBe(0);
- expect(sentReplies).toEqual([{ type: "host_reply", id: "hr-1", data: { status: "ok", answer: 42 } }]);
+ expect(sentReplies).toEqual([
+ {
+ type: "host_reply",
+ id: "hr-1",
+ data: { status: "ok", result: { answer: 42, status: "weird" } },
+ },
+ ]);
expect(internals.child).toBeUndefined();
});
diff --git a/packages/coding-agent/test/repl-kernel-startup.test.ts b/packages/coding-agent/test/repl-kernel-startup.test.ts
index 0ecd04ea72..d41789ac17 100644
--- a/packages/coding-agent/test/repl-kernel-startup.test.ts
+++ b/packages/coding-agent/test/repl-kernel-startup.test.ts
@@ -49,7 +49,7 @@ describe("ReplKernelManager startup", () => {
const manager = new ReplKernelManager({ python, cwd: tempDir });
try {
- await expect(manager.execute("print(1)")).rejects.toThrow(/speaks protocol 1, expected 2/);
+ await expect(manager.execute("print(1)")).rejects.toThrow(/speaks protocol 1, expected 3/);
} finally {
errorSpy.mockRestore();
await manager.dispose();
diff --git a/prime-agent-runtime/src/rlm/__init__.py b/prime-agent-runtime/src/rlm/__init__.py
index 43d054d9be..e9875c4f1a 100644
--- a/prime-agent-runtime/src/rlm/__init__.py
+++ b/prime-agent-runtime/src/rlm/__init__.py
@@ -57,7 +57,7 @@ def _spawn_handle_from_payload(payload: Any) -> RLMSpawnHandle:
def _parse_host_reply(request_type: str, reply: dict[str, Any]) -> dict[str, Any]:
status = reply.get("status")
if status == "ok":
- return {k: v for k, v in reply.items() if k != "status"}
+ return reply["result"]
if status == "error":
raise RuntimeError(str(reply.get("error") or f"host request {request_type} failed"))
raise RuntimeError(f"host request {request_type} returned unexpected status: {status!r}")
diff --git a/prime-agent-runtime/src/rlm/repl.md b/prime-agent-runtime/src/rlm/repl.md
index 506e4ea9db..c0cb012775 100644
--- a/prime-agent-runtime/src/rlm/repl.md
+++ b/prime-agent-runtime/src/rlm/repl.md
@@ -3,7 +3,7 @@
`python -m rlm.repl` starts a CPython REPL runtime that executes code cells in
one persistent `__main__` namespace on a single asyncio event loop. The wire
format is newline-delimited JSON: one object per line, UTF-8, no other framing.
-The current protocol version is `2`; the runtime announces it in the `ready`
+The current protocol version is `3`; the runtime announces it in the `ready`
event.
## Channels
@@ -29,7 +29,7 @@ event.
|---|---|
| `execute` | `{"type":"execute","id":str,"code":str}` |
| `interrupt` | `{"type":"interrupt","id"?:str}` — no reply |
-| `host_reply` | `{"type":"host_reply","id":str,"data":{...}}` — no reply |
+| `host_reply` | `{"type":"host_reply","id":str,"data":{"status":"ok","result":{...}}}` or an error envelope — no reply |
| `snapshot` | `{"type":"snapshot","id":str,"path":str,"manifest_path":str,"max_bytes"?:int,"max_variable_bytes"?:int,"prune_oversized"?:bool}` |
| `restore` | `{"type":"restore","id":str,"path":str}` |
| `list_names` | `{"type":"list_names","id":str}` |
@@ -42,7 +42,7 @@ runtime keeps serving. Closing stdin is equivalent to `shutdown`.
## Events
-- `{"event":"ready","protocol":2,"python":"3.13.11"}` — sent once at startup;
+- `{"event":"ready","protocol":3,"python":"3.13.11"}` — sent once at startup;
the handshake. No banner precedes it.
- `{"event":"stdout"|"stderr","id":str|null,"text":str}` — captured output.
`id` is the cell whose Python execution context performed the write; asyncio
diff --git a/prime-agent-runtime/src/rlm/repl.py b/prime-agent-runtime/src/rlm/repl.py
index d2648279ef..00323baf77 100644
--- a/prime-agent-runtime/src/rlm/repl.py
+++ b/prime-agent-runtime/src/rlm/repl.py
@@ -31,7 +31,7 @@ from typing import Any
from .bash import _kill_live_handles
-PROTOCOL_VERSION = 2
+PROTOCOL_VERSION = 3
DEFAULT_SNAPSHOT_MAX_BYTES = 256 * 1024 * 1024
DEFAULT_SNAPSHOT_MAX_VARIABLE_BYTES = 16 * 1024 * 1024
diff --git a/prime-agent-runtime/test/test_repl.py b/prime-agent-runtime/test/test_repl.py
index ca73371a74..26b7aca89d 100644
--- a/prime-agent-runtime/test/test_repl.py
+++ b/prime-agent-runtime/test/test_repl.py
@@ -117,7 +117,7 @@ class ReplTest(unittest.TestCase):
def test_ready_handshake_and_startup_time(self):
self.assertEqual(self.ready_event["event"], "ready")
- self.assertEqual(self.ready_event["protocol"], 2)
+ self.assertEqual(self.ready_event["protocol"], 3)
major, minor = sys.version_info[:2]
self.assertTrue(self.ready_event["python"].startswith(f"{major}.{minor}."))
# Loose bound for loaded CI machines; still catches an order-of-magnitude regression.
@@ -779,11 +779,75 @@ class ReplTest(unittest.TestCase):
while request.get("event") != "host_request":
request = self.repl.read_event()
self.assertEqual(request["data"], {"type": "demo", "value": 7})
- self.repl.send({"type": "host_reply", "id": request["id"], "data": {"status": "ok", "answer": 42}})
+ envelope = {"status": "ok", "result": {"status": "weird", "answer": 42}}
+ self.repl.send({"type": "host_reply", "id": request["id"], "data": envelope})
events = self.repl.until_done("hr")
- self.assertEqual(one(events, "result")["text"], "{'status': 'ok', 'answer': 42}")
+ self.assertEqual(one(events, "result")["text"], repr(envelope))
self.assertEqual(one(events, "done")["status"], "ok")
+ def test_typed_host_request_unwraps_exact_handler_result(self):
+ code = "\n".join(
+ [
+ "from rlm import host_request",
+ "reply = await host_request('demo')",
+ "reply",
+ ]
+ )
+ self.repl.send({"type": "execute", "id": "typed-hr", "code": code})
+ request = self.repl.read_event()
+ while request.get("event") != "host_request":
+ request = self.repl.read_event()
+ handler_result = {"status": "weird", "answer": 42}
+ self.repl.send(
+ {
+ "type": "host_reply",
+ "id": request["id"],
+ "data": {"status": "ok", "result": handler_result},
+ }
+ )
+ events = self.repl.until_done("typed-hr")
+ self.assertEqual(one(events, "result")["text"], repr(handler_result))
+ self.assertEqual(one(events, "done")["status"], "ok")
+
+ def test_typed_host_request_raises_host_error(self):
+ code = "from rlm import host_request\nawait host_request('demo')"
+ self.repl.send({"type": "execute", "id": "typed-error", "code": code})
+ request = self.repl.read_event()
+ while request.get("event") != "host_request":
+ request = self.repl.read_event()
+ self.repl.send(
+ {
+ "type": "host_reply",
+ "id": request["id"],
+ "data": {"status": "error", "error": "handler exploded"},
+ }
+ )
+ events = self.repl.until_done("typed-error")
+ self.assertEqual(one(events, "error")["ename"], "RuntimeError")
+ self.assertEqual(one(events, "error")["evalue"], "handler exploded")
+ self.assertEqual(one(events, "done")["status"], "error")
+
+ def test_typed_host_request_rejects_unexpected_envelope_status(self):
+ code = "from rlm import host_request\nawait host_request('demo')"
+ self.repl.send({"type": "execute", "id": "typed-unexpected", "code": code})
+ request = self.repl.read_event()
+ while request.get("event") != "host_request":
+ request = self.repl.read_event()
+ self.repl.send(
+ {
+ "type": "host_reply",
+ "id": request["id"],
+ "data": {"status": "partial", "result": {}},
+ }
+ )
+ events = self.repl.until_done("typed-unexpected")
+ self.assertEqual(one(events, "error")["ename"], "RuntimeError")
+ self.assertEqual(
+ one(events, "error")["evalue"],
+ "host request demo returned unexpected status: 'partial'",
+ )
+ self.assertEqual(one(events, "done")["status"], "error")
+
def test_host_reply_for_unknown_id_dropped(self):
self.repl.send({"type": "host_reply", "id": "no-such-request", "data": {"status": "ok"}})
events = self.repl.execute("ok", "'alive'")