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: the UHP 2026-09-12 sub-protocol in the gateway, runner and console (#175)
github-actions[bot]9bbff0ae4f75
diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.mdindex 13a8fe4c..f9d9012c 100644--- a/docs/self-hosting-guide.md+++ b/docs/self-hosting-guide.md@@ -718,6 +718,45 @@ It is created in this self-hosted instance and authenticates requests to that CEneither a Cloud key, your Console password, nor the model-provider key configuredin **Integrations**. Never put it in browser-side code or commit it to Git.+### Install a plugin on a harness++A plugin is a folder in the [Agent Plugins](https://agent-plugins.org) format: `plugin.json` at its+root, tools in `mcp.json`, Skills under `skills/`. Installing one gives a harness all of it at once,+and the harness records it as a named, versioned package it can export again. Starter kits built from+the kit release that carries plugin packages ship their Skills this way, so a kit launched from such+an image shows the kit as an installed plugin; a kit launched earlier keeps its Skills as its own.++In the Console, open the harness, find **Plugins**, and choose **Install from folder**. Over the API,+`plugins` is a field of the harness record. The simplest case is a new harness created with the+package in it:++```bash+curl -s -X POST "$HARNESSROUTER_BASE_URL/v1/harnesses" \+ -H "Authorization: Bearer $HARNESSROUTER_API_KEY" -H "Content-Type: application/json" \+ -d '{"name":"Contract Review Agent","base":"claude-code",+ "plugins":[{"files":[+ {"path":"plugin.json","content":"{\"$schema\":\"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json\",\"name\":\"contract-review\"}"},+ {"path":"skills/risk-checklist/SKILL.md","content":"---\nname: risk-checklist\ndescription: Turn an agreement into a risk checklist.\n---\n..."}+ ]}]}'+```++To add a plugin to a harness that already exists, remember that `PUT /v1/harnesses/{id}` replaces+the whole mutable configuration: any field you leave out is cleared, and an omitted `mcp_servers`+also removes the hosted tools behind it. Read the harness first, then send back its current+`system_prompt`, `default_model`, `mcp_servers`, `skills`, `disabled_tools`, `additional_headers`,+`max_step` and `timeout_seconds` (the write body uses these snake_case names; the record you read+uses camelCase) with the new package appended to `plugins`. Installed plugins round-trip as+`{name, enabled, blob}`, so send those back unchanged and add the new one beside them.++The record you read back carries what the server derived from the package (`manifest`,+`mcpServers`, `skills`, and `skipped` for anything it could not load) and a `blob` handle that+round-trips on the next PUT. The harness's own `mcpServers` and `skills` stay exactly what you wrote+there; a plugin's components are listed on the plugin. Names must not collide across the harness and+its enabled plugins, and a package that declares a process (a `stdio` server) is refused on a base+that cannot run one. `GET /v1/harnesses/{id}/plugin` exports the harness's own tools and Skills as a+package, credentials omitted. The full contract is the+[Plugins chapter](https://unifiedharnessprotocol.org/spec/2026-09-12/plugins) of the protocol.+### Run a taskThis example assumes `HARNESSROUTER_API_KEY` is already set. Choose an installed harness and adiff --git a/gateway/app.py b/gateway/app.pyindex 01714735..ab9a05c9 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -18,6 +18,7 @@ import hmacimport jsonimport osimport re+import urllib.parseimport collectionsimport timeimport uuid@@ -2888,7 +2889,7 @@ async def _harness_plugins(harness_id: str, org: str, hdr_vals: dict[str, str] |together if the read failed (hv is None → empty plugins), never inconsistently (review #5).`sid`: the session this turn belongs to, used to scope the database tool's credential to it."""if not harness_id:- return [], [], [], []+ return [], [], [], [], []v = hvif not v:# An out-of-box harness has no stored record — there is nothing to read, and that is@@ -2896,7 +2897,7 @@ async def _harness_plugins(harness_id: str, org: str, hdr_vals: dict[str, str] |# of the deployment rather than of a saved configuration. Returning nothing here is why# the default harnesses, which is what most people actually use, had no image generation# and no document skills while custom ones did.- return [], _builtin_default_skills(), [], []+ return [], _builtin_default_skills(), [], [], []v = await _mcp_migrate(org, harness_id, v)def _arr(prop):@@ -3010,12 +3011,50 @@ async def _harness_plugins(harness_id: str, org: str, hdr_vals: dict[str, str] |continueskills_out.append({"name": name, "files": files, "content": sk.get("content")})+ # Installed plugins (Plugins §4, §6): each enabled package contributes its skills and its MCP+ # servers, and travels whole to the runner so a stdio server has a root to run from. The+ # harness's own lists above are never rewritten by any of this. Placeholders stay literal+ # here; the runner expands them where the paths exist.+ plugins_out: list[dict] = []+ for pe in _plugins_of(v):+ if not pe["enabled"]:+ continue+ pfiles = await _plugin_files_of(pe, org)+ if not pfiles:+ print(f"[plugins] '{pe['name']}' on {harness_id}: package missing from the blob store — not offered this turn", flush=True)+ continue+ plugins_out.append({"name": pe["name"], "files": pfiles})+ for sk in pe["skills"]:+ prefix = f"skills/{sk['name']}/"+ sfiles = [{**f, "path": f["path"][len(prefix):]} for f in pfiles+ if isinstance(f, dict) and str(f.get("path") or "").startswith(prefix)]+ if sfiles:+ seen.add(sk["name"])+ # A same-named own entry with enabled:false marks a built-in as off; the plugin's+ # skill is the one that is on, so it must not be filtered out under that name.+ suppressed = [n for n in suppressed if n != sk["name"]]+ skills_out.append({"name": sk["name"], "files": sfiles, "plugin": pe["name"]})+ for s in pe["mcpServers"]:+ if s.get("transport") == "stdio":+ mcp_out.append({"name": s["name"], "transport": "stdio", "command": s["command"],+ "args": list(s.get("args") or []), "env": dict(s.get("env") or {}),+ "cwd": s.get("cwd") or "", "plugin": pe["name"]})+ continue+ _blocked = await _ssrf_check(str(s.get("url") or ""))+ if _blocked:+ print(f"[plugins] refusing '{s['name']}' of {pe['name']} for harness {harness_id}: {_blocked}", flush=True)+ continue+ entry = {"name": s["name"], "url": s["url"], "transport": s.get("transport") or "http"}+ if isinstance(s.get("headers"), dict):+ entry["headers"] = {str(k): str(vv) for k, vv in s["headers"].items()}+ mcp_out.append(entry)+# Built-ins the harness never mentions: on when the image says so. Implicit, so the set follows# the image rather than whatever was true when the Harness was created.skills_out += _builtin_default_skills(seen)disabled_tools = [t for t in _arr("disabled_tools") if isinstance(t, str)]- return mcp_out, skills_out, suppressed, disabled_tools+ return mcp_out, skills_out, suppressed, disabled_tools, plugins_out# ── API ──────────────────────────────────────────────────────────────────────────@@ -3618,8 +3657,14 @@ async def llm_broker(path: str, request: Request):# retry. Added the structured error envelope. The old `detail` string is still emitted beside# it, because clients in the wild read it — it is documented as deprecated, not removed under# them.-UHP_VERSION = "2026-08-11"-UHP_VERSIONS = [UHP_VERSION]+UHP_VERSION = "2026-09-12"+# Both versions, one code path: 2026-09-12 is additive to 2026-08-11 (plugins, and nothing+# the earlier version defined changes shape), so the same objects answer either request and+# the header is the only thing that differs. VERSIONING.md, server rule 3.+UHP_VERSIONS = [UHP_VERSION, "2026-08-11"]+# The Agent Plugins manifest schemas this server installs (Plugins §7). A package targeting+# another version is refused with unsupported_plugin_schema naming this list.+UHP_PLUGIN_SCHEMAS = ["https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"]# Capabilities are declared, not inferred, and the conformance suite checks each one against the# behaviour it promises. Reporting false is a supported answer; omitting a key is not, because a@@ -3634,6 +3679,7 @@ UHP_CAPABILITIES = {"harness_management": True,"session_sharing": True,"idempotency": True,+ "plugins": True,}UHP_CONFORMANCE_CLASS = "full"@@ -3700,7 +3746,9 @@ async def _uhp_version(request: Request, call_next):"detail": f"This server does not implement UHP version '{want}'."},status_code=400, headers={"UHP-Version": UHP_VERSION})resp = await call_next(request)- resp.headers["UHP-Version"] = UHP_VERSION+ # The version SERVED, which is the one asked for when it is one this server speaks: both+ # versions answer with the same objects, so honouring the request is just saying so.+ resp.headers["UHP-Version"] = want if want in UHP_VERSIONS else UHP_VERSIONreturn resp@@ -3711,6 +3759,7 @@ def uhp_discovery() -> dict:Nothing here is principal-specific."""return {"object": "uhp.discovery", "protocol": "uhp","versions": UHP_VERSIONS, "default_version": UHP_VERSION,+ "plugin_schemas": UHP_PLUGIN_SCHEMAS,"conformance_class": UHP_CONFORMANCE_CLASS,"capabilities": dict(UHP_CAPABILITIES),# The version this build IS (baked by the release workflow). "dev" for a build that@@ -6631,7 +6680,7 @@ async def _resp_execute(translator: _RespTranslator, *, org: str, member: str, s# HR-INF-010: the caller (create_response) already read this harness's vertex — thread it in# instead of re-reading it twice more here. Beyond cutting reads, a same-request snapshot means# _harness_plugins and agent_doc can't observe a mid-turn config edit inconsistently.- mcp_servers, skills, skills_suppressed, tools_disabled = await _harness_plugins(harness_id, org, hdr_vals, hv=hv, sid=sid)+ mcp_servers, skills, skills_suppressed, tools_disabled, plugin_pkgs = await _harness_plugins(harness_id, org, hdr_vals, hv=hv, sid=sid)if mcp_servers or skills or skills_suppressed or tools_disabled:rec["plugins"] = {"mcp": [m.get("name") for m in mcp_servers], "skills": [s.get("name") for s in skills],"skills_off": skills_suppressed, "tools_off": tools_disabled}@@ -6719,7 +6768,7 @@ async def _resp_execute(translator: _RespTranslator, *, org: str, member: str, s"prompt": runner_prompt, "max_turns": max_step,"timeout_seconds": timeout_s,"auth": sandbox_auth, "resume_session_id": resume, "files": files_in,- "mcp_servers": mcp_servers, "skills": skills, "agent_doc": agent_doc,+ "mcp_servers": mcp_servers, "skills": skills, "plugins": plugin_pkgs, "agent_doc": agent_doc,"skills_suppressed": skills_suppressed, "tools_disabled": turn_tools_off,# Image generation, when an integration can serve it. A per-turn credential for# the broker, never a provider key — see _image_auth.@@ -12811,9 +12860,48 @@ def _kits() -> dict:return out+def _kit_plugin(kit: dict) -> dict | None:+ """The kit's plugin package, read whole from `<kit>/<harness.plugin>/` (an Agent Plugins+ package: plugin.json at its root, the kit's skills under skills/). A launched Harness installs+ it as a named, versioned plugin it can export, and the skills derive from the package; there+ is no second list of them to keep in step. None when the kit ships no package."""+ sub = str((kit.get("harness") or {}).get("plugin") or "")+ root = pathlib.Path(_KITS_DIR) / str(kit.get("id") or "") / sub+ if not sub:+ return None+ if not (root / "plugin.json").is_file():+ print(f"[kits] {kit.get('id')}: harness.plugin names {sub}/ but there is no plugin.json in it", flush=True)+ return None+ files: list[dict] = []+ for f in sorted(root.rglob("*")):+ if not f.is_file() or f.stat().st_size > _SKILL_FILE_MAX:+ continue+ raw = f.read_bytes()+ rel = f.relative_to(root).as_posix()+ try:+ files.append({"path": rel, "content": raw.decode()})+ except UnicodeDecodeError:+ files.append({"path": rel, "content_b64": base64.b64encode(raw).decode()})+ return {"files": files, "enabled": True}+++def _kit_skill_names(kit: dict) -> list[str]:+ """What launching this kit installs, for the catalog: the package's skills when it ships+ one, else the names kit.json lists."""+ pkg = _kit_plugin(kit)+ if pkg:+ try:+ return [s["name"] for s in _plugin_read_package(pkg["files"])["skills"]]+ except HTTPException:+ return []+ return [str(n) for n in ((kit.get("harness") or {}).get("skills") or [])]++def _kit_skills(kit: dict) -> list[dict]:- """A kit's own skills, read from its folder. Self-contained by design: a kit carries the- skills its Harness needs rather than depending on what the image happens to bundle."""+ """A kit's own skills, read from its folder, for a kit built before kits shipped a plugin+ package (harness.skills names them). Self-contained by design: a kit carries the skills its+ Harness needs rather than depending on what the image happens to bundle. Retire this with+ the last image whose kits bake predates the package layout."""root = pathlib.Path(_KITS_DIR) / str(kit.get("id") or "")out: list[dict] = []for name in (kit.get("harness") or {}).get("skills") or []:@@ -13216,6 +13304,7 @@ class HarnessBody(BaseModel):system_prompt: str | None = Nonemcp_servers: list | None = Noneskills: list | None = None+ plugins: list | None = None # installed Agent Plugins packages (Plugins chapter)disabled_tools: list | None = None # inherited/built-in tool names the harness disabledmax_step: int | None = None # default agent step budget for this harness's turnstimeout_seconds: int | None = None # default per-turn wall-clock cap@@ -13243,6 +13332,9 @@ def _harness_out(v: dict) -> dict:# Verbatim: what a client reads is what is stored, for every entry, which is the# ordinary contract and the only one there now is."mcpServers": _mcp_list(v), "skills": _parse(v.get("skills")),+ # Derived by the server from each package on every write, never copied into the two+ # lists above: a client that PUTs back what it read cannot install a plugin twice.+ "plugins": _plugins_of(v),"disabledTools": [t for t in _parse(v.get("disabled_tools")) if isinstance(t, str)],"additionalHeaders": [h for h in _parse(v.get("additional_headers")) if isinstance(h, str) and h.strip()],"maxStep": int(v.get("max_step")) if str(v.get("max_step") or "").isdigit() else None,@@ -13259,6 +13351,7 @@ def _harness_props(body: HarnessBody) -> dict:return {"name": body.name, "base": base, "base_label": body.base_label or base,"default_model": body.default_model or "", "system_prompt": body.system_prompt or "","mcp_servers": json.dumps(body.mcp_servers or []), "skills": json.dumps(body.skills or []),+ "plugins": json.dumps(body.plugins or []),"disabled_tools": json.dumps(body.disabled_tools or []),"additional_headers": json.dumps([str(h).strip() for h in (body.additional_headers or [])if isinstance(h, str) and str(h).strip()]),@@ -13357,6 +13450,535 @@ async def _skill_bundle_files(sk: dict) -> list:files = [{"path": "SKILL.md", "content": sk["content"]}]return files or []+# ── Plugins (UHP 2026-09-12, Plugins chapter) ─────────────────────────────────────────────+# A plugin IS an Agent Plugins 1.0.0 package: plugin.json at the root, MCP servers in mcp.json,+# skills under skills/. This gateway reads one the way that specification's client conformance+# section says (manifest validated and closed, components discovered from their fixed locations,+# a failure isolated to one component recorded rather than fatal), stores the package out of line,+# and records what it derived on the harness. The harness's own mcpServers and skills are never+# touched by a plugin: they report what a client wrote there, which is what keeps every 2026-08-11+# client working (Plugins §4.1). Names are unique across the harness and its enabled plugins, and a+# collision is refused here, at configuration time, rather than resolved silently in a turn.+_PLUGIN_MANIFEST_SCHEMA = UHP_PLUGIN_SCHEMAS[0]+_PLUGIN_MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json"+_PLUGIN_NAME_RE = re.compile(r"^(?!.*(--|\.\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$")+_SKILL_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")+_PLUGIN_PACKAGE_MAX = 16 * 1024 * 1024 # the JSON-encoded package; a plugin is code and prose, not data+_PLUGIN_MANIFEST_FIELDS = {"$schema", "name", "version", "description", "author", "homepage",+ "repository", "license", "keywords", "extensions"}+_PLUGIN_ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")+_PLUGIN_BLOB_RE = re.compile(r"^plg_[0-9a-f]{32}$")+# The derived object rides on the harness record beside the blob handle; the record has a hard+# per-property cap on the graph backing, so the manifest and component metadata are bounded here+# rather than truncated there.+_PLUGIN_DERIVED_MAX = 24_000+++def _plugin_blob_key(org: str, blob: str) -> str:+ """Packages are stored under the org that installed them: a handle is unguessable, but a+ handle that leaked would otherwise read another org's package back through a PUT."""+ return f"plugins/{org}/{blob}.json"+++def _skill_key(name: str) -> str:+ """The runner's skill directory name (its _skill_dir_name), so two skills the gateway sees+ as different cannot land in one folder."""+ return re.sub(r"[^A-Za-z0-9_-]+", "-", str(name or ""))+# Runner backends that can launch a stdio MCP server (each writer emits command/args). pi's MCP+# adapter and dsh take URLs only; a package that needs a process is refused for those bases rather+# than accepted and skipped in a turn, which Harnesses §4.1 forbids.+_STDIO_MCP_BACKENDS = {"claude", "codex", "hermes", "gemini", "qwen", "opencode", "goose", "omp", "cline"}+++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})+++def _plugin_path_ok(path, name: str) -> str:+ if not isinstance(path, str) or not path or path.startswith("/"):+ raise _plugin_invalid(name, str(path), "file paths are relative to the plugin root")+ if any(seg in ("", ".", "..") for seg in path.split("/")):+ raise _plugin_invalid(name, path, "the path escapes the plugin root")+ if any(ord(c) < 32 or c == "\x7f" for c in path) or "\\" in path:+ raise _plugin_invalid(name, path, "the path contains a control character or a backslash")+ return path+++def _plugin_frontmatter(text: str) -> dict:+ """The top-level scalars of a SKILL.md frontmatter: plain values, quoted values, trailing+ comments dropped, and `>` / `|` block scalars joined, which is what the Agent Skills fields+ (name, description) are written with in practice."""+ m = re.match(r"^---\r?\n(.*?)\r?\n---", text or "", flags=re.S)+ out: dict = {}+ key, block = None, None+ for line in (m.group(1) if m else "").splitlines():+ if line.startswith((" ", "\t")):+ if key and block is not None:+ block.append(line.strip())+ continue+ if key and block is not None:+ out[key] = " ".join(block).strip()+ block = None+ key = None+ if ":" not in line:+ continue+ k, v = line.split(":", 1)+ key, v = k.strip(), v.strip()+ v = re.sub(r"\s+#.*$", "", v)+ if v in (">", "|", ">-", "|-", ">+", "|+"):+ block = []+ continue+ out[key] = v.strip("'\"")+ if key and block is not None:+ out[key] = " ".join(block).strip()+ return out+++def _plugin_command_ok(cmd) -> str | None:+ """Agent Plugins §7.2.1: one executable token, a bare name or a plugin-relative ./ path."""+ if not isinstance(cmd, str) or not cmd or re.search(r"\s", cmd):+ return "command must be one executable token"+ if cmd.startswith("./"):+ if any(seg in ("", ".", "..") for seg in cmd[2:].split("/")):+ return "a plugin-relative command must stay within the plugin root"+ elif "/" in cmd:+ return "command must be a bare executable name or a path beginning with ./"+ return None+++def _plugin_cwd_ok(cwd) -> str | None:+ if not isinstance(cwd, str) or not cwd:+ return "cwd must be a string"+ for root in ("${PLUGIN_ROOT}", "${PLUGIN_DATA}", "."):+ if cwd == root or cwd.startswith(root + "/"):+ rest = cwd[len(root):].lstrip("/")+ if any(seg in (".", "..") for seg in rest.split("/") if rest):+ return "cwd escapes its root"+ return None+ return "cwd must be plugin-relative (./…) or rooted in ${PLUGIN_ROOT} or ${PLUGIN_DATA}"+++def _plugin_url_ok(url) -> str | None:+ if not isinstance(url, str) or not url:+ return "url must be a string"+ try:+ u = urllib.parse.urlsplit(url)+ except Exception: # noqa: BLE001+ return "url is not a URL"+ if u.scheme not in ("http", "https") or not u.hostname:+ return "url must be an absolute http or https URL"+ if u.username or u.password or u.fragment:+ return "url must not carry user information or a fragment"+ host = u.hostname.lower()+ loopback = host == "localhost" or host.startswith("127.") or host == "::1"+ if u.scheme == "http" and not loopback:+ return "a non-loopback url must use https"+ return None+++def _plugin_server(sname: str, cfg) -> tuple[dict | None, str | None]:+ """One mcp.json entry -> (a plugin MCP server object, None) or (None, why it is invalid)."""+ if not isinstance(cfg, dict):+ return None, "server entry is not an object"+ t = cfg.get("type")+ allowed = {"stdio": {"type", "command", "args", "env", "cwd"},+ "streamable-http": {"type", "url", "headers"},+ "sse": {"type", "url", "headers"}}.get(t)+ if allowed is None:+ return None, f"unknown transport type {t!r}"+ extra = set(cfg) - allowed+ if extra:+ return None, f"fields {sorted(extra)} do not belong to a {t} server"+ if t == "stdio":+ why = _plugin_command_ok(cfg.get("command"))+ if why:+ return None, why+ s: dict = {"name": sname, "transport": "stdio", "command": cfg["command"], "enabled": True}+ if "args" in cfg:+ if not isinstance(cfg["args"], list) or not all(isinstance(a, str) for a in cfg["args"]):+ return None, "args must be a list of strings"+ s["args"] = list(cfg["args"])+ if "env" in cfg:+ env = cfg["env"]+ if not isinstance(env, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in env.items()):+ return None, "env must be an object of strings"+ if not all(_PLUGIN_ENV_NAME_RE.match(k) for k in env):+ return None, "env names must be environment variable names (letters, digits, underscore)"+ if any(k.upper() in ("PLUGIN_ROOT", "PLUGIN_DATA") for k in env):+ return None, "env must not name PLUGIN_ROOT or PLUGIN_DATA; the server sets those"+ s["env"] = dict(env)+ if "cwd" in cfg:+ why = _plugin_cwd_ok(cfg["cwd"])+ if why:+ return None, why+ s["cwd"] = cfg["cwd"]+ return s, None+ why = _plugin_url_ok(cfg.get("url"))+ if why:+ return None, why+ s = {"name": sname, "transport": "http" if t == "streamable-http" else "sse",+ "url": cfg["url"], "enabled": True}+ if "headers" in cfg:+ hdrs = cfg["headers"]+ if not isinstance(hdrs, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in hdrs.items()):+ return None, "headers must be an object of strings"+ if len({k.lower() for k in hdrs}) != len(hdrs):+ return None, "a header name appears more than once under different casing"+ s["headers"] = dict(hdrs)+ return s, None+++def _plugin_read_package(files: list, sent_name: str | None = None) -> dict:+ """Read a package as an Agent Plugins client: {name, manifest, mcpServers, skills, skipped}.++ Fatal (refused with plugin_invalid or unsupported_plugin_schema): no manifest, a manifest that+ is not valid JSON or violates its closed schema, an escaping path, a `name` on the write that+ contradicts the manifest. Not fatal, recorded in `skipped`: an unknown manifest field, a+ non-object `extensions`, an invalid mcp.json or server entry, a skill folder whose SKILL.md+ does not conform. That split is Agent Plugins §5.2 and §11.3, and the recording is UHP's own+ rule that ignoring must be observable (Plugins §2.2)."""+ if not isinstance(files, list) or not files:+ raise _plugin_invalid(sent_name or "", "", "a plugin needs files")+ by_path: dict[str, dict] = {}+ for f in files:+ if not isinstance(f, dict):+ raise _plugin_invalid(sent_name or "", "", "files must be objects with a path")+ path = _plugin_path_ok(f.get("path"), sent_name or "")+ content, b64 = f.get("content"), f.get("content_b64")+ if content is None and b64 is None:+ raise _plugin_invalid(sent_name or "", path, "a file needs content or content_b64")+ if content is not None and b64 is not None:+ raise _plugin_invalid(sent_name or "", path, "a file carries content or content_b64, not both")+ if content is not None and not isinstance(content, str):+ raise _plugin_invalid(sent_name or "", path, "content must be a string")+ if b64 is not None:+ try:+ base64.b64decode(b64, validate=True)+ except Exception: # noqa: BLE001+ raise _plugin_invalid(sent_name or "", path, "content_b64 is not base64")+ if path in by_path:+ raise _plugin_invalid(sent_name or "", path, "the same path appears twice")+ by_path[path] = f+ skipped: list[dict] = []++ raw = by_path.get("plugin.json")+ if raw is None:+ raise _plugin_invalid(sent_name or "", "plugin.json", "no plugin.json at the plugin root")+ try:+ manifest = json.loads(raw.get("content") if raw.get("content") is not None+ else base64.b64decode(raw.get("content_b64") or "").decode())+ except Exception: # noqa: BLE001+ raise _plugin_invalid(sent_name or "", "plugin.json", "plugin.json is not valid JSON")+ if not isinstance(manifest, dict):+ raise _plugin_invalid(sent_name or "", "plugin.json", "plugin.json is not an object")+ if "$schema" not in manifest:+ raise _plugin_invalid(str(manifest.get("name") or sent_name or ""), "plugin.json#/$schema",+ "the manifest names no $schema")+ if manifest.get("$schema") not in UHP_PLUGIN_SCHEMAS:+ raise uhp_error(422, "unsupported_plugin_schema",+ "The manifest targets an Agent Plugins version this server does not install.",+ "plugins", {"supported": list(UHP_PLUGIN_SCHEMAS),+ "declared": manifest.get("$schema")})+ name = manifest.get("name")+ if not isinstance(name, str) or not _PLUGIN_NAME_RE.match(name) or len(name) > 64:+ raise _plugin_invalid(str(name or sent_name or ""), "plugin.json#/name",+ "name must be 1 to 64 characters of a-z, 0-9, hyphen and period, "+ "starting and ending alphanumeric, with no -- or ..")+ if sent_name and sent_name != name:+ raise _plugin_invalid(name, "plugin.json#/name",+ f"the write names the plugin {sent_name!r} but the manifest says {name!r}")+ for k, v in manifest.items():+ if k not in _PLUGIN_MANIFEST_FIELDS:+ skipped.append({"path": f"plugin.json#/{k}", "reason": "unknown top-level field, ignored"})+ elif k in ("version", "description", "homepage", "repository", "license") and not isinstance(v, str):+ raise _plugin_invalid(name, f"plugin.json#/{k}", f"{k} must be a string")+ elif k == "keywords" and not (isinstance(v, list) and all(isinstance(x, str) for x in v)):+ raise _plugin_invalid(name, "plugin.json#/keywords", "keywords must be a list of strings")+ elif k == "author" and not (isinstance(v, dict) and set(v) <= {"name", "email", "url"}+ and all(isinstance(x, str) for x in v.values())):+ raise _plugin_invalid(name, "plugin.json#/author",+ "author may carry only name, email and url, each a string")+ elif k == "extensions" and not isinstance(v, dict):+ skipped.append({"path": "plugin.json#/extensions", "reason": "extensions is not an object, ignored"})++ servers: list[dict] = []+ raw = by_path.get("mcp.json")+ if raw is not None:+ try:+ mcp = json.loads(raw.get("content") if raw.get("content") is not None+ else base64.b64decode(raw.get("content_b64") or "").decode())+ except Exception: # noqa: BLE001+ mcp = None+ entries = mcp.get("mcpServers") if isinstance(mcp, dict) else None+ if not isinstance(mcp, dict) or set(mcp) != {"$schema", "mcpServers"} or not isinstance(entries, dict):+ skipped.append({"path": "mcp.json", "reason": "not an object of exactly $schema and mcpServers"})+ entries = {}+ elif mcp.get("$schema") != _PLUGIN_MCP_SCHEMA:+ skipped.append({"path": "mcp.json#/$schema",+ "reason": "mcp.json targets a different Agent Plugins version than plugin.json"})+ entries = {}+ for sname, cfg in entries.items():+ s, why = _plugin_server(str(sname), cfg)+ if s is None:+ skipped.append({"path": f"mcp.json#/mcpServers/{sname}", "reason": why})+ else:+ servers.append(s)++ skills: list[dict] = []+ dirs = sorted({p.split("/")[1] for p in by_path if p.startswith("skills/") and p.count("/") >= 2})+ for d in dirs:+ md = by_path.get(f"skills/{d}/SKILL.md")+ if md is None:+ continue # a folder without SKILL.md is not a skill (Agent Plugins §7.1)+ try:+ text = md.get("content") if md.get("content") is not None else base64.b64decode(md.get("content_b64") or "").decode()+ except Exception: # noqa: BLE001+ text = ""+ fm = _plugin_frontmatter(text)+ if fm.get("name") != d or not _SKILL_NAME_RE.match(d) or len(d) > 64:+ skipped.append({"path": f"skills/{d}", "reason": "SKILL.md name must equal the directory name and follow Agent Skills naming"})+ continue+ if not fm.get("description") or len(fm["description"]) > 1024:+ skipped.append({"path": f"skills/{d}", "reason": "SKILL.md needs a description of at most 1024 characters"})+ continue+ skills.append({"name": d, "description": fm["description"]})+ return {"name": name, "manifest": manifest, "mcpServers": servers, "skills": skills, "skipped": skipped}+++def _plugins_of(v: dict | None) -> list[dict]:+ """The stored plugin entries of a harness vertex, each with every derived field present."""+ try:+ a = json.loads((v or {}).get("plugins") or "[]")+ except Exception: # noqa: BLE001+ a = []+ out = []+ for e in a if isinstance(a, list) else []:+ if isinstance(e, dict) and e.get("name"):+ out.append({"name": e["name"], "enabled": e.get("enabled", True) is not False,+ **({"blob": e["blob"]} if e.get("blob") else {}),+ "manifest": e.get("manifest") or {}, "mcpServers": e.get("mcpServers") or [],+ "skills": e.get("skills") or [], "skipped": e.get("skipped") or []})+ return out+++async def _plugin_files_of(entry: dict, org: str) -> list:+ files = entry.get("files")+ if not files and entry.get("blob") and _PLUGIN_BLOB_RE.match(str(entry["blob"])):+ raw = await _blob_get(_plugin_blob_key(org, str(entry["blob"])), kb=BLOB_KB)+ if raw:+ try:+ files = json.loads(raw.decode())+ except Exception: # noqa: BLE001+ files = None+ return files if isinstance(files, list) else []+++def _plugin_collisions(plugins: list[dict], mcp_servers: list | None, skills: list | None,+ reserved_mcp: tuple[str, ...] = ()) -> None:+ """Plugins §4.2: one namespace per component type across the harness and its enabled plugins.+ Names are compared the way the runner keys them (its MCP and skill directory sanitisers), so+ two names the protocol sees as different cannot land on one file. `reserved_mcp` names the+ servers this deployment attaches to a harness itself, such as a kit's hosted database."""+ servers: dict[str, str] = {}+ for s in mcp_servers or []:+ if isinstance(s, dict) and str(s.get("enabled")) not in ("False", "false", "0"):+ servers[_mcp_name(str(s.get("name") or "mcp"))] = "harness"+ for n in reserved_mcp:+ servers[_mcp_name(str(n))] = "harness"+ skill_owner: dict[str, str] = {}+ for sk in skills or []:+ if isinstance(sk, dict) and str(sk.get("enabled")) not in ("False", "false", "0"):+ skill_owner[_skill_key(str(sk.get("name") or sk.get("id") or ""))] = "harness"+ for pe in plugins:+ if not pe.get("enabled", True):+ continue+ for s in pe.get("mcpServers") or []:+ key = _mcp_name(str(s.get("name")))+ if key in servers:+ raise uhp_error(409, "plugin_conflict",+ f"MCP server '{s.get('name')}' exists on both {servers[key]} and plugin {pe['name']}.",+ "plugins", {"component": "mcp_server", "name": s.get("name"),+ "between": [servers[key], pe["name"]]})+ servers[key] = pe["name"]+ for sk in pe.get("skills") or []:+ key = _skill_key(sk["name"])+ if key in skill_owner:+ raise uhp_error(409, "plugin_conflict",+ f"skill '{sk['name']}' exists on both {skill_owner[key]} and plugin {pe['name']}.",+ "plugins", {"component": "skill", "name": sk["name"],+ "between": [skill_owner[key], pe["name"]]})+ skill_owner[key] = pe["name"]+++async def _plugins_prepare(body: HarnessBody, org: str, previous: list[dict] | None = None,+ reserved_mcp: tuple[str, ...] = ()) -> list[dict]:+ """Validate and store every package on a create or update, and derive what the harness records.++ Everything is checked before anything is stored, so a refused write leaves no orphan package+ behind and the harness unchanged (the caller writes nothing until this returns). Files always+ go to the blob store under this org: a package is bigger than the vertex prop cap by+ construction, and one storage path is one fewer to get wrong. What the vertex carries is the+ derived 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 to+ are deleted once the new list is validated."""+ base = _require_supported_base(body.base) if body.base else ""+ body.base = base or body.base+ backend = str(_BASE_CATALOG.get(base, {}).get("backend") or "")+ 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 []):+ if not isinstance(item, dict):+ raise uhp_error(400, "invalid_input", f"plugins[{i}]: must be an object.", "plugins")+ sent = None+ if "name" in item:+ if not isinstance(item["name"], str) or not item["name"]:+ raise _plugin_invalid("", "plugin.json#/name", "name must be a non-empty string when sent")+ sent = item["name"]+ files, blob = item.get("files"), item.get("blob")+ if files:+ blob = None # a fresh package supersedes whatever the handle held+ elif blob:+ if not isinstance(blob, str) or not _PLUGIN_BLOB_RE.match(blob):+ raise _plugin_invalid(sent or "", "", "the blob handle is not one this server issued")+ files = await _plugin_files_of({"blob": blob}, org)+ if not files:+ raise _plugin_invalid(sent or "", "", "the package this handle refers to is gone; send its files")+ else:+ raise _plugin_invalid(sent or "", "", "a plugin needs files or a blob handle")+ encoded = json.dumps(files)+ if len(encoded) > _PLUGIN_PACKAGE_MAX:+ raise uhp_error(413, "file_too_large", "The plugin package is larger than this server accepts.",+ "plugins", {"max_bytes": _PLUGIN_PACKAGE_MAX})+ derived = _plugin_read_package(files, sent)+ name = derived["name"]+ key = _mcp_name(name)+ if name in seen or key in seen.values():+ other = name if name in seen else next(n for n, k in seen.items() if k == key)+ raise uhp_error(409, "plugin_conflict", f"Plugins '{other}' and '{name}' would share one name.", "plugins",+ {"component": "plugin", "name": name, "between": [other, name]})+ seen[name] = key+ enabled = item.get("enabled", True) is not False+ if enabled and backend and backend not in _STDIO_MCP_BACKENDS \+ and any(s.get("transport") == "stdio" for s in derived["mcpServers"]):+ raise uhp_error(422, "unsupported_transport",+ f"Plugin {name} declares a stdio MCP server, which the {base} base cannot run.",+ "plugins", {"transport": "stdio", "base": base, "plugin": name})+ # A remote server this deployment's network policy would refuse at turn time is refused+ # here instead, and written down: the turn would otherwise drop it with only a log line.+ kept: list[dict] = []+ for s in derived["mcpServers"]:+ blocked = 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']}",+ "reason": f"refused by this deployment's network policy: {blocked}"})+ else:+ kept.append(s)+ derived["mcpServers"] = kept+ entry = {"name": name, "enabled": enabled, "manifest": derived["manifest"],+ "mcpServers": derived["mcpServers"], "skills": derived["skills"],+ "skipped": derived["skipped"]}+ if len(json.dumps(entry)) > _PLUGIN_DERIVED_MAX:+ raise _plugin_invalid(name, "plugin.json", "the manifest and component metadata exceed 24 KB")+ staged.append((entry, None if blob else encoded, blob))+ out = [e for e, _, _ in staged]+ _plugin_collisions(out, body.mcp_servers, body.skills, reserved_mcp)+ # Every check passed: store the fresh packages, then let go of the ones this write dropped.+ for entry, encoded, blob in staged:+ if encoded is not None:+ blob = _rid("plg")+ if not await _blob_put(_plugin_blob_key(org, blob), encoded.encode(), kb=BLOB_KB):+ raise uhp_error(502, "internal_error", f"Plugin {entry['name']}: the package could not be stored.", "plugins")+ entry["blob"] = blob+ kept_blobs = {e["blob"] for e in out}+ for pe in previous or []:+ if pe.get("blob") and pe["blob"] not in kept_blobs:+ await _blob_delete(_plugin_blob_key(org, str(pe["blob"])), kb=BLOB_KB)+ return out+++async def _plugins_discard(org: str, v: dict | None) -> None:+ """Delete the packages of a harness being deleted."""+ for pe in _plugins_of(v):+ if pe.get("blob"):+ await _blob_delete(_plugin_blob_key(org, str(pe["blob"])), kb=BLOB_KB)+++def _plugin_export_name(v: dict) -> str:+ """Plugins §5: the harness name as a plugin name, or the id when nothing usable remains."""+ def derive(s: str) -> str:+ s = re.sub(r"[^a-z0-9.]+", "-", (s or "").lower()).strip("-")+ s = re.sub(r"\.{2,}", ".", s).strip(".").strip("-")+ return s[:64].strip("-.")+ n = derive(str(v.get("name") or ""))+ if not n or not _PLUGIN_NAME_RE.match(n):+ n = derive(str(v.get("id") or "")) or "harness"+ return n if _PLUGIN_NAME_RE.match(n) else "harness"+++async def _harness_export_plugin(v: dict) -> dict:+ """The harness's own tools and skills as an Agent Plugins package (Plugins §5). Installed+ plugins, the prompt, the model, the base and disabled tools are not part of it; credentials+ never are, and each omission is written down so the importer knows what to re-enter."""+ files: list[dict] = [{"path": "plugin.json", "content": json.dumps(+ {"$schema": _PLUGIN_MANIFEST_SCHEMA, "name": _plugin_export_name(v)}, indent=2)}]+ skipped: list[dict] = []+ entries: dict = {}+ for s in _mcp_list(v):+ if str(s.get("enabled")) in ("False", "false", "0") or not s.get("url"):+ continue+ sname = str(s.get("name") or s.get("id") or "mcp")+ url = str(s["url"])+ try:+ u = urllib.parse.urlsplit(url)+ if u.username or u.password:+ url = urllib.parse.urlunsplit((u.scheme, u.hostname + (f":{u.port}" if u.port else ""),+ u.path, u.query, ""))+ skipped.append({"path": f"mcp.json#/mcpServers/{sname}/url",+ "reason": "credentials in the url are not exported"})+ except Exception: # noqa: BLE001+ pass+ entries[sname] = {"type": "sse" if (s.get("transport") or "").lower() == "sse" else "streamable-http",+ "url": url}+ for k in ("auth", "headers"):+ if s.get(k):+ skipped.append({"path": f"mcp.json#/mcpServers/{sname}/{k}",+ "reason": "credentials are not exported"})+ if entries:+ files.append({"path": "mcp.json", "content": json.dumps(+ {"$schema": _PLUGIN_MCP_SCHEMA, "mcpServers": entries}, indent=2)})+ try:+ skills = json.loads(v.get("skills") or "[]")+ except Exception: # noqa: BLE001+ skills = []+ for sk in skills if isinstance(skills, list) else []:+ if not isinstance(sk, dict) or str(sk.get("enabled")) in ("False", "false", "0"):+ continue+ sname = str(sk.get("name") or sk.get("id") or "")+ if not sname:+ continue+ for f in await _skill_bundle_files(sk):+ if not isinstance(f, dict) or not isinstance(f.get("path"), str):+ continue+ rel = f["path"]+ ok = rel and not rel.startswith("/") and not any(seg in ("", ".", "..") for seg in rel.split("/")) \+ and ((isinstance(f.get("content"), str)) != (f.get("content_b64") is not None))+ if not ok:+ skipped.append({"path": f"skills/{sname}/{rel}", "reason": "not a file a package can carry"})+ continue+ files.append({"path": f"skills/{sname}/{rel}",+ **({"content": f["content"]} if isinstance(f.get("content"), str) else {"content_b64": f["content_b64"]})})+ derived = _plugin_read_package(files)+ return {**derived, "enabled": True, "skipped": derived["skipped"] + skipped, "files": files}+++def _plugin_entry(v: dict, name: str) -> dict:+ pe = next((e for e in _plugins_of(v) if e["name"] == name), None)+ if not pe:+ raise uhp_error(404, "plugin_not_found", f"No plugin '{name}' on this harness.", "plugin_name")+ return pe++def _workspace_keep(item_ws: str, workspace: str, ws_default: bool) -> bool:"""Workspace filter with Default-Workspace leniency: unstamped legacy records belong@@ -13373,6 +13995,7 @@ async def create_harness(org: str, body: HarnessBody, request: Request) -> dict:workspace = request.headers.get("x-harness-workspace", "")body.mcp_servers = _mcp_servers_prepare(body.mcp_servers)body.skills = await _skills_prepare(body.skills)+ body.plugins = await _plugins_prepare(body, org)hid = _rid("chrn")now = str(int(time.time() * 1000))props = {"org": org, "member": member, "workspace": workspace, **_harness_props(body),@@ -13443,6 +14066,30 @@ async def get_harness_skill_files(org: str, hid: str, skill_id: str, request: Re"files": await _skill_bundle_files(sk)}[email protected]("/v1/orgs/{org}/harnesses/{hid}/plugins/{name}/files")+async def get_harness_plugin_files(org: str, hid: str, name: str, request: Request) -> dict:+ """The complete package of one installed plugin (Plugins §3.1), byte-for-byte."""+ await _owned_org(request, org)+ v = await _vertex_get(hid)+ if not v or v.get("org") != org or str(v.get("deleted")) in ("1", "true", "True"):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")+ pe = _plugin_entry(v, name)+ files = await _plugin_files_of(pe, org)+ if not files:+ raise uhp_error(500, "internal_error", f"The stored package of plugin '{name}' is missing.", "plugin_name")+ return {"name": pe["name"], "files": files}++[email protected]("/v1/orgs/{org}/harnesses/{hid}/plugin")+async def export_harness_plugin(org: str, hid: str, request: Request) -> dict:+ """The harness's own tools and skills as an Agent Plugins package (Plugins §5)."""+ await _owned_org(request, org)+ v = await _vertex_get(hid)+ if not v or v.get("org") != org or str(v.get("deleted")) in ("1", "true", "True"):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")+ return await _harness_export_plugin(await _mcp_migrate(org, hid, v) or v)++@app.put("/v1/orgs/{org}/harnesses/{hid}")async def update_harness(org: str, hid: str, body: HarnessBody, request: Request) -> dict:await _owned_org(request, org)@@ -13451,9 +14098,18 @@ async def update_harness(org: str, hid: str, body: HarnessBody, request: Requestif not cur or str(cur.get("org") or "") != org or str(cur.get("deleted")) in ("1", "true", "True"):raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")cur = await _mcp_migrate(org, hid, cur)+ # Harnesses §5.2: id, base and createdAt are immutable. A body naming a different base is+ # refused rather than applied, because applying it would change the behaviour of every+ # session already attached to this harness.+ if body.base and body.base != str(cur.get("base") or ""):+ raise uhp_error(409, "harness_mismatch",+ "A harness's base cannot change; create a different harness for a different base.",+ "base", {"base": cur.get("base")})+ body.base = str(cur.get("base") or body.base)# coalesce-upsert: created_at/org are untouched (only the provided props are set)body.mcp_servers = _mcp_servers_prepare(body.mcp_servers)body.skills = await _skills_prepare(body.skills)+ body.plugins = await _plugins_prepare(body, org, previous=_plugins_of(cur))await _vg_upsert("Harness", hid, {**_harness_props(body), "updated_at": str(int(time.time() * 1000))})# AFTER the write: _harness_props can still refuse this save (an unsupported base), and a# refused save that had already scrubbed a record would disconnect a database nobody removed.@@ -13475,6 +14131,7 @@ async def delete_harness(org: str, hid: str, request: Request) -> dict:# spending at a providerawait _hosted_scrub_removed(org, hid, _mcp_list(cur), [])await _media_harness_purge(hid)+ await _plugins_discard(org, cur)return {"id": hid, "deleted": True}@@ -13599,6 +14256,7 @@ async def create_harness_public(body: HarnessBody, request: Request) -> dict:raise uhp_error(401, "invalid_credential", "Missing or invalid API key.")body.mcp_servers = _mcp_servers_prepare(body.mcp_servers)body.skills = await _skills_prepare(body.skills)+ body.plugins = await _plugins_prepare(body, org)hid = _rid("chrn")now = str(int(time.time() * 1000))props = {"org": org, "member": member, "workspace": str(p.get("workspace") or ""),@@ -13646,7 +14304,7 @@ async def list_kits(request: Request) -> dict:"harnessId": (h or {}).get("id") or None,# What the kit actually installs, from its own config — so the card can say# what you get instead of asking you to take it on trust.- "skills": [str(n) for n in ((kit.get("harness") or {}).get("skills") or [])],+ "skills": _kit_skill_names(kit),# What a LAUNCHED kit is really running on. Not the same thing as the# recommendation: the person may have chosen differently at launch, or changed# it since. Showing the recommendation for a running kit would state something@@ -13687,6 +14345,48 @@ class KitLaunchBody(BaseModel):base: str = ""model: str = ""database: KitDatabaseBody | None = None+ # An existing Harness of yours to run the kit on, instead of the one launch made or would+ # make: the kit's app then talks to that Harness, which receives the kit's package and its+ # launch entries. How a package migrated to another Harness takes the kit with it.+ harness: str = ""+++def _plugin_files_key(files: list) -> list[tuple]:+ """A package's files as a comparable value: path, bytes and the executable bit, in path order."""+ out = []+ for f in files or []:+ if not isinstance(f, dict):+ continue+ body = f.get("content_b64") if f.get("content_b64") is not None else f.get("content")+ out.append((str(f.get("path") or ""), str(body or ""), bool(f.get("executable"))))+ return sorted(out)+++async def _kit_plugin_ensure(org: str, hid: str, v: dict, kit_plugin: dict,+ reserved_mcp: tuple[str, ...] = ()) -> dict | None:+ """The kit's current package on an existing kit Harness. Installed when the Harness holds no+ package of that name, replaced when it holds another version, left alone when the versions+ match; the kit's loose skills from before the package layout give way to the package's. Three+ kit Harnesses launched before their kits shipped packages stayed without one through a+ relaunch (hr-oss-test, 2026-09-14), while a fresh launch installed it."""+ want = _plugin_read_package(kit_plugin["files"])+ have = _plugins_of(v)+ same = next((e for e in have if e["name"] == want["name"]), None)+ if same and (same.get("manifest") or {}).get("version") == (want.get("manifest") or {}).get("version"):+ # The version matching is not the whole story: a kit whose files changed under the same+ # version (the Skill fix of 2026-09-14 shipped as 1.0.0 twice) would otherwise never reach+ # a launched Harness. Launch reflects the package on disk, byte for byte.+ stored = await _plugin_files_of({"blob": same["blob"]}, org) if same.get("blob") else []+ if _plugin_files_key(stored) == _plugin_files_key(kit_plugin["files"]):+ return None+ body = HarnessBody(name=str(v.get("name") or ""), base=str(v.get("base") or ""),+ plugins=[e for e in have if e["name"] != want["name"]] + [kit_plugin])+ body.plugins = await _plugins_prepare(body, org, previous=have, reserved_mcp=reserved_mcp)+ await _vg_upsert("Harness", hid, {"plugins": json.dumps(body.plugins), "skills": json.dumps([]),+ "updated_at": str(int(time.time() * 1000))})+ print(f"[kits] {v.get('kit')}: package {want['name']} {(want.get('manifest') or {}).get('version')} "+ f"{'replaced' if same else 'installed'} on {hid}", flush=True)+ return await _vertex_get(hid)@app.post("/v1/kits/{kit_id}/launch")@@ -13717,6 +14417,23 @@ async def launch_kit(kit_id: str, request: Request, body_in: KitLaunchBody | Nonexisting = next((r for r in await _vg_list_by_org("Harness", org)if str(r.get("kit") or "") == kit_id and str(r.get("deleted") or "0") != "1"),None)+ want_h = (body_in.harness if body_in else "").strip()+ if want_h and want_h != str((existing or {}).get("id") or ""):+ # Run the kit on a Harness the person already has. One kit, one Harness: the previous kit+ # Harness keeps its sessions and its package but is no longer the one the app talks to,+ # and a Harness already running another kit is not taken over.+ target = await _vertex_get(want_h)+ if not target or str(target.get("org") or "") != org or str(target.get("deleted") or "0") == "1":+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness")+ other = str(target.get("kit") or "")+ if other and other != kit_id:+ raise uhp_error(409, "kit_conflict", f"That Harness runs the '{other}' kit.", "harness", {"kit": other})+ now0 = str(int(time.time() * 1000))+ if existing:+ await _vg_upsert("Harness", str(existing["id"]), {"kit": "", "updated_at": now0})+ await _vg_upsert("Harness", want_h, {"kit": kit_id, "updated_at": now0})+ existing = await _vertex_get(want_h) or {**target, "kit": kit_id}+ print(f"[kits] {kit_id} now runs on {want_h}", flush=True)if decl and not db_in and not existing:# Declaring launch.database is what makes it required: every panel this kit builds would# have nothing to read, so a launch without a connection is not a partial success.@@ -13743,6 +14460,13 @@ async def launch_kit(kit_id: str, request: Request, body_in: KitLaunchBody | Non# one record, not two of each.await _hosted_media_attach(org, hid0, existing, media_decl)existing = await _vertex_get(hid0) or existing+ kit_plugin = _kit_plugin(kit)+ if kit_plugin:+ # The package comes from the kit definition, like the database tool above: a Harness+ # launched before the kit shipped one, or one holding an older version, gets the+ # current package on the next press of Launch. Same version: nothing is rewritten.+ existing = await _kit_plugin_ensure(org, hid0, existing, kit_plugin, tuple(+ str(d["name"]) for d in (decl, media_decl) if d and d.get("name"))) or existingreturn {"kit": kit_id, "harnessId": hid0,"route": (kit.get("app") or {}).get("route") or "", "created": False,"harness": _harness_out(existing)}@@ -13763,15 +14487,23 @@ async def launch_kit(kit_id: str, request: Request, body_in: KitLaunchBody | Nonbase, model = want_base, want_modelelse:base, model = await _kit_base(org, kit)+ kit_plugin = _kit_plugin(kit)body = HarnessBody(name=spec.get("name") or kit.get("title") or kit_id,base=base,default_model=model,system_prompt=spec.get("system_prompt") or "",- skills=_kit_skills(kit),+ # A kit that ships a package installs it; its skills derive from the+ # package. A kit from before that layout still carries them directly.+ skills=[] if kit_plugin else _kit_skills(kit),+ plugins=[kit_plugin] if kit_plugin else [],mcp_servers=spec.get("mcp_servers") or [],disabled_tools=spec.get("disabled_tools") or [])body.mcp_servers = _mcp_servers_prepare(body.mcp_servers)body.skills = await _skills_prepare(body.skills)+ # The hosted entries launch attaches below (a kit's database, the media server) are names a+ # plugin's own servers must not take, so they count as the harness's here.+ body.plugins = await _plugins_prepare(body, org, reserved_mcp=tuple(+ str(d["name"]) for d in (decl, media_decl) if d and d.get("name")))hid = _rid("chrn")now = str(int(time.time() * 1000))props = {"org": org, "member": member, "workspace": str(p.get("workspace") or ""),@@ -13921,11 +14653,37 @@ async def _cloud_me(base_url: str, api_key: str) -> dict:return me-async def _cloud_harness_body(org: str, hid: str, v: dict) -> dict:+async def _cloud_harness_body(org: str, hid: str, v: dict, plugins_ok: bool = False) -> dict:"""What travels: the harness config, with every skill's files inlined (a bundle the localinstance offloaded to a blob is a local detail; the hosted side gets the files). Never:- provider keys (not part of a harness), sessions, produced files, the local workspace."""+ provider keys (not part of a harness), sessions, produced files, the local workspace.++ Installed plugins travel whole, with their files, when the hosted side reports the plugins+ capability. When it does not (a hosted side still on 2026-08-11), each enabled plugin travels+ as what it contains, its skills and its remote servers on the harness's own lists, so the+ hosted copy runs the same way; a stdio server has no place there and is left out."""out = _harness_out(await _mcp_migrate(org, hid, v))+ plugins: list[dict] = []+ mcp_extra: list[dict] = []+ skills_extra: list[dict] = []+ for pe in _plugins_of(v):+ pfiles = await _plugin_files_of(pe, org)+ if not pfiles:+ continue+ if plugins_ok:+ plugins.append({"name": pe["name"], "enabled": pe["enabled"], "files": pfiles})+ continue+ if not pe["enabled"]:+ continue+ for sk in pe["skills"]:+ prefix = f"skills/{sk['name']}/"+ sfiles = [{**f, "path": f["path"][len(prefix):]} for f in pfiles+ if isinstance(f, dict) and str(f.get("path") or "").startswith(prefix)]+ if sfiles:+ skills_extra.append({"name": sk["name"], "enabled": True, "files": sfiles})+ for s in pe["mcpServers"]:+ if s.get("transport") != "stdio" and s.get("url"):+ mcp_extra.append({k: s[k] for k in ("name", "url", "transport", "headers") if k in s})skills = []for sk in out.get("skills") or []:if not isinstance(sk, dict):@@ -13942,7 +14700,8 @@ async def _cloud_harness_body(org: str, hid: str, v: dict) -> dict:skills.append(sk)return {"name": out["name"], "base": out["base"], "base_label": out.get("baseLabel") or out["base"],"default_model": out.get("defaultModel") or None, "system_prompt": out.get("systemPrompt") or None,- "mcp_servers": out.get("mcpServers") or [], "skills": skills,+ "mcp_servers": (out.get("mcpServers") or []) + mcp_extra, "skills": skills + skills_extra,+ **({"plugins": plugins} if plugins_ok else {}),"disabled_tools": out.get("disabledTools") or [], "max_step": out.get("maxStep"),"timeout_seconds": out.get("timeoutSeconds"), "additional_headers": out.get("additionalHeaders") or [],"kit": out.get("kit") or None,@@ -13962,7 +14721,14 @@ async def _cloud_upload_one(org: str, hid: str, target: dict, records: dict) ->v = await _vertex_get(hid)if not v or str(v.get("org") or "") != org or str(v.get("deleted") or "") in ("1", "true"):return {"id": hid, "ok": False, "action": "skip", "error": "not found"}- body = await _cloud_harness_body(org, hid, v)+ plugins_ok = False+ try:+ async with httpx.AsyncClient(timeout=httpx.Timeout(10.0, connect=5.0)) as c:+ d = (await c.get(f"{target['base_url']}/v1/uhp")).json()+ plugins_ok = bool((d.get("capabilities") or {}).get("plugins"))+ except Exception: # noqa: BLE001+ plugins_ok = False+ body = await _cloud_harness_body(org, hid, v, plugins_ok)fp = _cloud_fingerprint(body)per = records.setdefault("harnesses", {}).setdefault(hid, {})tkey = _cloud_tkey(target)@@ -14317,6 +15083,30 @@ async def get_harness_skill_files_public(hid: str, skill_id: str, request: Reque"files": await _skill_bundle_files(sk)}[email protected]("/v1/harnesses/{hid}/plugins/{name}/files")+async def get_harness_plugin_files_public(hid: str, name: str, request: Request) -> dict:+ """UHP Plugins §3.1: the complete package of one installed plugin."""+ org, _ = await _pub_org_member(request)+ v = await _vertex_get(hid)+ if not v or v.get("org") != org or str(v.get("deleted")) in ("1", "true", "True"):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")+ pe = _plugin_entry(v, name)+ files = await _plugin_files_of(pe, org)+ if not files:+ raise uhp_error(500, "internal_error", f"The stored package of plugin '{name}' is missing.", "plugin_name")+ return {"name": pe["name"], "files": files}++[email protected]("/v1/harnesses/{hid}/plugin")+async def export_harness_plugin_public(hid: str, request: Request) -> dict:+ """UHP Plugins §5: the harness's own tools and skills as an Agent Plugins package."""+ org, _ = await _pub_org_member(request)+ v = await _vertex_get(hid)+ if not v or v.get("org") != org or str(v.get("deleted")) in ("1", "true", "True"):+ raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")+ return await _harness_export_plugin(await _mcp_migrate(org, hid, v) or v)++@app.put("/v1/harnesses/{hid}")async def update_harness_public(hid: str, body: HarnessBody, request: Request) -> dict:org, _ = await _pub_org_member(request)@@ -14324,8 +15114,14 @@ async def update_harness_public(hid: str, body: HarnessBody, request: Request) -if not v or v.get("org") != org or str(v.get("deleted")) in ("1", "true", "True"):raise uhp_error(404, "harness_not_found", "No harness with that id.", "harness_id")v = await _mcp_migrate(org, hid, v)+ if body.base and body.base != str(v.get("base") or ""): # Harnesses §5.2, as in update_harness+ raise uhp_error(409, "harness_mismatch",+ "A harness's base cannot change; create a different harness for a different base.",+ "base", {"base": v.get("base")})+ body.base = str(v.get("base") or body.base)body.mcp_servers = _mcp_servers_prepare(body.mcp_servers)body.skills = await _skills_prepare(body.skills)+ body.plugins = await _plugins_prepare(body, org, previous=_plugins_of(v))await _vg_upsert("Harness", hid, {**_harness_props(body), "updated_at": str(int(time.time() * 1000))})# AFTER the write: see update_harness.await _hosted_scrub_removed(org, hid, _mcp_list(v), body.mcp_servers)@@ -14344,4 +15140,5 @@ async def delete_harness_public(hid: str, request: Request) -> dict:# spending at a providerawait _hosted_scrub_removed(org, hid, _mcp_list(v), [])await _media_harness_purge(hid)+ await _plugins_discard(org, v)return {"id": hid, "deleted": True}diff --git a/gateway/tests/test_plugins.py b/gateway/tests/test_plugins.pynew file mode 100644index 00000000..9b937f9d--- /dev/null+++ b/gateway/tests/test_plugins.py@@ -0,0 +1,334 @@+"""Plugins (UHP 2026-09-12, Plugins chapter): a package is read as an Agent Plugins client reads+it, what the server derives is what it records, refusals happen at configuration time, and a+harness exports as a package that installs again.++These drive the public UHP surface through the app so they measure the same thing the P-series+of the conformance suite measures, without a live turn: create, read, files, export, refusals.+"""+from __future__ import annotations++import json+import os+import sys++import pytest++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))+import app # noqa: E402+from fastapi.testclient import TestClient # noqa: E402++ORG = "plugorg"+HEADERS = {"x-harness-internal": "test-internal-key", "x-harness-org": ORG,+ "x-harness-member": "[email protected]"}+MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"+MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json"+++def _package(name="demo-plugin", *, manifest=None, mcp=None, skill=True, extra=None):+ files = []+ if manifest is not None:+ files.append({"path": "plugin.json", "content": json.dumps(manifest)})+ if mcp is not None:+ files.append({"path": "mcp.json", "content": json.dumps(mcp)})+ if skill:+ files += [+ {"path": "skills/demo-skill/SKILL.md",+ "content": "---\nname: demo-skill\ndescription: A fixture skill.\n---\n\nSee references/data.md.\n"},+ {"path": "skills/demo-skill/references/data.md", "content": "nested\n"},+ {"path": "bin/tool.bin", "content_b64": "AAECAwQF"},+ ]+ return files + (extra or [])+++MANIFEST = {"$schema": MANIFEST_SCHEMA, "name": "demo-plugin", "version": "1.0.0",+ "description": "A fixture.", "author": {"name": "Tester"}}+MCP = {"$schema": MCP_SCHEMA, "mcpServers": {+ "remote": {"type": "streamable-http", "url": "https://mcp.example.invalid/mcp",+ "headers": {"X-Team": "fixture"}},+ "local": {"type": "stdio", "command": "./bin/tool.bin", "args": ["--data", "${PLUGIN_DATA}"],+ "env": {"MODE": "test"}, "cwd": "${PLUGIN_ROOT}"},+}}++[email protected](scope="module")+def api():+ with TestClient(app.app) as c:+ class Api:+ def __getattr__(self, m):+ def call(path, **kw):+ kw["headers"] = {**HEADERS, **(kw.get("headers") or {})}+ return getattr(c, m)(path, **kw)+ return call+ yield Api()+++def _create(api, **cfg):+ r = api.post("/v1/harnesses", json={"name": "Plugged", "base": "claude-code", **cfg})+ assert r.status_code == 200, r.text+ return r.json()+++def test_discovery_advertises_both_versions_and_the_plugin_schemas(api):+ d = api.get("/v1/uhp").json()+ assert d["versions"] == ["2026-09-12", "2026-08-11"] and d["default_version"] == "2026-09-12"+ assert d["capabilities"]["plugins"] is True+ assert d["plugin_schemas"] == [MANIFEST_SCHEMA]+ # Both versions from one code path: a 2026-08-11 request is honoured and echoed as such.+ r = api.get("/v1/uhp", headers={"UHP-Version": "2026-08-11"})+ assert r.status_code == 200 and r.headers["uhp-version"] == "2026-08-11"+ r = api.get("/v1/uhp", headers={"UHP-Version": "2025-01-01"})+ assert r.status_code == 400 and r.json()["error"]["code"] == "unsupported_protocol_version"+++def test_a_package_is_derived_not_copied(api):+ h = _create(api, plugins=[{"files": _package(manifest=MANIFEST, mcp=MCP)}])+ assert h["mcpServers"] == [] and h["skills"] == [], "the harness's own lists absorbed the plugin's"+ (pl,) = h["plugins"]+ assert pl["name"] == "demo-plugin" and pl["enabled"] is True and pl["blob"]+ assert pl["manifest"]["name"] == "demo-plugin"+ servers = {s["name"]: s for s in pl["mcpServers"]}+ assert servers["remote"]["transport"] == "http" and servers["remote"]["headers"] == {"X-Team": "fixture"}+ assert servers["local"]["transport"] == "stdio" and servers["local"]["command"] == "./bin/tool.bin"+ assert servers["local"]["args"] == ["--data", "${PLUGIN_DATA}"], "placeholders must come back unexpanded"+ assert [s["name"] for s in pl["skills"]] == ["demo-skill"]+ assert pl["skipped"] == []+ # the files endpoint returns the whole package, byte for byte+ r = api.get(f"/v1/harnesses/{h['id']}/plugins/demo-plugin/files")+ assert r.status_code == 200+ paths = sorted(f["path"] for f in r.json()["files"])+ assert paths == ["bin/tool.bin", "mcp.json", "plugin.json", "skills/demo-skill/SKILL.md",+ "skills/demo-skill/references/data.md"]+ assert any(f.get("content_b64") == "AAECAwQF" for f in r.json()["files"])+ # a read then write keeps the package+ g = api.get(f"/v1/harnesses/{h['id']}").json()+ r = api.put(f"/v1/harnesses/{h['id']}", json={"name": "Renamed", "base": g["base"],+ "plugins": g["plugins"], "skills": g["skills"],+ "mcp_servers": g["mcpServers"]})+ assert r.status_code == 200, r.text+ r = api.get(f"/v1/harnesses/{h['id']}/plugins/demo-plugin/files")+ assert sorted(f["path"] for f in r.json()["files"]) == paths+++def test_no_manifest_is_refused(api):+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code",+ "plugins": [{"files": _package(manifest=None, mcp=MCP)}]})+ assert r.status_code == 422 and r.json()["error"]["code"] == "plugin_invalid"+++def test_unknown_schema_is_refused_naming_the_supported_ones(api):+ m = {**MANIFEST, "$schema": "https://agent-plugins.org/schemas/0.0.1/plugin.schema.json"}+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code",+ "plugins": [{"files": _package(manifest=m, mcp=None)}]})+ assert r.status_code == 422+ e = r.json()["error"]+ assert e["code"] == "unsupported_plugin_schema" and e["detail"]["supported"] == [MANIFEST_SCHEMA]+++def test_a_name_that_contradicts_the_manifest_is_refused(api):+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code",+ "plugins": [{"name": "other", "files": _package(manifest=MANIFEST, mcp=None)}]})+ assert r.status_code == 422 and r.json()["error"]["code"] == "plugin_invalid"+++def test_an_escaping_path_is_refused(api):+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code",+ "plugins": [{"files": _package(manifest=MANIFEST, mcp=None,+ extra=[{"path": "../x", "content": ""}])}]})+ assert r.status_code == 422 and r.json()["error"]["code"] == "plugin_invalid"+++def test_an_invalid_component_is_skipped_and_recorded(api):+ mcp = {"$schema": MCP_SCHEMA, "mcpServers": {+ "good": {"type": "streamable-http", "url": "https://mcp.example.invalid/mcp"},+ "bad": {"type": "carrier-pigeon", "url": "https://x"},+ "leaky": {"type": "stdio", "command": "./bin/tool.bin", "env": {"PLUGIN_ROOT": "/tmp"}},+ }}+ broken_skill = [{"path": "skills/wrong-name/SKILL.md",+ "content": "---\nname: other\ndescription: x\n---\n"}]+ h = _create(api, plugins=[{"files": _package(manifest={**MANIFEST, "vendorField": 1},+ mcp=mcp, extra=broken_skill)}])+ (pl,) = h["plugins"]+ assert [s["name"] for s in pl["mcpServers"]] == ["good"]+ assert [s["name"] for s in pl["skills"]] == ["demo-skill"]+ paths = sorted(s["path"] for s in pl["skipped"])+ assert paths == ["mcp.json#/mcpServers/bad", "mcp.json#/mcpServers/leaky",+ "plugin.json#/vendorField", "skills/wrong-name"]+ assert all(s["reason"] for s in pl["skipped"])+++def test_a_component_collision_with_the_harness_is_refused(api):+ direct = [{"name": "remote", "url": "https://direct.example.invalid/mcp", "transport": "http"}]+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code", "mcp_servers": direct,+ "plugins": [{"files": _package(manifest=MANIFEST, mcp=MCP)}]})+ assert r.status_code == 409+ e = r.json()["error"]+ assert e["code"] == "plugin_conflict"+ assert e["detail"] == {"component": "mcp_server", "name": "remote", "between": ["harness", "demo-plugin"]}+++def test_two_plugins_with_one_name_are_refused(api):+ r = api.post("/v1/harnesses", json={"name": "x", "base": "claude-code",+ "plugins": [{"files": _package(manifest=MANIFEST, mcp=None)},+ {"files": _package(manifest=MANIFEST, mcp=None, skill=False)}]})+ assert r.status_code == 409 and r.json()["error"]["code"] == "plugin_conflict"+++def test_a_disabled_plugin_stays_installed_and_clears_collisions(api):+ direct = [{"name": "remote", "url": "https://direct.example.invalid/mcp", "transport": "http"}]+ h = _create(api, mcp_servers=direct, plugins=[{"files": _package(manifest=MANIFEST, mcp=MCP), "enabled": False}])+ (pl,) = h["plugins"]+ assert pl["name"] == "demo-plugin" and pl["enabled"] is False+++def test_stdio_on_a_base_that_cannot_run_it_is_refused(api):+ r = api.post("/v1/harnesses", json={"name": "x", "base": "dsh",+ "plugins": [{"files": _package(manifest=MANIFEST, mcp=MCP)}]})+ assert r.status_code in (422, 400), r.text+ e = r.json()["error"]+ if r.status_code == 422 and e["code"] == "unsupported_transport":+ assert e["detail"]["transport"] == "stdio" and e["detail"]["base"] == "dsh"+ else:+ pytest.skip(f"dsh is not a creatable base here: {e['code']}")+++def test_export_is_a_package_that_installs_again_without_credentials(api):+ direct = [{"name": "vault", "url": "https://mcp.example.invalid/mcp", "transport": "http",+ "headers": {"X-Team": "t"}, "auth": "secret-token"}]+ skill = {"name": "own-skill", "enabled": True, "files": [+ {"path": "SKILL.md", "content": "---\nname: own-skill\ndescription: mine\n---\n"},+ {"path": "references/r.md", "content": "ref"}]}+ h = _create(api, mcp_servers=direct, skills=[skill])+ r = api.get(f"/v1/harnesses/{h['id']}/plugin")+ assert r.status_code == 200, r.text+ pl = r.json()+ files = {f["path"]: f for f in pl["files"]}+ manifest = json.loads(files["plugin.json"]["content"])+ assert manifest["$schema"] == MANIFEST_SCHEMA and manifest["name"] == "plugged" == pl["name"]+ entry = json.loads(files["mcp.json"]["content"])["mcpServers"]["vault"]+ assert entry == {"type": "streamable-http", "url": "https://mcp.example.invalid/mcp"}+ assert "secret-token" not in json.dumps(pl)+ assert {s["path"] for s in pl["skipped"]} == {"mcp.json#/mcpServers/vault/auth", "mcp.json#/mcpServers/vault/headers"}+ assert {"skills/own-skill/SKILL.md", "skills/own-skill/references/r.md"} <= set(files)+ h2 = _create(api, plugins=[{"files": pl["files"]}])+ (got,) = h2["plugins"]+ assert got["name"] == "plugged"+ assert [s["name"] for s in got["mcpServers"]] == ["vault"]+ assert [s["name"] for s in got["skills"]] == ["own-skill"]+++def test_a_missing_plugin_is_plugin_not_found(api):+ h = _create(api)+ r = api.get(f"/v1/harnesses/{h['id']}/plugins/nope/files")+ assert r.status_code == 404 and r.json()["error"]["code"] == "plugin_not_found"+++def test_export_name_derivation():+ assert app._plugin_export_name({"name": "Contract Review Agent", "id": "chrn_x"}) == "contract-review-agent"+ assert app._plugin_export_name({"name": "acme..Tools v2", "id": "chrn_x"}) == "acme.tools-v2"+ assert app._plugin_export_name({"name": "!!!", "id": "chrn_08da"}) == "chrn-08da"+++def test_a_kit_that_ships_a_package_launches_as_an_installed_plugin(api, tmp_path, monkeypatch):+ """The starter kits carry their skills as an Agent Plugins package; launch installs it, and+ the Harness records the kit as a named, versioned plugin rather than as loose skills."""+ kid = "demo-kit"+ plug = tmp_path / kid / "plugin"+ (plug / "skills" / "demo-skill").mkdir(parents=True)+ (plug / "plugin.json").write_text(json.dumps({"$schema": MANIFEST_SCHEMA, "name": "harnessrouter-demo",+ "version": "1.2.0", "description": "A kit."}))+ (plug / "skills" / "demo-skill" / "SKILL.md").write_text("---\nname: demo-skill\ndescription: fixture\n---\n")+ (plug / "skills" / "demo-skill" / "helper.py").write_text("print('hi')\n")+ monkeypatch.setattr(app, "_KITS_DIR", str(tmp_path))+ monkeypatch.setattr(app, "_kits", lambda: {kid: {+ "id": kid, "title": "Demo", "app": {"route": "/kits/demo"},+ "harness": {"name": "Demo", "plugin": "plugin", "recommended": [{"base": "claude-code", "model": "claude-opus-5"}]}}})+ r = api.post(f"/v1/kits/{kid}/launch", json={})+ assert r.status_code == 200, r.text+ h = r.json()["harness"]+ assert h["skills"] == [], "the kit's skills come from the package, not the direct list"+ (pl,) = h["plugins"]+ assert pl["name"] == "harnessrouter-demo" and pl["manifest"]["version"] == "1.2.0"+ assert [s["name"] for s in pl["skills"]] == ["demo-skill"] and pl["skipped"] == []+ files = api.get(f"/v1/harnesses/{h['id']}/plugins/harnessrouter-demo/files").json()["files"]+ assert sorted(f["path"] for f in files) == ["plugin.json", "skills/demo-skill/SKILL.md", "skills/demo-skill/helper.py"]+ again = api.post(f"/v1/kits/{kid}/launch", json={})+ assert again.status_code == 200 and again.json()["created"] is False and again.json()["harnessId"] == h["id"]+++def test_a_kit_harness_from_before_the_package_gets_it_on_the_next_launch(api, tmp_path, monkeypatch):+ """Three kit Harnesses launched before their kits shipped packages stayed without one through a+ relaunch (hr-oss-test, 2026-09-14). Launch on an existing Harness installs the kit's current+ package, replaces an older version, and leaves a matching one alone."""+ kid = "demo-kit-before-packages" # its own kit id: the org keeps the previous test's kit Harness+ plug = tmp_path / kid / "plugin"+ (plug / "skills" / "demo-skill").mkdir(parents=True)+ (plug / "skills" / "demo-skill" / "SKILL.md").write_text("---\nname: demo-skill\ndescription: fixture\n---\n")+ monkeypatch.setattr(app, "_KITS_DIR", str(tmp_path))+ kit = {"id": kid, "title": "Demo", "app": {"route": "/kits/demo"},+ "harness": {"name": "Demo", "recommended": [{"base": "claude-code", "model": "claude-opus-5"}]}}+ monkeypatch.setattr(app, "_kits", lambda: {kid: kit})+ first = api.post(f"/v1/kits/{kid}/launch", json={}).json() # the kit ships no package yet+ assert first["created"] is True and first["harness"]["plugins"] == []+ hid = first["harnessId"]+ (plug / "plugin.json").write_text(json.dumps({"$schema": MANIFEST_SCHEMA, "name": "harnessrouter-demo",+ "version": "1.0.0", "description": "A kit."}))+ kit["harness"]["plugin"] = "plugin" # the kit now ships one+ again = api.post(f"/v1/kits/{kid}/launch", json={}).json()+ assert again["created"] is False and again["harnessId"] == hid+ (pl,) = again["harness"]["plugins"]+ assert pl["name"] == "harnessrouter-demo" and pl["manifest"]["version"] == "1.0.0"+ assert [s["name"] for s in pl["skills"]] == ["demo-skill"] and again["harness"]["skills"] == []+ blob = pl.get("blob")+ same = api.post(f"/v1/kits/{kid}/launch", json={}).json()["harness"]["plugins"][0]+ assert same.get("blob") == blob, "a matching version is left alone, not re-stored"+ (plug / "plugin.json").write_text(json.dumps({"$schema": MANIFEST_SCHEMA, "name": "harnessrouter-demo",+ "version": "1.1.0", "description": "A kit."}))+ newer = api.post(f"/v1/kits/{kid}/launch", json={}).json()["harness"]["plugins"]+ assert [p["manifest"]["version"] for p in newer] == ["1.1.0"]+ # the same version with different bytes is a changed package too (the 2026-09-14 Skill fix)+ (plug / "skills" / "demo-skill" / "SKILL.md").write_text("---\nname: demo-skill\ndescription: fixture, revised\n---\n")+ revised = api.post(f"/v1/kits/{kid}/launch", json={}).json()["harness"]["plugins"][0]+ assert revised.get("blob") != newer[0].get("blob"), "changed files under the same version are installed"+ files = api.get(f"/v1/harnesses/{hid}/plugins/harnessrouter-demo/files").json()["files"]+ assert any("revised" in (f.get("content") or "") for f in files)+++def test_a_kit_can_move_to_a_harness_you_already_have(api, tmp_path, monkeypatch):+ """A package migrated to another Harness takes the kit with it: launch with `harness` binds the+ kit to that Harness, installs the kit's package there, and the previous kit Harness keeps its+ sessions and package but is no longer the one the app finds."""+ kid = "demo-kit-moves"+ plug = tmp_path / kid / "plugin"+ (plug / "skills" / "demo-skill").mkdir(parents=True)+ (plug / "plugin.json").write_text(json.dumps({"$schema": MANIFEST_SCHEMA, "name": "harnessrouter-moves", "version": "1.0.0", "description": "A kit."}))+ (plug / "skills" / "demo-skill" / "SKILL.md").write_text("---\nname: demo-skill\ndescription: fixture\n---\n")+ monkeypatch.setattr(app, "_KITS_DIR", str(tmp_path))+ kits = {kid: {"id": kid, "title": "Moves", "app": {"route": "/kits/moves"},+ "harness": {"name": "Moves", "plugin": "plugin", "recommended": [{"base": "claude-code", "model": "claude-opus-5"}]}},+ "other-kit": {"id": "other-kit", "title": "Other", "app": {"route": "/kits/other"},+ "harness": {"name": "Other", "recommended": [{"base": "claude-code", "model": "claude-opus-5"}]}}}+ monkeypatch.setattr(app, "_kits", lambda: kits)+ first = api.post(f"/v1/kits/{kid}/launch", json={}).json(); a = first["harnessId"]+ mine = _create(api, name="Mine")+ moved = api.post(f"/v1/kits/{kid}/launch", json={"harness": mine["id"]})+ assert moved.status_code == 200, moved.text+ assert moved.json()["harnessId"] == mine["id"] and moved.json()["created"] is False+ h = moved.json()["harness"]+ assert h["kit"] == kid and [p["name"] for p in h["plugins"]] == ["harnessrouter-moves"]+ assert api.get(f"/v1/harnesses/{a}").json().get("kit") in (None, "")+ again = api.post(f"/v1/kits/{kid}/launch", json={}).json()+ assert again["harnessId"] == mine["id"], "the kit now finds the Harness it moved to"+ other = api.post("/v1/kits/other-kit/launch", json={"harness": mine["id"]})+ assert other.status_code == 409 and other.json()["error"]["code"] == "kit_conflict"+ r = api.post(f"/v1/kits/{kid}/launch", json={"harness": "chrn_nothere"})+ assert r.status_code == 404+++def test_an_update_cannot_change_the_base(api):+ """Harnesses §5.2: id, base and createdAt are immutable on update."""+ h = _create(api)+ r = api.put(f"/v1/harnesses/{h['id']}", json={"name": "Moved", "base": "codex"})+ assert r.status_code == 409 and r.json()["error"]["code"] == "harness_mismatch"+ assert api.get(f"/v1/harnesses/{h['id']}").json()["base"] == "claude-code"+ r = api.put(f"/v1/harnesses/{h['id']}", json={"name": "Renamed", "base": "claude-code"})+ assert r.status_code == 200 and r.json()["name"] == "Renamed"diff --git a/runner/server.py b/runner/server.pyindex 0cb1734e..fcc93510 100644--- a/runner/server.py+++ b/runner/server.py@@ -50,6 +50,7 @@ import mimetypesimport osimport pathlibimport re+import shleximport shutilimport signalimport socket@@ -604,9 +605,19 @@ def _codex_mcp_toml(servers: list[dict]) -> str:blocks: list[str] = []for s in servers or []:url = (s or {}).get("url")+ name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")+ if not url and (s or {}).get("command"):+ # A stdio server (a plugin's, through its launcher): Codex's native shape.+ def _tq(x: str) -> str:+ s2 = str(x).replace("\\", "\\\\").replace('"', '\\"')+ s2 = s2.replace("\n", "\\n").replace("\t", "\\t").replace("\r", "\\r")+ s2 = "".join(c if ord(c) >= 32 and c != "\x7f" else f"\\u{ord(c):04X}" for c in s2)+ return '"' + s2 + '"'+ blocks.append("\n".join([f"[mcp_servers.{name}]", f"command = {_tq(s['command'])}",+ "args = [" + ", ".join(_tq(a) for a in (s.get("args") or [])) + "]"]))+ continueif not url:continue- name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")auth = (s or {}).get("auth")lines = [f"[mcp_servers.{name}]", f'url = "{url}"']# One http_headers inline table: Authorization from `auth` + any extra headers the@@ -628,6 +639,7 @@ def _codex_mcp_toml(servers: list[dict]) -> str:if not blocks:return ""# rmcp HTTP client is opt-in in Codex; enable it when any HTTP MCP server is configured.+ # (stdio servers need no switch; the flag is harmless beside them.)return "\nexperimental_use_rmcp_client = true\n" + "\n".join(blocks) + "\n"@@ -756,6 +768,29 @@ def _write_skills(cwd: str, skills: list[dict], backend: str = "claude") -> listif wrote:installed.append({"name": name, "desc": _skill_desc(files),"entry": f"{entryroot}/{name}/SKILL.md"})+ # Skills this runner wrote on an earlier turn of the session that this turn does not name+ # (disabled, removed, or a plugin's that is now off) are removed, so the CLI cannot keep+ # offering them. Only what this runner wrote is touched: the record of that is its own.+ now_names = {s["name"] for s in installed}+ ledger = _safe_join(cwd, ".harness/skills-written.json")+ if ledger is not None:+ before: list[str] = []+ try:+ before = [str(n) for n in json.loads(ledger.read_text())] if ledger.is_file() else []+ except Exception: # noqa: BLE001+ before = []+ for old in before:+ if old in now_names or not old:+ continue+ for rootrel in rootrels:+ d = _safe_join(str(pathlib.Path(cwd) / rootrel), old)+ if d is not None and d.is_dir() and not d.is_symlink():+ shutil.rmtree(d, ignore_errors=True)+ try:+ ledger.parent.mkdir(parents=True, exist_ok=True)+ ledger.write_text(json.dumps(sorted(now_names)))+ except Exception: # noqa: BLE001+ passreturn installed@@ -778,15 +813,18 @@ def _plugin_file_is_executable(rel: str, declared: bool | None) -> bool:def _write_plugins(cwd: str, plugins: list[dict]) -> list[str]:- """Materialize enabled Claude Code plugins into the workspace, one directory per plugin- under `.harness/plugins/<name>/`. Each plugin: {name, files:[{path, content|content_b64,- executable?}]}. Returns the absolute paths written, in order — the caller turns each into- one `--plugin-dir <path>` argument to `_build_claude`.-- A single root, unlike skills: a plugin is loaded exclusively through --plugin-dir, so- there is no discovery path to also mirror it under, and a stray second copy under- .claude/ would risk Claude Code loading the same plugin twice."""+ """Materialize each installed plugin package whole, at its own root under+ `.harness/plugins/<name>/`, with a writable data directory beside it under+ `.harness/plugin-data/<name>/` (UHP Plugins §6: PLUGIN_ROOT and PLUGIN_DATA). Each plugin:+ {name, files:[{path, content|content_b64, executable?}]}. Returns the roots written, in order.++ The package's skills reach the agent through the ordinary skill path (the gateway lists them+ in `skills`); its stdio servers run from this root through the launchers _plugin_launchers+ writes. A package that also carries `.claude-plugin/plugin.json` is a Claude Code plugin+ besides, and the claude branch hands that root to `--plugin-dir`: one root, never a second+ copy under .claude/, which would risk Claude Code loading the same plugin twice."""installed: list[str] = []+ wanted: set[str] = set()for pg in plugins or []:pg = pg or {}name = _mcp_name(pg.get("name") or pg.get("id") or "")@@ -794,8 +832,25 @@ def _write_plugins(cwd: str, plugins: list[dict]) -> list[str]:if not name or not files:continueroot = _safe_join(cwd, f".harness/plugins/{name}")- if root is None:+ data = _safe_join(cwd, f".harness/plugin-data/{name}")+ if root is None or data is None:+ continue+ wanted.add(name)+ # The runner writes as itself and the agent ran as the session's uid last turn: a root+ # or data directory it replaced with a symlink would redirect these writes, so the link+ # itself (the unresolved path) is removed before anything is written through it, and the+ # root is rebuilt from the package every turn so nothing from an older version lingers.+ for raw in (pathlib.Path(cwd) / ".harness" / "plugins" / name,+ pathlib.Path(cwd) / ".harness" / "plugin-data" / name):+ if raw.is_symlink():+ raw.unlink()+ root = _safe_join(cwd, f".harness/plugins/{name}")+ data = _safe_join(cwd, f".harness/plugin-data/{name}")+ if root is None or data is None:continue+ if root.exists():+ shutil.rmtree(root, ignore_errors=True)+ data.mkdir(parents=True, exist_ok=True)wrote = Falsefor f in files:f = f or {}@@ -809,20 +864,125 @@ def _write_plugins(cwd: str, plugins: list[dict]) -> list[str]:continuetry:dest.parent.mkdir(parents=True, exist_ok=True)+ # Written beside and renamed over: a binary a still-running server has open+ # cannot be truncated in place (ETXTBSY), and a rename replaces it regardless.+ tmp = dest.with_name(dest.name + ".hr-tmp")if content_b64 is not None:- dest.write_bytes(base64.b64decode(content_b64))+ tmp.write_bytes(base64.b64decode(content_b64))else:- dest.write_text(content)+ tmp.write_text(content)if _plugin_file_is_executable(rel, f.get("executable")):- dest.chmod(dest.stat().st_mode | 0o111)+ tmp.chmod(tmp.stat().st_mode | 0o111)+ os.replace(tmp, dest)wrote = Trueexcept Exception: # noqa: BLE001continueif wrote:installed.append(str(root))+ # A plugin removed or disabled since the last turn leaves nothing runnable behind.+ plugroot = _safe_join(cwd, ".harness/plugins")+ if plugroot is not None and plugroot.is_dir():+ for d in plugroot.iterdir():+ if d.name not in wanted:+ if d.is_symlink():+ d.unlink()+ else:+ shutil.rmtree(d, ignore_errors=True)return installed+_PLUGIN_PLACEHOLDER = re.compile(r"\$\{PLUGIN_(ROOT|DATA)\}")+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")+++def _plugin_launchers(cwd: str, servers: list[dict] | None) -> list[dict]:+ """The stdio servers a plugin declares, made runnable (UHP Plugins §6, Agent Plugins §7.2.1+ and §9): the two placeholders expanded once and non-recursively in args, env and cwd; a+ `./` command resolved against the plugin root and refused if it escapes; cwd defaulting to the+ root and confined to the root or the data directory; PLUGIN_ROOT and PLUGIN_DATA set last.++ All of that lands in one launcher script per server in the plugin's data directory, so every+ backend writer sees the same shape it already understands, {name, command, args}, and none of+ the nine has to learn env or cwd. The user's command is exec'd with its args as argv, never+ parsed by the shell. Servers that are not a plugin's pass through untouched."""+ out: list[dict] = []+ for s in servers or []:+ s = s or {}+ pname = s.get("plugin")+ if not pname or not s.get("command") or s.get("url"):+ out.append(s)+ continue+ dname = _mcp_name(str(pname))+ raw_data = pathlib.Path(cwd) / ".harness" / "plugin-data" / dname+ if raw_data.is_symlink(): # never write the launcher through a planted link+ raw_data.unlink()+ root = _safe_join(cwd, f".harness/plugins/{dname}")+ data = _safe_join(cwd, f".harness/plugin-data/{dname}")+ if root is None or data is None or not root.is_dir():+ print(f"[plugins] '{s.get('name')}': plugin {pname} has no root in this workspace — skipped", flush=True)+ continue+ data.mkdir(parents=True, exist_ok=True)+ subst = {"ROOT": str(root), "DATA": str(data)}++ def expand(x) -> str:+ return _PLUGIN_PLACEHOLDER.sub(lambda m: subst[m.group(1)], str(x))++ cmd = str(s["command"])+ if cmd.startswith("./"):+ target = _safe_join(str(root), cmd[2:])+ if target is None:+ print(f"[plugins] '{s.get('name')}': command escapes the plugin root — skipped", flush=True)+ continue+ # A package's own script is what the entry says to run; JSON has no file mode, so+ # the bit is set here rather than left to a naming convention.+ try:+ if target.is_file() and not target.is_symlink():+ target.chmod(target.stat().st_mode | 0o111)+ except Exception: # noqa: BLE001+ pass+ command = str(target)+ else:+ command = cmd # a bare name, resolved on PATH at exec+ raw_cwd = str(s.get("cwd") or "")+ if not raw_cwd or raw_cwd == ".":+ wd = root+ elif raw_cwd.startswith("./"):+ wd = _safe_join(str(root), raw_cwd[2:])+ else:+ candidate = pathlib.Path(expand(raw_cwd))+ wd = None+ for base in (root, data):+ try:+ candidate.resolve().relative_to(base.resolve())+ wd = candidate+ break+ except ValueError:+ continue+ if wd is None:+ print(f"[plugins] '{s.get('name')}': cwd escapes the plugin root and data directory — skipped", flush=True)+ continue+ args = [expand(a) for a in (s.get("args") or [])]+ env = {str(k): expand(v) for k, v in (s.get("env") or {}).items()+ if _ENV_NAME.match(str(k)) and str(k).upper() not in ("PLUGIN_ROOT", "PLUGIN_DATA")}+ launcher = data / f".launch-{_mcp_name(str(s.get('name') or 'mcp'))}.sh"+ lines = ["#!/bin/sh", "# written by the harness runner for one plugin MCP server; not user content"]+ lines += [f"export {k}={shlex.quote(v)}" for k, v in env.items()]+ lines += [f"export PLUGIN_ROOT={shlex.quote(str(root))}",+ f"export PLUGIN_DATA={shlex.quote(str(data))}",+ f"mkdir -p {shlex.quote(str(wd))} && cd {shlex.quote(str(wd))} || exit 1",+ f'exec {shlex.quote(command)} "$@"', ""]+ # Never through a link the session may have planted where the launcher goes: the data+ # directory is the agent's to write, and the runner writes here as itself.+ if launcher.is_symlink() or (launcher.exists() and not launcher.is_file()):+ launcher.unlink()+ fd = os.open(str(launcher), os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0), 0o755)+ with os.fdopen(fd, "w") as fh:+ fh.write("\n".join(lines))+ launcher.chmod(0o755)+ out.append({"name": s.get("name"), "command": str(launcher), "args": args, "plugin": pname})+ return out++_AGENTS_BEGIN = "<!-- harness-skills:begin -->"_AGENTS_END = "<!-- harness-skills:end -->"@@ -2157,9 +2317,15 @@ def _omp_write_mcp(agent_dir: pathlib.Path, servers: list[dict] | None) -> bool:entries: dict = {}for s in servers or []:url = (s or {}).get("url")+ name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")+ if not url and (s or {}).get("command"):+ # A stdio server (a plugin's, through its launcher): the standard mcpServers shape,+ # which the loader infers as stdio from `command` and which `type` states outright.+ entries[name] = {"type": "stdio", "command": str(s["command"]),+ "args": [str(a) for a in (s.get("args") or [])]}+ continueif not url:continue- name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")entry: dict = {"type": "http", "url": url}auth = (s or {}).get("auth")if auth:@@ -2300,9 +2466,13 @@ def _hermes_mcp_section(servers: list[dict] | None) -> dict:out: dict = {}for s in servers or []:url = (s or {}).get("url")+ name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")+ if not url and (s or {}).get("command"):+ # A stdio server (a plugin's, through its launcher): hermes's own command/args shape.+ out[name] = {"command": str(s["command"]), "args": [str(a) for a in (s.get("args") or [])]}+ continueif not url:continue- name = _mcp_name((s or {}).get("name") or (s or {}).get("id") or "mcp")entry: dict = {"url": url}if ((s or {}).get("transport") or "").lower() == "sse":entry["transport"] = "sse"@@ -3572,9 +3742,15 @@ def _cline_settings(home: pathlib.Path, base_url: str, api_key: str, model: str,if not isinstance(sv, dict) or sv.get("enabled") is False:continueurl = (sv.get("url") or "").strip()- if not url:- continue # cline's file also takes stdio; the harness config is URL-onlyname = _skill_dir_name(sv.get("name") or sv.get("id") or f"server{i}")+ if not url and sv.get("command"):+ # A stdio server (a plugin's, through its launcher), in the same transport-object+ # shape 3.0.60 writes for `mcp install` of a local server.+ servers[name] = {"transport": {"type": "stdio", "command": str(sv["command"]),+ "args": [str(a) for a in (sv.get("args") or [])]}}+ continue+ if not url:+ continueentry: dict = {"transport": {"type": "streamableHttp", "url": url}}hdrs = sv.get("headers")if isinstance(hdrs, dict) and hdrs:@@ -5652,8 +5828,18 @@ def turn(req: TurnReq, identifier: str = "") -> dict:# image-mounted (there is no _mount_builtin_skills), and the gateway already drops suppress markers# from req.skills, so this filter is a parity guard: never write a skill whose name is suppressed._skip = set(req.skills_suppressed or [])+ # Installed plugin packages, whole, at their roots; then every stdio server a plugin declares+ # becomes a launcher every backend writer below already knows how to hand to its CLI.+ plugin_roots = _write_plugins(cwd, req.plugins)+ req.mcp_servers = _plugin_launchers(cwd, req.mcp_servers)+ # A package that is also a Claude Code plugin reaches the claude CLI whole through+ # --plugin-dir, which loads its skills/ itself; folding those skills into the skills+ # directory too would offer each one twice.+ claude_native = {pathlib.Path(d).name for d in plugin_roots+ if (pathlib.Path(d) / ".claude-plugin" / "plugin.json").is_file()} if backend == "claude" else set()installed_skills = _write_skills(- cwd, [s for s in (req.skills or []) if (s.get("name") or s.get("id")) not in _skip], backend,+ cwd, [s for s in (req.skills or []) if (s.get("name") or s.get("id")) not in _skip+ and _mcp_name(str(s.get("plugin") or "")) not in claude_native], backend,) # materialize enabled skills for this backend (minus suppressed built-ins)# Seed the agent's instruction file (AGENTS.md/CLAUDE.md) from the harness doc + installed skills.# The model's system prompt stays the CLI default; persistent instructions live in this file.@@ -5779,7 +5965,10 @@ def turn(req: TurnReq, identifier: str = "") -> dict:skills_dir=skills_dir, tools_disabled=req.tools_disabled)else:mcp_config = _write_mcp_config_claude(cwd, req.mcp_servers)- plugin_dirs = _write_plugins(cwd, req.plugins)+ # Only a package that is ALSO a Claude Code plugin gets --plugin-dir; an Agent Plugins+ # package without .claude-plugin/plugin.json would make the CLI refuse the flag.+ plugin_dirs = [d for d in plugin_roots+ if (pathlib.Path(d) / ".claude-plugin" / "plugin.json").is_file()]cmd = _build_claude(req.provider, auth, model, req.prompt, req.max_turns, cwd, env,resume_session_id=req.resume_session_id, mcp_config=mcp_config,disallowed_tools=req.tools_disabled, partial=bool(req.partial_messages),diff --git a/runner/tests/test_uhp_plugins.py b/runner/tests/test_uhp_plugins.pynew file mode 100644index 00000000..f938cce4--- /dev/null+++ b/runner/tests/test_uhp_plugins.py@@ -0,0 +1,134 @@+"""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"diff --git a/ui/package-lock.json b/ui/package-lock.jsonindex 74596d53..63d99edb 100644--- a/ui/package-lock.json+++ b/ui/package-lock.json@@ -34,6 +34,7 @@"echarts": "^5.6.0","echarts-for-react": "^3.0.6","emoji-mart": "^5.6.0",+ "fflate": "^0.8.3","framer-motion": "^12.23.16","highlight.js": "^11.11.1","iconify-icon": "^3.0.2",@@ -7248,6 +7249,12 @@}}},+ "node_modules/fflate": {+ "version": "0.8.3",+ "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.3.tgz",+ "integrity": "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==",+ "license": "MIT"+ },"node_modules/file-entry-cache": {"version": "8.0.0","resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",diff --git a/ui/package.json b/ui/package.jsonindex e2d4f8b5..0da203a9 100644--- a/ui/package.json+++ b/ui/package.json@@ -43,6 +43,7 @@"echarts": "^5.6.0","echarts-for-react": "^3.0.6","emoji-mart": "^5.6.0",+ "fflate": "^0.8.3","framer-motion": "^12.23.16","highlight.js": "^11.11.1","iconify-icon": "^3.0.2",diff --git a/ui/src/app/revamp.css b/ui/src/app/revamp.cssindex 6c43b928..10baa2d3 100644--- a/ui/src/app/revamp.css+++ b/ui/src/app/revamp.css@@ -2009,3 +2009,45 @@ button.creq-srcstat.on b { color: var(--accent); }when the record actually knows the cause. The badge above it deliberately no longer names acause, because it used to name the wrong one for interrupted turns. */.wbx-incomplete-why { font-size: 12.5px; color: var(--faint, #6e6760); margin: 4px 0 0 2px; }++/* ── Plugins on the Harness page: one row per installed package, the same row grammar as the+ Tools and Skills sections, expandable to what the server derived from it ─────────────── */+.plugin-head{flex-wrap:wrap}+.plugin-row .capability-copy{min-width:0}+.plugin-row .capability-copy strong,.plugin-row .capability-copy span{overflow-wrap:anywhere}+.plugin-row.is-off .capability-copy{opacity:.62}+/* The four actions sit two per row beside the copy so the description keeps its width. The row+ follows the width of the list it is in, not the viewport: the settings panel is narrow on a+ 1024 screen too. Under 680px the actions drop below the copy, two per row; under 340px (a phone) one per row. */+.plugin-list{container-type:inline-size}+.plugin-row .capability-actions{display:grid;grid-template-columns:repeat(2,minmax(104px,max-content));gap:6px 8px;justify-content:end;align-self:start;margin-top:2px}+.plugin-row .capability-actions .button,.plugin-row .capability-actions .toggle-button{width:100%;min-width:0;justify-content:center}+@container (max-width:680px){+ .plugin-row{grid-template-columns:30px minmax(0,1fr)}+ .plugin-row .capability-actions{grid-column:2;justify-content:start;margin-top:8px}+ .plugin-details{grid-column:1 / -1}+}+@container (max-width:340px){+ .plugin-row .capability-actions{grid-template-columns:1fr;width:100%}+ .plugin-group li{grid-template-columns:1fr}+}+.plugin-row .capability-copy .plugin-title{display:flex;align-items:center;gap:10px;min-width:0;flex-wrap:wrap} /* outranks the row's block strong, so the gap applies */+.plugin-row .capability-copy .plugin-version{display:inline-flex;align-items:center;width:auto;margin:0;padding:1px 7px;border-radius:999px;+ border:1px solid var(--line,#e7e7eb);background:rgba(255,255,255,.72);font:500 10.5px/1.6 var(--mono,ui-monospace,monospace);color:var(--muted,#6f6f78);white-space:nowrap}+.plugin-row .capability-copy .plugin-desc{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;color:var(--muted,#6f6f78);font-size:12px;line-height:1.45}+.plugin-row .capability-copy .plugin-facts{display:block;margin-top:4px;font-size:11.5px;color:var(--faint,#9696a0)}+.plugin-warn{font-style:normal;color:#b45309}+.plugin-details{grid-column:2 / -1;margin:6px 0 2px;padding:10px 12px;display:grid;gap:12px;border-radius:9px;background:rgba(255,255,255,.72);border:1px solid var(--line,#e7e7eb);font-size:12.5px;color:var(--muted,#6f6f78)}+.plugin-group b{display:block;margin-bottom:6px;font-size:10.5px;font-weight:660;letter-spacing:.06em;text-transform:uppercase;color:var(--faint,#9696a0)}+.plugin-group ul{margin:0;padding:0;list-style:none;display:grid;gap:6px}+.plugin-group li{display:grid;grid-template-columns:minmax(120px,max-content) minmax(0,1fr);gap:10px;align-items:baseline}+.plugin-group li code{font:500 12px/1.45 var(--mono,ui-monospace,monospace);color:var(--ink,#111317);word-break:break-all}+.plugin-group li span{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;line-height:1.45}+.plugin-group.is-warn code{color:#b45309}+.plugin-note{margin:8px 0 0;padding:9px 12px;border-radius:8px;font-size:13px;line-height:1.45;overflow-wrap:anywhere}+.plugin-note.is-info{background:var(--subtle,#f7f7f9);color:var(--muted,#6f6f78)}+.plugin-note.is-error{background:#fef2f2;color:#991b1b}+@media (max-width:480px){+ .plugin-head{display:grid;grid-template-columns:1fr;gap:8px}+ .plugin-head .button{width:100%;justify-content:center}+}diff --git a/ui/src/components/ApiReference.tsx b/ui/src/components/ApiReference.tsxindex 0dc7afc4..1944895c 100644--- a/ui/src/components/ApiReference.tsx+++ b/ui/src/components/ApiReference.tsx@@ -295,6 +295,7 @@ curl "${mgmtBase}/sessions/{session_id}/files?changed=true" \\<Param name="system_prompt" type="string">The agent's instructions (written into its workspace as AGENTS.md / CLAUDE.md).</Param><Param name="mcp_servers" type="array">Tool connections: <code>{`{name, url, auth?, enabled}`}</code>. For <code>auth</code>, pass a secrets ref (below) or a <code>$headers.{Name}</code> per-request reference.</Param><Param name="skills" type="array"><code>{`{name, files:[{path, content|content_b64}]}`}</code>, a bundle MUST include a <code>SKILL.md</code>; invalid bundles are rejected with 400. Skills can be whole folders: <code>path</code> is the file's relative path inside the skill (nested layouts like <code>guides/SKILL.md</code> install as-is); the root <code>SKILL.md</code> needs YAML frontmatter (<code>name</code>, <code>description</code>). Bundles over ~48 KB are offloaded server-side and the saved agent returns that skill as <code>{`{name, enabled, blob}`}</code> with no <code>files</code>, normal; the folder still mounts into every run. On later updates pass such entries back unchanged; only include <code>files</code> when changing content.</Param>+ <Param name="plugins" type="array">Packages in the Agent Plugins format: <code>{`{files:[{path, content|content_b64}], enabled?}`}</code>, each with a <code>plugin.json</code> at its root, tools in <code>mcp.json</code>, Skills under <code>skills/</code>. The saved agent returns each as <code>{`{name, enabled, blob, manifest, mcpServers, skills, skipped}`}</code>; pass such entries back unchanged, and include <code>files</code> only for a new or changed package.</Param><Param name="disabled_tools" type="array">Inherited/built-in tool names to disable.</Param><Param name="additional_headers" type="array">Header NAMES your product passes per request for app-level auth (see Additional headers above).</Param><Param name="max_step" type="integer">Default agent step budget (default 400).</Param>@@ -321,6 +322,21 @@ curl "${mgmtBase}/sessions/{session_id}/files?changed=true" \\<code> id</code> or <code>name</code>; returns <code>{`{ id, name, files: [{path, content|content_b64}] }`}</code>.</p></Endpoint>+ <Endpoint method="GET" path="/v1/harnesses/{id}/plugins/{name}/files">+ <p className="hr-meta">The complete package of one installed plugin, byte for byte. A plugin is a+ folder in the Agent Plugins format (<code>plugin.json</code> at its root, tools in+ <code> mcp.json</code>, Skills under <code>skills/</code>), sent on create or update as+ <code>{`plugins: [{ files: [{path, content|content_b64}] }]`}</code>. The record you read back carries+ what the server derived from it: <code>manifest</code>, <code>mcpServers</code>, <code>skills</code>+ and <code>skipped</code>, plus a <code>blob</code> handle that round-trips on PUT.</p>+ </Endpoint>++ <Endpoint method="GET" path="/v1/harnesses/{id}/plugin">+ <p className="hr-meta">This agent's own tools and Skills as an Agent Plugins package, ready to+ send to another agent's <code>plugins</code> or to write to disk for any client that reads the+ format. Credentials are never included; each omission is listed in <code>skipped</code>.</p>+ </Endpoint>+<Endpoint method="GET" path="/v1/models"><p className="hr-meta">The current model catalog per engine, each with its default. Build modelpickers from this, don't hardcode model names. The map is keyed by <b>backend</b>, notdiff --git a/ui/src/components/HarnessEditors.tsx b/ui/src/components/HarnessEditors.tsxindex a240a9a0..5b0de655 100644--- a/ui/src/components/HarnessEditors.tsx+++ b/ui/src/components/HarnessEditors.tsx@@ -31,7 +31,7 @@ export type SkillFile = { path: string; content?: string; content_b64?: string }// anything else (binaries like .exe/.png, or text with embedded NULs) is base64-encoded into// `content_b64`. This keeps binary bytes intact AND keeps NUL out of any JSON string, a literal// in skill content otherwise aborts the harness PUT at the Postgres layer.-async function readSkillUpload(file: File, path: string): Promise<SkillFile> {+export async function readSkillUpload(file: File, path: string): Promise<SkillFile> {try {const bytes = new Uint8Array(await file.arrayBuffer());try {diff --git a/ui/src/components/HarnessSettings.tsx b/ui/src/components/HarnessSettings.tsxindex e319e3be..060585ae 100644--- a/ui/src/components/HarnessSettings.tsx+++ b/ui/src/components/HarnessSettings.tsx@@ -3,16 +3,17 @@// IA review): General → Default model → Agent instructions → Tools → Skills → Runtime limits →// Request headers, one Save. Built-in harnesses render read-only with a Clone action.// Reuses the battle-tested SkillEditor + McpModal from the workbench.-import { useEffect, useMemo, useState } from 'react';+import { useEffect, useMemo, useRef, useState } from 'react';+import { zipSync, strToU8 } from 'fflate';import { SkelPage } from '@/components/Skel';import { useRouter } from 'next/navigation';import {- OOB, oobById, oobDefaultModel, oobModels, useModelCatalog, modelAvailable, modelAvailability, availabilityNote, useBases, getCustom, saveCustom, deleteCustom, createCustom, getSkillFiles, storeMcpSecret,- type CustomHarness, type OobHarness,+ OOB, oobById, oobDefaultModel, oobModels, useModelCatalog, modelAvailable, modelAvailability, availabilityNote, useBases, getCustom, saveCustom, deleteCustom, createCustom, getSkillFiles, storeMcpSecret, pluginSchemas,+ type CustomHarness, type OobHarness, type HarnessPlugin, getPluginFiles,} from '@/lib/harness';import { HarnessLogo } from '@/components/HarnessLogo';import { CopyId } from '@/components/CopyId';-import { SkillEditor, McpModal, type McpServer } from '@/components/HarnessEditors';+import { SkillEditor, McpModal, readSkillUpload, type McpServer } from '@/components/HarnessEditors';import { fetchTraceWindow, statsFor, p95Of, avgCreditsOf, timeAgo, type TraceCard } from '@/lib/revamp-data';// Self-hosted only: publish a custom harness (instructions, model, skills, MCP wiring) to a// hosted workspace. Hidden and inert on hosted builds.@@ -50,6 +51,76 @@ export function HarnessSettings({ id, embedded = false, onNavigate }: {}, [id]);// Draft of a NEW skill being created in the SkillEditor popup (name edited in the same popup).const [newSkill, setNewSkill] = useState<{ name: string } | null>(null);+ // Plugins: which row is expanded (by name, so removing another row cannot move it), the folder+ // picker, the export in flight, and a notice that belongs to this section rather than to Save.+ const [pluginOpen, setPluginOpen] = useState<string | null>(null);+ const [pluginBusy, setPluginBusy] = useState(false);+ const [pluginNote, setPluginNote] = useState<{ kind: 'error' | 'info'; text: string } | null>(null);+ const pluginDirRef = useRef<HTMLInputElement>(null);+ // The gateway refuses a package over this size (its _PLUGIN_PACKAGE_MAX); refusing here first+ // spares reading a 30 MB folder into the draft only to be told no on Save.+ const PLUGIN_PACKAGE_MAX = 16 * 1024 * 1024;+ // A folder picked as a plugin package: every file under it, paths relative to the folder itself,+ // and the manifest read up front so the row can name what was picked before it is saved. The+ // server does the real validation on save and answers with what it derived and what it skipped.+ async function installPluginFolder(list: FileList | null) {+ if (!list || !list.length || !draft) return;+ setPluginBusy(true); setPluginNote(null);+ try {+ let total = 0;+ for (let i = 0; i < list.length; i++) total += list[i].size;+ if (total > PLUGIN_PACKAGE_MAX) throw new Error(`That folder is ${fmtMb(total)}; a plugin package can be at most ${fmtMb(PLUGIN_PACKAGE_MAX)}.`);+ const files: NonNullable<HarnessPlugin['files']> = [];+ for (let i = 0; i < list.length; i++) {+ const f = list[i];+ const rel = (f as File & { webkitRelativePath?: string }).webkitRelativePath || f.name;+ const path = rel.includes('/') ? rel.slice(rel.indexOf('/') + 1) : rel; // drop the picked folder's own name+ if (!path || path.split('/').some((seg) => seg === 'node_modules' || seg === '.git')) continue;+ files.push(await readSkillUpload(f, path));+ }+ const manifestFile = files.find((f) => f.path === 'plugin.json');+ if (!manifestFile || manifestFile.content === undefined) throw new Error('That folder has no plugin.json at its root, so it is not a plugin package.');+ let manifest: (HarnessPlugin['manifest'] & { $schema?: string }) = {};+ try { manifest = JSON.parse(manifestFile.content) as typeof manifest; } catch { throw new Error('plugin.json is not valid JSON.'); }+ const name = String(manifest?.name || '');+ if (!name) throw new Error('plugin.json names no plugin.');+ if ((draft.plugins || []).some((p) => p.name === name)) throw new Error(`A plugin named ${name} is already installed on this Harness.`);+ // The server says which package versions it installs; a package for another one is+ // refused on Save, so say so now, while the folder is still in front of the person.+ const schemas = await pluginSchemas();+ if (schemas.length && !schemas.includes(String(manifest.$schema || ''))) {+ throw new Error(manifest.$schema+ ? `This package targets ${manifest.$schema}, which this server does not install (it installs ${schemas.join(', ')}).`+ : 'plugin.json names no $schema, which every package must.');+ }+ upd({ plugins: [...(draft.plugins || []), { name, enabled: true, files, manifest }] });+ setPluginNote({ kind: 'info', text: `${name} is added; it installs when you save the Harness.` });+ } catch (e) { setPluginNote({ kind: 'error', text: e instanceof Error ? e.message : String(e) }); }+ finally { setPluginBusy(false); if (pluginDirRef.current) pluginDirRef.current.value = ''; }+ }+ const fmtMb = (n: number) => `${(n / 1048576).toFixed(n < 10485760 ? 1 : 0)} MB`;+ // One installed plugin, byte for byte as the server holds it, zipped in the browser.+ async function downloadInstalledPlugin(p: HarnessPlugin) {+ if (!draft?.id || pluginBusy) return;+ setPluginBusy(true); setPluginNote(null);+ try {+ const files = await getPluginFiles(draft.id, p.name);+ const entries: Record<string, Uint8Array> = {};+ for (const f of files) {+ entries[f.path] = f.content_b64 !== undefined+ ? Uint8Array.from(atob(f.content_b64), (c) => c.charCodeAt(0))+ : strToU8(f.content || '');+ }+ const fname = `${p.name}${p.manifest?.version ? '-' + p.manifest.version : ''}.zip`;+ const blob = new Blob([zipSync(entries) as BlobPart], { type: 'application/zip' });+ const a = document.createElement('a');+ a.href = URL.createObjectURL(blob); a.download = fname;+ document.body.appendChild(a); a.click(); a.remove();+ setTimeout(() => URL.revokeObjectURL(a.href), 1000);+ setPluginNote({ kind: 'info', text: `Downloaded ${fname}: ${files.length} ${files.length === 1 ? 'file' : 'files'}, the package as installed.` });+ } catch (e) { setPluginNote({ kind: 'error', text: e instanceof Error ? e.message : String(e) }); }+ finally { setPluginBusy(false); }+ }const [cards, setCards] = useState<TraceCard[]>([]);useEffect(() => {@@ -82,6 +153,14 @@ export function HarnessSettings({ id, embedded = false, onNavigate }: {try {const s = await saveCustom(draft);setSaved(s); setDraft(s);+ // A plugin the server installed with parts it could not load is only visible on this+ // page; leaving now would hide it. Stay, open that row, and say so.+ const partial = (s.plugins || []).filter((p) => (p.skipped || []).length);+ if (partial.length) {+ setPluginOpen(partial[0].name);+ setPluginNote({ kind: 'info', text: `Saved. ${partial.map((p) => `${p.name}: ${(p.skipped || []).length} part${(p.skipped || []).length === 1 ? '' : 's'} not loaded`).join('; ')}. Open Details to see which.` });+ return;+ }// After a successful save, jump to Tasks with THIS harness selected so the user can// immediately run a task on the config they just changed.go('tasks');@@ -301,6 +380,77 @@ export function HarnessSettings({ id, embedded = false, onNavigate }: {</div></section>+ <section className="form-section">+ <div><h3>Plugins</h3><p>A plugin is a package of tools and Skills in the Agent Plugins format. What it brings joins this Harness's own tools and Skills on every Task.</p></div>+ <div className="field-stack">+ <div className="section-actions plugin-head"><strong>{(draft?.plugins || []).length} installed {(draft?.plugins || []).length === 1 ? 'plugin' : 'plugins'}</strong>+ {!readOnly && <button className="button small" type="button" disabled={pluginBusy} onClick={() => pluginDirRef.current?.click()}>+ <iconify-icon icon="tabler:plus"></iconify-icon>Install from folder</button>}+ <input ref={pluginDirRef} type="file" hidden onChange={(e) => void installPluginFolder(e.target.files)}+ {...({ webkitdirectory: '', directory: '' } as Record<string, string>)} />+ </div>+ {pluginNote && <div className={'plugin-note is-' + pluginNote.kind} role={pluginNote.kind === 'error' ? 'alert' : 'status'}>{pluginNote.text}</div>}+ <div className="capability-list plugin-list">+ {(draft?.plugins || []).map((p, idx) => {+ const servers = p.mcpServers || [], skls = p.skills || [], skipped = p.skipped || [];+ const pending = Boolean(p.files && p.files.length && !p.blob);+ const m = p.manifest || {};+ const open = pluginOpen === p.name;+ const facts = pending+ ? ['Installs when you save the Harness']+ : [`${skls.length} ${skls.length === 1 ? 'Skill' : 'Skills'}`, `${servers.length} ${servers.length === 1 ? 'tool' : 'tools'}`,+ ...(m.author?.name ? [`by ${m.author.name}`] : []), ...(m.license ? [m.license] : [])];+ return (+ <div key={p.name} className={'capability-row plugin-row' + (open ? ' is-open' : '') + (p.enabled === false ? ' is-off' : '')}>+ <span className="capability-icon"><iconify-icon icon="tabler:puzzle"></iconify-icon></span>+ <div className="capability-copy">+ <strong className="plugin-title">{p.name}{m.version ? <span className="plugin-version">v{m.version}</span> : null}</strong>+ <span className="plugin-desc" title={m.description || undefined}>{m.description || 'Agent Plugins package'}</span>+ <span className="plugin-facts">{facts.join(' \u00b7 ')}+ {!pending && skipped.length > 0 && <em className="plugin-warn">{' \u00b7 '}{skipped.length} not loaded</em>}</span>+ </div>+ <div className="capability-actions">+ {!pending && <button className="button quiet small" type="button" aria-expanded={open} onClick={() => setPluginOpen(open ? null : p.name)}>+ <iconify-icon icon={open ? 'tabler:chevron-up' : 'tabler:chevron-down'}></iconify-icon>{open ? 'Hide' : 'Details'}</button>}+ {!pending && draft?.id && <button className="button quiet small" type="button" disabled={pluginBusy} title="This package, as installed, as a zip"+ onClick={() => void downloadInstalledPlugin(p)}><iconify-icon icon="tabler:download"></iconify-icon>Download</button>}+ {!readOnly && <button className="button quiet small" type="button" onClick={() => upd({ plugins: (draft?.plugins || []).filter((_, k) => k !== idx) })}>Remove</button>}+ <button className="toggle-button" type="button" disabled={readOnly} aria-pressed={p.enabled !== false}+ onClick={() => upd({ plugins: (draft?.plugins || []).map((x, k) => (k === idx ? { ...x, enabled: !(x.enabled !== false) } : x)) })}>+ {p.enabled !== false ? 'Enabled' : 'Disabled'}</button>+ </div>+ {open && !pending && (+ <div className="plugin-details">+ {skls.length > 0 && <div className="plugin-group"><b>Skills</b>+ <ul>{skls.map((s) => <li key={s.name}><code>{s.name}</code>{s.description ? <span title={s.description}>{s.description}</span> : null}</li>)}</ul></div>}+ {servers.length > 0 && <div className="plugin-group"><b>Tools</b>+ <ul>{servers.map((s) => <li key={s.name}><code>{s.name}</code><span>{s.transport === 'stdio' ? `runs ${s.command}${(s.args || []).length ? ' ' + (s.args || []).join(' ') : ''}` : s.url}</span></li>)}</ul></div>}+ {skipped.length > 0 && <div className="plugin-group is-warn"><b>Not loaded</b>+ <ul>{skipped.map((s) => <li key={s.path}><code>{s.path}</code><span>{s.reason}</span></li>)}</ul></div>}+ {(m.homepage || m.repository || (m.keywords || []).length > 0) && (+ <div className="plugin-group"><b>About</b>+ <ul>{m.homepage && <li><a href={m.homepage} target="_blank" rel="noreferrer">Homepage</a></li>}+ {m.repository && <li><a href={m.repository} target="_blank" rel="noreferrer">Source</a></li>}+ {(m.keywords || []).length > 0 && <li><span>{(m.keywords || []).join(', ')}</span></li>}</ul></div>+ )}+ </div>+ )}+ </div>+ );+ })}+ {(draft?.plugins || []).length === 0 && (+ <div className="capability-row">+ <span className="capability-icon"><iconify-icon icon="tabler:puzzle"></iconify-icon></span>+ <div className="capability-copy"><strong>No plugins installed</strong>+ <span>{readOnly+ ? 'A built-in Harness carries no plugins. Create a Harness of your own to install packages of tools and Skills.'+ : 'A plugin is a folder with a plugin.json at its root, tools in mcp.json and Skills under skills. Install one to add all of it at once.'}</span></div>+ </div>+ )}+ </div>+ </div>+ </section>+<section className="form-section"><div><h3>Runtime limits</h3><p>Stop Tasks that run longer or take more agent steps than expected.</p></div><div className="field-stack">diff --git a/ui/src/lib/harness.ts b/ui/src/lib/harness.tsindex 8de15518..8dc16fd4 100644--- a/ui/src/lib/harness.ts+++ b/ui/src/lib/harness.ts@@ -49,9 +49,24 @@ export interface CustomHarness {maxStep?: number | null; // default agent step budget per turn (blank = 40)timeoutSeconds?: number | null; // default per-turn wall-clock cap (blank = server default)additionalHeaders?: string[]; // declared header NAMES callers pass per request (app-level auth)+ // Installed plugins (UHP Plugins chapter). The server derives manifest, mcpServers, skills and+ // skipped from the package on every save; a saved plugin round-trips as {name, enabled, blob}+ // plus those derived fields, and a freshly picked one carries its `files` until it is saved.+ plugins?: HarnessPlugin[];createdAt: number;}+export type HarnessPlugin = {+ name: string; enabled?: boolean; blob?: string;+ files?: { path: string; content?: string; content_b64?: string }[];+ manifest?: { name?: string; version?: string; description?: string; license?: string;+ homepage?: string; repository?: string; keywords?: string[];+ author?: { name?: string; email?: string; url?: string } };+ mcpServers?: { name: string; transport?: string; url?: string; command?: string; args?: string[] }[];+ skills?: { name: string; description?: string }[];+ skipped?: { path: string; reason: string }[];+};+export const OOB: OobHarness[] = [{ id: 'codex', name: 'Codex', version: 'v1.0.1', backend: 'codex', status: 'ready',models: ['gpt-6-astra', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.2'], defaultModel: 'gpt-5.5', moreModels: 0,@@ -330,6 +345,7 @@ function harnessBody(input: Partial<CustomHarness> & { name: string; base: strinmcp_servers: input.mcpServers || [],skills: input.skills || [],disabled_tools: input.disabledTools || [],+ plugins: input.plugins || [],max_step: input.maxStep || null,timeout_seconds: input.timeoutSeconds || null,additional_headers: input.additionalHeaders || [],@@ -373,6 +389,32 @@ export async function deleteCustom(id: string): Promise<void> {/** Full files of one skill on a harness, resolving the server-side blob offload, used to* hydrate a folder skill for editing when the record only carries {name, enabled, blob}. */+let _pluginSchemas: Promise<string[]> | null = null;+/** The Agent Plugins manifest schemas this server installs, from its discovery document; empty+ * when the server reports no plugin support (the Console then leaves the check to Save). */+export function pluginSchemas(): Promise<string[]> {+ if (!_pluginSchemas) {+ _pluginSchemas = gw<{ capabilities?: Record<string, boolean>; plugin_schemas?: string[] }>('GET', '/v1/uhp')+ .then((d) => (d.capabilities?.plugins ? (d.plugin_schemas || []) : []))+ .catch(() => []);+ }+ return _pluginSchemas;+}++/** The complete package of one installed plugin, byte for byte (UHP Plugins §3.1). */+export async function getPluginFiles(harnessId: string, name: string):+ Promise<{ path: string; content?: string; content_b64?: string }[]> {+ const r = await gw<{ files: { path: string; content?: string; content_b64?: string }[] }>(+ 'GET', `/v1/harnesses/${encodeURIComponent(harnessId)}/plugins/${encodeURIComponent(name)}/files`);+ return r.files || [];+}++/** This Harness's own tools and Skills as an Agent Plugins package (UHP Plugins §5). Credentials+ * are never in it; each omission is listed in `skipped`. */+export async function exportPlugin(harnessId: string): Promise<HarnessPlugin> {+ return gw<HarnessPlugin>('GET', `/v1/harnesses/${encodeURIComponent(harnessId)}/plugin`);+}+export async function getSkillFiles(harnessId: string, skillId: string):Promise<{ path: string; content?: string; content_b64?: string }[]> {const r = await gw<{ files: { path: string; content?: string; content_b64?: string }[] }>(