HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
"""UHP Plugins §6 in the runner: a package lands whole at its root with a data directory, and a
stdio server a plugin declares runs through a launcher that sets PLUGIN_ROOT and PLUGIN_DATA,
expands the two placeholders once, resolves a ./ command against the root, and honours cwd. The
launcher is real: one test runs it and reads what the child process saw."""
import json
import os
import pathlib
import subprocess
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
import server as rn # noqa: E402
PKG = {"name": "demo-plugin", "files": [
{"path": "plugin.json", "content": "{}"},
{"path": "bin/probe.sh", "content": "#!/bin/sh\nprintf '%s|%s|%s|%s|' \"$PLUGIN_ROOT\" \"$PLUGIN_DATA\" \"$MODE\" \"$(pwd)\"; printf '%s|' \"$@\"\n"},
]}
def _server(**over):
return {"name": "probe", "plugin": "demo-plugin", "command": "./bin/probe.sh",
"args": ["--data", "${PLUGIN_DATA}/x", "${PLUGIN_ROOT}"], "env": {"MODE": "t-${PLUGIN_DATA}"}, **over}
def test_a_package_lands_at_its_root_with_a_data_directory(tmp_path):
roots = rn._write_plugins(str(tmp_path), [PKG])
assert roots == [str(tmp_path / ".harness/plugins/demo_plugin")]
assert (tmp_path / ".harness/plugins/demo_plugin/bin/probe.sh").is_file()
assert (tmp_path / ".harness/plugin-data/demo_plugin").is_dir()
def test_the_launcher_runs_the_command_with_root_data_env_cwd_and_args(tmp_path):
rn._write_plugins(str(tmp_path), [PKG])
(out,) = rn._plugin_launchers(str(tmp_path), [_server()])
assert out["name"] == "probe" and out["command"].endswith("/.launch-probe.sh") and "env" not in out
root = str(tmp_path / ".harness/plugins/demo_plugin")
data = str(tmp_path / ".harness/plugin-data/demo_plugin")
assert out["args"] == ["--data", f"{data}/x", root], "placeholders expand in args"
seen = subprocess.run([out["command"], *out["args"], "extra"], capture_output=True, text=True, timeout=10)
assert seen.returncode == 0, seen.stderr
got = seen.stdout.split("|")
assert got[0] == root and got[1] == data, "PLUGIN_ROOT and PLUGIN_DATA reach the process"
assert got[2] == f"t-{data}", "the env overlay is expanded and exported"
assert os.path.realpath(got[3]) == os.path.realpath(root), "cwd defaults to the plugin root"
assert got[4:8] == ["--data", f"{data}/x", root, "extra"], "args are passed as argv, unparsed"
def test_cwd_may_sit_in_the_root_or_the_data_directory_and_nowhere_else(tmp_path):
rn._write_plugins(str(tmp_path), [PKG])
(a,) = rn._plugin_launchers(str(tmp_path), [_server(cwd="${PLUGIN_DATA}/work")])
seen = subprocess.run([a["command"]], capture_output=True, text=True, timeout=10).stdout.split("|")
assert seen[3].endswith("/.harness/plugin-data/demo_plugin/work"), "a data-rooted cwd is created and used"
(b,) = rn._plugin_launchers(str(tmp_path), [_server(cwd="./sub")])
seen = subprocess.run([b["command"]], capture_output=True, text=True, timeout=10).stdout.split("|")
assert seen[3].endswith("/.harness/plugins/demo_plugin/sub")
assert rn._plugin_launchers(str(tmp_path), [_server(cwd="/etc")]) == []
assert rn._plugin_launchers(str(tmp_path), [_server(cwd="${PLUGIN_ROOT}/../../escape")]) == []
def test_an_escaping_command_is_dropped_and_a_bare_one_kept(tmp_path):
rn._write_plugins(str(tmp_path), [PKG])
assert rn._plugin_launchers(str(tmp_path), [_server(command="./../../bin/sh")]) == []
(bare,) = rn._plugin_launchers(str(tmp_path), [_server(command="sh", args=["-c", "echo hi"])])
assert subprocess.run([bare["command"], *bare["args"]], capture_output=True, text=True, timeout=10).stdout.strip() == "hi"
def test_the_reserved_names_cannot_be_overridden_from_env(tmp_path):
rn._write_plugins(str(tmp_path), [PKG])
(out,) = rn._plugin_launchers(str(tmp_path), [_server(env={"PLUGIN_ROOT": "/tmp/evil", "plugin_data": "/x", "MODE": "ok"})])
text = pathlib.Path(out["command"]).read_text()
assert "/tmp/evil" not in text and "plugin_data" not in text and "export MODE=ok" in text
assert text.count("export PLUGIN_ROOT=") == 1 and text.count("export PLUGIN_DATA=") == 1
def test_servers_that_are_not_a_plugins_pass_through(tmp_path):
direct = {"name": "vault", "url": "https://mcp.example.invalid/mcp"}
assert rn._plugin_launchers(str(tmp_path), [direct]) == [direct]
def test_a_plugin_without_a_root_in_this_workspace_is_skipped(tmp_path):
assert rn._plugin_launchers(str(tmp_path), [_server()]) == []
def test_every_url_only_writer_now_carries_a_stdio_entry(tmp_path):
srv = [{"name": "probe", "command": "/ws/.harness/plugin-data/demo/.launch-probe.sh", "args": ["--x", "1"]},
{"name": "vault", "url": "https://mcp.example.invalid/mcp"}]
toml = rn._codex_mcp_toml(srv)
assert '[mcp_servers.probe]\ncommand = "/ws/.harness/plugin-data/demo/.launch-probe.sh"\nargs = ["--x", "1"]' in toml
assert "[mcp_servers.vault]" in toml
hermes = rn._hermes_mcp_section(srv)
assert hermes["probe"] == {"command": "/ws/.harness/plugin-data/demo/.launch-probe.sh", "args": ["--x", "1"]}
assert hermes["vault"]["url"].startswith("https://")
home = tmp_path / "home"
rn._cline_settings(home, "https://relay", "k", "m", srv)
cline = json.loads((home / ".cline/data/settings/cline_mcp_settings.json").read_text())["mcpServers"]
assert cline["probe"]["transport"] == {"type": "stdio", "command": "/ws/.harness/plugin-data/demo/.launch-probe.sh", "args": ["--x", "1"]}
agent = tmp_path / "omp"
assert rn._omp_write_mcp(agent, srv)
omp = json.loads((agent / "mcp.json").read_text())["mcpServers"]
assert omp["probe"] == {"type": "stdio", "command": "/ws/.harness/plugin-data/demo/.launch-probe.sh", "args": ["--x", "1"]}
assert omp["vault"]["type"] == "http"
def test_a_dot_command_is_made_runnable_and_control_chars_are_escaped_for_codex(tmp_path):
pkg = {"name": "demo-plugin", "files": [{"path": "plugin.json", "content": "{}"},
{"path": "server.sh", "content": "#!/bin/sh\necho started\n"}]}
rn._write_plugins(str(tmp_path), [pkg])
(out,) = rn._plugin_launchers(str(tmp_path), [_server(command="./server.sh", args=["a\nb"])])
assert subprocess.run([out["command"]], capture_output=True, text=True, timeout=10).stdout.strip() == "started"
toml = rn._codex_mcp_toml([out])
assert "\\n" in toml and "\n\n" not in toml.split("args = ")[1].split("]")[0]
def test_stale_plugin_roots_and_skills_are_removed_on_the_next_turn(tmp_path):
rn._write_plugins(str(tmp_path), [PKG, {"name": "other", "files": [{"path": "plugin.json", "content": "{}"}]}])
assert (tmp_path / ".harness/plugins/other").is_dir()
rn._write_plugins(str(tmp_path), [PKG])
assert not (tmp_path / ".harness/plugins/other").exists() and (tmp_path / ".harness/plugins/demo_plugin").is_dir()
skill = {"name": "risk", "files": [{"path": "SKILL.md", "content": "---\nname: risk\ndescription: x\n---\n"}]}
rn._write_skills(str(tmp_path), [skill], "claude")
assert (tmp_path / ".harness/home/.claude/skills/risk/SKILL.md").is_file()
rn._write_skills(str(tmp_path), [], "claude")
assert not (tmp_path / ".harness/home/.claude/skills/risk").exists()
def test_a_symlinked_data_directory_is_not_followed(tmp_path):
rn._write_plugins(str(tmp_path), [PKG])
outside = tmp_path / "outside"; outside.mkdir()
data = tmp_path / ".harness/plugin-data/demo_plugin"
import shutil as _sh; _sh.rmtree(data); data.symlink_to(outside)
(out,) = rn._plugin_launchers(str(tmp_path), [_server()])
assert not data.is_symlink() and data.is_dir(), "the planted link is replaced by a real directory"
assert pathlib.Path(out["command"]).parent.resolve() == data.resolve()
assert not list(outside.iterdir()), "nothing was written through the link"
def test_pi_adapter_gets_a_stdio_command_entry(tmp_path):
"""pi-mcp-adapter spawns a stdio server itself (`command`, mutually exclusive with `url`), so
a plugin's server reaches pi as the launcher the runner wrote, beside the URL servers. Before
this the writer skipped anything without a url and the gateway refused the package for pi."""
home = tmp_path / "home"
servers = [{"name": "probe", "command": "/ws/.harness/plugin-data/hr_probe/.launch-probe.sh",
"args": ["--data", "/ws/.harness/plugin-data/hr_probe"], "plugin": "hr-probe"},
{"name": "remote", "url": "https://mcp.example.invalid/mcp", "headers": {"X-Team": "t"}}]
assert rn._pi_write_mcp(home, servers) is True
doc = json.loads((home / ".pi" / "agent" / "mcp-adapter.json").read_text())
# the tools are registered one by one, as on every other CLI; not behind the adapter's proxy
assert doc["settings"] == {"directTools": True, "disableProxyTool": True}
cfg = doc["mcpServers"]
assert cfg["probe"] == {"command": "/ws/.harness/plugin-data/hr_probe/.launch-probe.sh",
"args": ["--data", "/ws/.harness/plugin-data/hr_probe"]}
assert cfg["remote"] == {"url": "https://mcp.example.invalid/mcp", "headers": {"X-Team": "t"}}
def test_dsh_client_gets_a_stdio_row(tmp_path):
"""dsh-mcp-client has a stdio transport of its own (StdioClientTransport on command/args), so a
plugin's server is one more inserted client row, discriminated on transport."""
import yaml
import dsh_driver
home = tmp_path / "home"
servers = [{"name": "probe", "command": "/ws/.harness/plugin-data/hr_probe/.launch-probe.sh",
"args": ["--data", "/ws/.harness/plugin-data/hr_probe"], "plugin": "hr-probe"},
{"name": "remote", "url": "https://mcp.example.invalid/mcp"}]
out = pathlib.Path(dsh_driver._compose_patch(home, servers, relay_base="http://127.0.0.1:9999/v1", model="m",
cwd=str(tmp_path / "ws")))
rows = [r for e in yaml.safe_load(out.read_text()) if isinstance(e, dict) for r in (e.get("insert") or [])
if r.get("name") == "@deepseek-ai/dsh-mcp-client"]
by = {r["config"]["serverName"]: r["config"] for r in rows}
assert by["probe"] == {"transport": "stdio", "serverName": "probe", "cwd": str(tmp_path / "ws"),
"command": "/ws/.harness/plugin-data/hr_probe/.launch-probe.sh",
"args": ["--data", "/ws/.harness/plugin-data/hr_probe"]}
assert by["remote"]["transport"] == "streamable-http" and by["remote"]["url"] == "https://mcp.example.invalid/mcp"
def test_an_sse_server_reaches_each_client_in_its_own_spelling(tmp_path):
"""gemini and qwen name the transport by the key (`url` is SSE, `httpUrl` streamable HTTP);
cline and omp by a type. Every writer used to emit the streamable form for any url, so an sse
server was configured but never loaded (hosted, 2026-09-15: SSE=MISSING on all four)."""
sse = {"name": "probe_sse", "url": "https://probe.example.invalid/sse", "transport": "sse"}
http = {"name": "probe_http", "url": "https://probe.example.invalid/mcp", "transport": "http"}
rn._gemini_settings(tmp_path / "g", [sse, http], "gemini-3.8-flash")
g = json.loads((tmp_path / "g" / ".gemini" / "settings.json").read_text())["mcpServers"]
assert g["probe_sse"] == {"url": sse["url"]} and g["probe_http"] == {"httpUrl": http["url"]}
rn._qwen_settings(tmp_path / "q", [sse, http])
q = json.loads((tmp_path / "q" / ".qwen" / "settings.json").read_text())["mcpServers"]
assert q["probe_sse"] == {"url": sse["url"]} and q["probe_http"] == {"httpUrl": http["url"]}
omp_dir = tmp_path / "omp"
assert rn._omp_write_mcp(omp_dir, [sse, http]) is True
o = json.loads((omp_dir / "mcp.json").read_text())["mcpServers"]
assert o["probe_sse"]["type"] == "sse" and o["probe_http"]["type"] == "http"
def test_a_client_without_sse_gets_the_server_through_the_stdio_bridge(tmp_path):
"""goose 1.50.0's ExtensionConfig has no sse variant, dsh-mcp-client's config is a union of
stdio and streamable-http, codex's client takes streamable HTTP and stdio. Each launches a
stdio server, so an SSE server reaches them as the bridge: url and headers in the launcher's
environment, never on its command line; other servers and other backends pass untouched."""
sse = {"name": "probe_sse", "url": "https://probe.example.invalid/sse", "transport": "sse",
"auth": "secret-token", "headers": {"X-Team": "t"}, "plugin": "hr-probe"}
http = {"name": "probe_http", "url": "https://probe.example.invalid/mcp", "transport": "http"}
for backend in ("goose", "dsh", "codex"):
out = rn._sse_bridges(str(tmp_path), [sse, http], backend)
assert out[1] == http
b = out[0]
assert b["name"] == "probe_sse" and b["plugin"] == "hr-probe" and b["args"] == [] and "url" not in b and "auth" not in b
text = pathlib.Path(b["command"]).read_text()
assert "HR_MCP_URL=https://probe.example.invalid/sse" in text and "HR_MCP_TRANSPORT=sse" in text
assert '"Authorization": "Bearer secret-token"' in text and '"X-Team": "t"' in text
assert text.rstrip().endswith("mcp_bridge.py") and os.access(b["command"], os.X_OK)
assert rn._sse_bridges(str(tmp_path), [sse, http], "claude") == [sse, http]
# the writers then see a stdio entry, as for any plugin server
ext = rn._goose_extensions(rn._sse_bridges(str(tmp_path), [sse, http], "goose"), None)
assert ext["probe_sse"]["type"] == "stdio" and ext["probe_http"]["type"] == "streamable_http"
# the other way round for CheetahClaws 3.5.88: its client speaks SSE and stdio, and its own
# streamable-HTTP client is answered 400 on initialize by a standard server (the public probe,
# 2026-09-27), so the streamable-HTTP server is the one that rides the bridge; a url with no
# transport is streamable HTTP too
bare = {"name": "probe_bare", "url": "https://probe.example.invalid/mcp"}
out = rn._sse_bridges(str(tmp_path), [sse, http, bare], "cheetahclaws")
assert out[0] == sse
for b, u in ((out[1], "https://probe.example.invalid/mcp"), (out[2], "https://probe.example.invalid/mcp")):
assert "url" not in b and b["args"] == []
text = pathlib.Path(b["command"]).read_text()
assert f"HR_MCP_URL={u}" in text and "HR_MCP_TRANSPORT=http" in text
def test_dsh_job_keeps_a_stdio_server(tmp_path):
"""_build_dsh hands the driver a job whose server list kept only urls, from before plugins:
the stdio row the driver knows how to write never saw the server (hosted, 2026-09-15, the
compose patch held the http row alone)."""
env = {"HOME": str(tmp_path)}
servers = [{"name": "probe", "command": "/ws/.launch-probe.sh", "args": ["--data", "/d"], "plugin": "hr-probe"},
{"name": "remote", "url": "https://mcp.example.invalid/mcp"}]
cmd = rn._build_dsh("deepseek", rn.Auth(api_key="k", base_url="https://api.deepseek.com"), "deepseek-v4-pro", "x", str(tmp_path), env, mcp_servers=servers)
job = json.loads(cmd[2])
assert [s["name"] for s in job["mcp_servers"]] == ["probe", "remote"]
def test_a_servers_auth_reaches_every_base_as_its_authorization_header(tmp_path):
"""One helper gives every writer a server's headers, `auth` first as Authorization and the
declared headers over it. Eight writers took only the declared headers, so the hosted plugs
server (auth minted per turn) answered 401 to kimi, aider, opencode, qwen, gemini, goose,
openhands and cline, and those bases had no browser (hr-test browser column, 2026-09-27)."""
import json
assert rn._mcp_headers({"auth": "tok"}) == {"Authorization": "Bearer tok"}
assert rn._mcp_headers({"auth": "bearer tok"}) == {"Authorization": "bearer tok"}
assert rn._mcp_headers({"auth": "tok", "headers": {"X-Team": "t", "Authorization": "Bearer mine"}}) == {"Authorization": "Bearer mine", "X-Team": "t"}
assert rn._mcp_headers({"headers": {"X": None}}) == {} and rn._mcp_headers(None) == {}
sv = [{"name": "plugs", "url": "http://127.0.0.1:8080/v1/mcp/plugs", "transport": "http", "auth": "tok"}]
want = {"Authorization": "Bearer tok"}
assert rn._opencode_mcp(sv)["plugs"]["headers"] == want
assert rn._goose_extensions(sv, None)["plugs"]["headers"] == want
assert rn._openhands_mcp_config(sv)["plugs"]["headers"] == want
assert rn._aider_mcp_servers(sv)["plugs"]["headers"] == want
assert rn._hermes_mcp_section(sv)["plugs"]["headers"] == want
assert json.loads(rn._kimi_mcp_config(tmp_path / "kimi", sv).read_text())["mcpServers"]["plugs"]["headers"] == want
rn._qwen_settings(tmp_path / "qwen", sv)
assert json.loads((tmp_path / "qwen" / ".qwen" / "settings.json").read_text())["mcpServers"]["plugs"]["headers"] == want
rn._gemini_settings(tmp_path / "gemini", sv)
assert json.loads((tmp_path / "gemini" / ".gemini" / "settings.json").read_text())["mcpServers"]["plugs"]["headers"] == want
assert 'http_headers = { "Authorization" = "Bearer tok" }' in rn._codex_mcp_toml(sv)
def _bridge_module():
import importlib.util
spec = importlib.util.spec_from_file_location("mcp_bridge", str(pathlib.Path(rn.__file__).with_name("mcp_bridge.py")))
br = importlib.util.module_from_spec(spec)
spec.loader.exec_module(br)
return br
def test_the_bridge_leaves_out_what_a_closed_tool_never_declared():
"""jcode's model writes its own `intent` argument into a remote tool's call; the browser's tools
are closed, and the bridge's own check refused each such call (three in one jcode turn on
gpt-5.4, 2026-10-14). The bridge forwards only what a closed schema declares."""
br = _bridge_module()
closed = {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"], "additionalProperties": False}
assert br.declared_only(closed, {"url": "https://example.com/", "intent": "open it"}) == {"url": "https://example.com/"}
opened = {"type": "object", "properties": {"url": {"type": "string"}}}
assert br.declared_only(opened, {"url": "u", "intent": "i"}) == {"url": "u", "intent": "i"} # an open schema takes extras
allowed = {**closed, "additionalProperties": True}
assert br.declared_only(allowed, {"url": "u", "intent": "i"}) == {"url": "u", "intent": "i"} # extras allowed: kept
assert br.declared_only(None, {"a": 1}) == {"a": 1} # an unknown tool: unchanged
# a free-form object argument travels whole: only top-level names a closed schema never declared go
rows = {"type": "object", "properties": {"sql": {"type": "string"}, "row": {"type": "object"}}, "additionalProperties": False}
got = br.declared_only(rows, {"sql": "select 1", "row": {"any": 1, "nested": {"x": [1, {"y": None}]}}, "intent": "q"})
assert got == {"sql": "select 1", "row": {"any": 1, "nested": {"x": [1, {"y": None}]}}}
def test_a_closed_tool_called_with_an_extra_argument_runs_through_the_real_bridge(tmp_path):
"""End to end: a streamable-HTTP server with one closed tool (the browser's shape), the bridge
as the stdio server a client launches, and a call carrying jcode's `intent`. Before, the bridge's
own check answered "Additional properties are not allowed"; now the server runs the tool with the
arguments it declares, whether the client listed the tools first or not."""
import asyncio
import socket
import threading
import time
from contextlib import asynccontextmanager
import uvicorn
from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client
from mcp.server.lowlevel import Server
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
from starlette.applications import Starlette
from starlette.routing import Mount
seen: list[dict] = []
remote = Server("probe")
navigate = types.Tool(name="navigate", description="Open a page.", inputSchema={
"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"], "additionalProperties": False})
@remote.list_tools()
async def _tools() -> list[types.Tool]:
return [navigate]
@remote.call_tool() # the server keeps its own check: it is the one that judges
async def _call(name: str, arguments: dict) -> list[types.TextContent]:
seen.append(dict(arguments))
return [types.TextContent(type="text", text=f"opened {arguments['url']}")]
manager = StreamableHTTPSessionManager(app=remote, json_response=True, stateless=True)
@asynccontextmanager
async def lifespan(_app):
async with manager.run():
yield
with socket.socket() as s:
s.bind(("127.0.0.1", 0))
port = s.getsockname()[1]
web = uvicorn.Server(uvicorn.Config(Starlette(routes=[Mount("/mcp", app=manager.handle_request)], lifespan=lifespan),
host="127.0.0.1", port=port, log_level="error"))
t = threading.Thread(target=web.run, daemon=True)
t.start()
deadline = time.time() + 15
while not web.started and time.time() < deadline:
time.sleep(0.05)
assert web.started, "the probe server did not start"
async def drive(list_first: bool):
params = StdioServerParameters(command=sys.executable, args=[str(pathlib.Path(rn.__file__).with_name("mcp_bridge.py"))],
env={**os.environ, "HR_MCP_URL": f"http://127.0.0.1:{port}/mcp/", "HR_MCP_TRANSPORT": "http"})
async with stdio_client(params) as (r, w):
async with ClientSession(r, w) as client:
await client.initialize()
if list_first:
assert [x.name for x in (await client.list_tools()).tools] == ["navigate"]
return await client.call_tool("navigate", {"url": "https://example.com/", "intent": "open the page"})
try:
for list_first in (True, False):
got = asyncio.run(drive(list_first))
assert not got.isError, got.content[0].text
assert got.content[0].text == "opened https://example.com/"
assert seen == [{"url": "https://example.com/"}, {"url": "https://example.com/"}]
finally:
web.should_exit = True
t.join(timeout=10)