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
plugins: an SSE server reaches each client in its own spelling; a transport a base cannot speak is recorded on the plugin (#181)
github-actions[bot]8534feec2161
diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.mdindex 92665191..75064f17 100644--- a/docs/self-hosting-guide.md+++ b/docs/self-hosting-guide.md@@ -754,7 +754,9 @@ round-trips on the next PUT. The harness's own `mcpServers` and `skills` stay exthere; a plugin's components are listed on the plugin. Names must not collide across the harness andits enabled plugins. A package that declares a process (a `stdio` server) installs on every base: therunner writes one launcher per server and each agent's own MCP client runs it (pi's adapter and dsh's-client included). `GET /v1/harnesses/{id}/plugin` exports the harness's own tools and Skills as a+client included). A remote server reaches each client in its own spelling; a transport a base's client+does not speak (SSE on codex, dsh and goose) is recorded on the plugin's `skipped` list with the reason+and the rest of the package installs. `GET /v1/harnesses/{id}/plugin` exports the harness's own tools and Skills as apackage, credentials omitted. The full contract is the[Plugins chapter](https://unifiedharnessprotocol.org/spec/2026-09-12/plugins) of the protocol.diff --git a/gateway/app.py b/gateway/app.pyindex 969db329..a38543e8 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -13484,6 +13484,14 @@ def _skill_key(name: str) -> str:"""The runner's skill directory name (its _skill_dir_name), so two skills the gateway seesas different cannot land in one folder."""return re.sub(r"[^A-Za-z0-9_-]+", "-", str(name or ""))+# Transports a base's own MCP client does not speak, by runner backend. A plugin server on one of+# these installs as `skipped` with the reason, so the omission is on the record (Plugins §2.2)+# rather than a silent miss in a turn; the plugin's other components still install. codex's client+# takes streamable HTTP and stdio; dsh-mcp-client's config is a union of stdio and streamable-http;+# goose 1.50.0's ExtensionConfig has no sse variant.+_MCP_TRANSPORTS_MISSING = {"codex": {"sse"}, "dsh": {"sse"}, "goose": {"sse"}}++def _plugin_invalid(name: str, path: str, reason: str) -> HTTPException:return uhp_error(422, "plugin_invalid", f"Plugin {name or 'package'}: {reason}", "plugins",{"path": path, "reason": reason})@@ -13816,6 +13824,8 @@ async def _plugins_prepare(body: HarnessBody, org: str, previous: list[dict] | Nderived object and the blob handle, which is exactly what a client reads back and PUTs again.`previous` is what the harness held before an update; packages the new list no longer refers toare deleted once the new list is validated."""+ backend = str(_BASE_CATALOG.get(body.base or "", {}).get("backend") or "")+ missing = _MCP_TRANSPORTS_MISSING.get(backend, set())staged: list[tuple[dict, str | None, str | None]] = [] # (entry, encoded files to store, kept blob)seen: dict[str, str] = {}for i, item in enumerate(body.plugins or []):@@ -13854,6 +13864,10 @@ async def _plugins_prepare(body: HarnessBody, org: str, previous: list[dict] | N# here instead, and written down: the turn would otherwise drop it with only a log line.kept: list[dict] = []for s in derived["mcpServers"]:+ if s.get("transport") in missing:+ derived["skipped"].append({"path": f"mcp.json#/mcpServers/{s['name']}",+ "reason": f"the {body.base} base's client has no {s['transport']} transport"})+ continueblocked = await _ssrf_check(str(s.get("url") or "")) if s.get("transport") != "stdio" else ""if blocked:derived["skipped"].append({"path": f"mcp.json#/mcpServers/{s['name']}",diff --git a/gateway/tests/test_plugins.py b/gateway/tests/test_plugins.pyindex 9e8354b6..e73fb7c8 100644--- a/gateway/tests/test_plugins.py+++ b/gateway/tests/test_plugins.py@@ -180,6 +180,24 @@ def test_a_disabled_plugin_stays_installed_and_clears_collisions(api):assert pl["name"] == "demo-plugin" and pl["enabled"] is False+def test_a_transport_a_base_cannot_speak_is_recorded_not_refused(api):+ """codex, dsh and goose have no SSE client: an sse server in a package lands in `skipped`+ with the reason and the rest of the package installs; a base with an SSE client keeps it."""+ mcp = {"$schema": MCP_SCHEMA, "mcpServers": {+ "events": {"type": "sse", "url": "https://mcp.example.invalid/sse"},+ "remote": {"type": "streamable-http", "url": "https://mcp.example.invalid/mcp"}}}+ r = api.post("/v1/harnesses", json={"name": "x", "base": "codex", "plugins": [{"files": _package(manifest=MANIFEST, mcp=mcp)}]})+ if r.status_code == 400:+ pytest.skip(f"codex is not a creatable base here: {r.json()['error']['code']}")+ assert r.status_code == 200, r.text+ (pl,) = r.json()["plugins"]+ assert [s["name"] for s in pl["mcpServers"]] == ["remote"] and [s["name"] for s in pl["skills"]] == ["demo-skill"]+ assert pl["skipped"] == [{"path": "mcp.json#/mcpServers/events", "reason": "the codex base's client has no sse transport"}]+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code", "plugins": [{"files": _package(manifest=MANIFEST, mcp=mcp)}]})+ (pl,) = r.json()["plugins"]+ assert {s["name"]: s["transport"] for s in pl["mcpServers"]} == {"events": "sse", "remote": "http"} and pl["skipped"] == []++def test_a_stdio_server_installs_on_every_base(api):"""pi's MCP adapter and dsh's MCP client each spawn a stdio server themselves (pi-mcp-adapter's`command`, dsh-mcp-client's `transport: stdio`), so no base refuses a package for needing adiff --git a/runner/dsh_driver.py b/runner/dsh_driver.pyindex 161b1d95..5e79fcd0 100644--- a/runner/dsh_driver.py+++ b/runner/dsh_driver.py@@ -421,12 +421,19 @@ def _compose_patch(home: pathlib.Path, servers: list[dict], llm: dict | None = Nname = "".join(c for c in str((s or {}).get("name") or f"mcp{i}") if c.isalnum() or c in "_-")[:32] or f"mcp{i}"if not url:# A plugin's stdio server: dsh-mcp-client's own stdio transport spawns the command- # (StdioClientTransport); the launcher the runner wrote carries env and cwd.+ # (StdioClientTransport); the launcher the runner wrote carries env and cwd. The row+ # names the workspace as cwd because the client's schema defaults it to "" and spawns+ # with that, which never starts (hosted, 2026-09-15); the launcher cd's on its own.if (s or {}).get("command"):inserted.append({"id": f"hr-mcp-{i}", "name": "@deepseek-ai/dsh-mcp-client",- "config": {"transport": "stdio", "serverName": name,+ "config": {"transport": "stdio", "serverName": name, "cwd": cwd,"command": str(s["command"]), "args": [str(a) for a in (s.get("args") or [])]}})continue+ if str((s or {}).get("transport") or "").lower() == "sse":+ # dsh-mcp-client's config is a union of stdio and streamable-http; an sse endpoint+ # driven as streamable HTTP never answers, so the row is not written.+ print(f"[dsh] '{name}': sse transport is not one dsh-mcp-client speaks, skipped", flush=True)+ continueentry = {"id": f"hr-mcp-{i}", "name": "@deepseek-ai/dsh-mcp-client","config": {"transport": "streamable-http", "serverName": name, "url": url}}hdrs: dict = {}diff --git a/runner/server.py b/runner/server.pyindex e58bb1e4..21607424 100644--- a/runner/server.py+++ b/runner/server.py@@ -2331,7 +2331,7 @@ def _omp_write_mcp(agent_dir: pathlib.Path, servers: list[dict] | None) -> bool:continueif not url:continue- entry: dict = {"type": "http", "url": url}+ entry: dict = {"type": "sse" if str((s or {}).get("transport") or "").lower() == "sse" else "http", "url": url}auth = (s or {}).get("auth")if auth:hdr = auth if str(auth).lower().startswith("bearer ") else f"Bearer {auth}"@@ -3491,7 +3491,9 @@ def _qwen_settings(home: pathlib.Path, mcp_servers: list[dict] | None) -> None:name = _skill_dir_name(sv.get("name") or sv.get("id") or f"server{i}")url = (sv.get("url") or "").strip()if url:- entry: dict = {"httpUrl": url}+ # Their schema names the transport by the key: `url` is an SSE endpoint, `httpUrl` a+ # streamable HTTP one; a server declared sse under httpUrl is silently never loaded.+ entry: dict = {"url": url} if str(sv.get("transport") or "").lower() == "sse" else {"httpUrl": url}hdrs = sv.get("headers")if isinstance(hdrs, dict) and hdrs:entry["headers"] = {str(k): str(v) for k, v in hdrs.items()}@@ -3608,7 +3610,9 @@ def _gemini_settings(home: pathlib.Path, mcp_servers: list[dict] | None, model:name = _skill_dir_name(sv.get("name") or sv.get("id") or f"server{i}")url = (sv.get("url") or "").strip()if url:- entry: dict = {"httpUrl": url}+ # Their schema names the transport by the key: `url` is an SSE endpoint, `httpUrl` a+ # streamable HTTP one; a server declared sse under httpUrl is silently never loaded.+ entry: dict = {"url": url} if str(sv.get("transport") or "").lower() == "sse" else {"httpUrl": url}hdrs = sv.get("headers")if isinstance(hdrs, dict) and hdrs:entry["headers"] = {str(k): str(v) for k, v in hdrs.items()}@@ -3756,7 +3760,7 @@ def _cline_settings(home: pathlib.Path, base_url: str, api_key: str, model: str,continueif not url:continue- entry: dict = {"transport": {"type": "streamableHttp", "url": url}}+ entry: dict = {"transport": {"type": "sse" if str(sv.get("transport") or "").lower() == "sse" else "streamableHttp", "url": url}}hdrs = sv.get("headers")if isinstance(hdrs, dict) and hdrs:entry["transport"]["headers"] = {str(k): str(v) for k, v in hdrs.items()}@@ -4450,6 +4454,11 @@ def _goose_extensions(mcp_servers: list[dict] | None, tools_disabled: list[str]url = (sv.get("url") or "").strip()cmd = sv.get("command")if url:+ if str(sv.get("transport") or "").lower() == "sse":+ # goose 1.50.0's ExtensionConfig has no sse variant (stdio, builtin, platform,+ # streamable_http); an sse entry would fail to parse and take the config with it.+ print(f"[goose] '{name}': sse transport is not one goose speaks, skipped", flush=True)+ continueentry: dict = {"enabled": True, "type": "streamable_http", "name": name,"uri": url, "timeout": 300}hdrs = sv.get("headers")diff --git a/runner/tests/test_uhp_plugins.py b/runner/tests/test_uhp_plugins.pyindex 0fe179d8..03ae4d28 100644--- a/runner/tests/test_uhp_plugins.py+++ b/runner/tests/test_uhp_plugins.py@@ -162,7 +162,41 @@ def test_dsh_client_gets_a_stdio_row(tmp_path):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",+ 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_clients_without_an_sse_transport_leave_the_server_out(tmp_path):+ """goose 1.50.0's ExtensionConfig has no sse variant and dsh-mcp-client's config is a union of+ stdio and streamable-http: an sse endpoint driven as streamable HTTP never answers, so neither+ writer emits it (the gateway records the omission on the plugin at install time)."""+ import dsh_driver+ sse = {"name": "probe_sse", "url": "https://probe.example.invalid/sse", "transport": "sse"}+ http = {"name": "probe_http", "url": "https://probe.example.invalid/mcp", "transport": "http"}+ ext = rn._goose_extensions([sse, http], None)+ assert "probe_sse" not in ext and ext["probe_http"]["type"] == "streamable_http"+ out = pathlib.Path(dsh_driver._compose_patch(tmp_path / "home", [sse, http], relay_port=9999, model="m", cwd=str(tmp_path)))+ import yaml+ names = [r["config"]["serverName"] 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"]+ assert names == ["probe_http"]