Skip to content

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.

21.9 KB
Raw Blame
"""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)