Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

UHP Harness Plugins

UHP 2026-09-12 adds an optional Harness Plugins sub-protocol that installs a portable Agent Plugins package into a hosted harness without redefining the package format.

Page reviewed 4 Oct 2026 Source and review policy

Introduced in UHP: 2026-09-12Agent Plugins: 1.0.0

What changed

Review a package before binding it to execution

Installing a package and authorizing its runtime effects are separate decisions. Begin with discovery: require plugins and a supported plugin_schemas entry, then inspect the actual package.

Package review	Runtime review
Validate root `plugin.json` against the advertised manifest schema	Confirm the configured harness can materialize the selected components
Identify bundled skills, instructions and `mcp.json` entries	Treat stdio servers as executable processes inside the sandbox
Compare package-derived components with direct harness settings	Check effective tool/skill composition rather than only the source manifest
Inspect export contents and omission records	Keep credentials out of the exported installable package

A successful package upload does not demonstrate a working MCP process, a granted permission or an equivalent implementation on another backend. Test a minimal authorized workflow after binding, and preserve the derived manifest, mcpServers, skills and skipped evidence so failures can be diagnosed.

Use Agent Plugins for the reused packaging contract, tool-surface coherence when configured tools differ from model-visible tools, and security for admission and execution boundaries. The historical introduction results below remain at their original suite revisions.

UHP 2026-09-12 adds Harness Plugins as an optional protocol surface. A UHP plugin is not a new UHP-specific package format: it is an Agent Plugins 1.0.0 package containing a root plugin.json, optional mcp.json, and optional Agent Skills under skills/.

UHP defines the layer around that package: how it is attached to a harness, transported and stored by a server, exposed through discovery, materialized for execution, exported again, and tested for conformance.

Agent Skills     SKILL.md + skill folder       one portable skill
Agent Plugins    plugin.json + mcp.json + ...  portable extension package
UHP Plugins      harness binding + HTTP API    package installed into a hosted harness

This is an additive change from 2026-08-11. Existing direct harness mcpServers and skills retain their previous shape and meaning. A server that does not implement Harness Plugins can remain conformant; it reports the plugins capability as unsupported and the plugin-specific conformance checks skip rather than pass.

Harness object and derived state

The harness object gains a plugins array. The package itself is supplied through files or a server-side blob handle. The server derives the package-facing state instead of trusting client copies:

manifest from validated plugin.json;
mcpServers from mcp.json;
skills from immediate skills/<name>/SKILL.md children;
skipped entries for isolated components that cannot be loaded.

The package is the source of truth. Editing a derived mcpServers or skills projection does not rewrite the plugin package.

Two plugins with the same manifest name in one harness are refused. A rejected plugin write must leave the harness unchanged.

Why stdio MCP appears here

Direct UHP harness mcpServers remain remote-server configuration. Harness Plugins additionally supports Agent Plugins stdio MCP entries because the plugin provides the filesystem roots and files a subprocess needs.

The mapping is explicit:

Agent Plugins MCP type	UHP plugin transport
`streamable-http`	`http`
`sse`	`sse`
`stdio`	`stdio`

${PLUGIN_ROOT} and ${PLUGIN_DATA} remain package placeholders. A UHP server reports them as written and expands them only inside the execution environment where the plugin is materialized.

Effective harness composition

At execution time the effective configuration combines:

enabled direct harness MCP servers;
MCP servers derived from every enabled plugin;
enabled direct harness skills;
skills derived from every enabled plugin.

The direct fields are not rewritten to contain plugin-derived components. That preserves read/modify/write round trips and prevents a plugin server or skill from being duplicated into the harness’s direct configuration.

disabledTools continues to apply across the effective tool set.

Export is part of the contract

UHP 2026-09-12 adds harness export as an installable Agent Plugins package. Export is deliberately lossy where carrying a value would be unsafe or non-portable: credentials are omitted and the omission must be recorded rather than silently disappearing.

This gives the new sub-protocol a two-way interoperability boundary:

Agent Plugin package → UHP harness → exported Agent Plugin package

That does not mean UHP now owns the Agent Plugins format. Agent Plugins remains authoritative for package structure and component validation; UHP owns the hosted-harness binding and transport semantics.

Capability discovery and errors

A server that implements the sub-protocol advertises the plugins capability and supported plugin_schemas. The version adds five plugin-specific error codes:

plugin_invalid
unsupported_plugin_schema
unsupported_transport
plugin_conflict
plugin_not_found

The protocol also adds a plugin-files endpoint and a harness-export endpoint so clients can retrieve a stored package and produce a portable package from a configured harness.

Security boundary

Plugins are third-party code and configuration. The new Security section requires hosts to treat them accordingly. In particular, a plugin’s stdio MCP process executes inside the agent sandbox rather than becoming an unsandboxed host process merely because its command was packaged with the plugin.

Agent Plugins 1.0.0 itself does not define portable OAuth or credential-reference fields. UHP export therefore cannot treat visible package headers or environment variables as a portable secret channel.

Conformance impact at introduction

The official suite advances to package 2026.9.12 and 74 checks:

Core: 40
Extended: +8
Full: +25
Full total: 74

The new P-01 through P-10 checks cover plugin package round trips, derivation, refusal behavior and export. They are Full-class but capability-gated. If a server reports plugins: false, those checks skip; a skip is never counted as a pass.

HarnessRouter v0.17.2 ships PR #175, serving UHP 2026-09-12 alongside 2026-08-11, advertising plugins: true and Agent Plugins schema 1.0.0, and implementing the Harness Plugins path across the gateway, runner and console. PR #175 records a live Full run of the current package at 74/74 passed, 0 failed, 0 skipped, 0 errored, then records the same 74/74 result again after adversarial review and redeployment.

Post-release PR #177 first closes the repository’s stale checked-in README reference block. The dedicated conformance-remeasure workflow reruns the Full suite against the live reference instance and updates protocol/conformance/README.md to 74/74 passed, 0 failed, 0 skipped, 0 errored — CONFORMANT, UHP 2026-09-12 (full). The workflow does not reach PR creation when the conformance CLI reports a FAIL or ERROR.

PR #178 then runs the generic conformance-measure workflow against HarnessRouter Community Edition 0.17.2 and checks in protocol/conformance/reports/harnessrouter-ce/2026-09-15T0046Z-full.json. That structured report records protocol/suite 2026-09-12 / 2026.9.12, class Full and 74 pass · 0 fail · 0 skip · 0 error.

PR #179 closes the implementation-list metadata drift: the official HarnessRouter CE card says UHP 2026-09-12, and a measured card’s displayed UHP version is derived from its newest checked report just as its measured level/badge already is.

Post-release PR #180, merged as aecfd7dd27acfdd0687ee0cb035675b5ba8ddf3f, removes a false gateway admission restriction: Pi and DeepSeek Harness (dsh) are no longer rejected merely because a plugin contains a stdio MCP server. It also teaches the Pi and dsh config writers the native launcher shapes their MCP clients accept. That merge established admission/writer capability, but later upstream work found that the dsh job builder still discarded command-only MCP entries before a hosted turn.

PR #181, merged as 95f56696582bb668c1d70c67bfac7ebd8322c8dc, then corrects transport fidelity across backend-native MCP clients. Gemini/Qwen encode SSE with url and Streamable HTTP with httpUrl; Cline and Oh My Pi receive their own explicit transport types. At that revision, Codex, dsh and Goose lack native SSE in the pinned client surfaces, so HarnessRouter records an SSE component in the plugin’s indexed skipped state rather than silently omitting or mis-encoding it. The dsh stdio row also receives a concrete cwd because its client schema does not tolerate the previous empty default.

PR #182, merged as ab6212e727a311fc54885e577f16317775d0cc18, closes the remaining dsh stdio execution gap. _build_dsh still filtered job MCP servers using the old URL-only condition, so the stdio row added by PR #180 never reached the compose patch on a hosted dsh turn. The filter now retains a server with either a URL or a command, and focused runner coverage pins that behavior.

PR #185, merged as d24b665910c3dd8ec52bf6ed19e86e105f7701b8, supersedes PR #181’s transport-specific SSE skip for Codex, dsh and Goose. Those clients still do not gain native SSE. Instead, the runner gives them mcp_bridge.py as a local stdio MCP server; the bridge connects to the remote server over SSE and forwards MCP tools, resources and prompts, including structured tool content. The remote URL and request headers are carried in the launcher’s environment rather than its command line. HarnessRouter therefore installs an SSE plugin server on every base while preserving the actual backend-client transport boundary.

PR #188, merged as 022179214a2a6be509a502229574ea118d9698ee, closes the Codex startup race around that bridge. Codex’s shared default one-second optional MCP startup grace could expire while the local stdio bridge was still establishing its remote SSE connection, so the server could appear in one initial tool catalog and disappear in the next. HarnessRouter now writes mcp_optional_startup_grace_ms = 0, making Codex wait each MCP server’s own startup_timeout_sec. The change is readiness fidelity for the adapter; it does not add native SSE to Codex.

PR #189, merged as 7e2c36a144819c41f3f346cdb7ac15e57568bf13, closes the bridge’s open-source image dependency gap before it reaches a tag. runner/mcp_bridge.py imports the MCP SDK at module load, but the image requirements did not pin that package. Runtime ancestry pins mcp==1.28.1, aligns gateway and runner on Pydantic 2.11.9, and adds a derived test requiring every runner module-level third-party import to be pinned in the shared image’s requirements. The hosted runner already carried that MCP version, so this is packaging/release-readiness fidelity rather than a new transport capability. PR #189 reports the bridge answering on Codex, Goose and dsh in a real-image check; those clients still do not gain native SSE.

PR #190, merged as current main cc692866c56d9c0c747d7da82eaaa46511eef3e0, reruns the dedicated conformance README measurement. The result remains 74/74 Full, 0 failed, 0 skipped, 0 errored on 15 September under suite 2026.9.12, while the current checked-in block now identifies the measured live runtime as HarnessRouter Community Edition 0.17.3. PR #190 changes only that evidence attribution; it does not alter Harness Plugins semantics, publish v0.17.3, or add a new versioned JSON report.

These corrections do not change UHP 2026-09-12, Agent Plugins 1.0.0 or the 74-check suite. Keep evidence forms distinct: PR #175 is v0.17.2 release/adversarial verification; PR #177 is the earlier README remeasurement; PR #178 is the versioned CE 0.17.2 JSON measurement; PR #190 is the current README remeasurement identifying live CE 0.17.3; PR #179 consumes report evidence for listing metadata. PRs #180–#182, #185, #188 and #189 are backend/runtime interoperability corrections, not new checked-in measurement artifacts.

Reference implementation — September snapshot

HarnessRouter v0.17.2, published 15 September 2026, targets release commit fa9ca27d71bb8c8987daead01db19fddb1d0d7c2. Checked upstream main is now cc692866c56d9c0c747d7da82eaaa46511eef3e0 after PR #190. The released gateway source:

defaults to UHP 2026-09-12;
continues to accept 2026-08-11 when explicitly requested;
advertises plugins: true;
advertises https://agent-plugins.org/schemas/1.0.0/plugin.schema.json in plugin_schemas;
implements package storage, harness binding, export and runner materialization for the optional sub-protocol.

The stable v0.17.2 release and post-release main must be kept separate. At v0.17.2, Pi/dsh plugin packages that contained a stdio MCP server were refused by the gateway. PR #180 removes that false admission restriction and teaches the native config writers; PR #181 corrects backend-specific SSE/HTTP spelling and, at that intermediate revision, records SSE as unsupported for Codex/dsh/Goose; PR #182 removes the residual dsh URL-only job filter; PR #185 then replaces the transport-specific SSE skip with a stdio-to-SSE bridge for clients lacking native SSE; PR #188 makes Codex wait the bridge under each server’s own startup timeout rather than a shared one-second optional grace; PR #189 pins the MCP SDK required to start that bridge in the open-source image. PR #190 refreshes conformance evidence only. Other published protocol coordinates remain unchanged.

Relationship to Agent Plugins

Before UHP 2026-09-12, UHP and Agent Plugins were complementary but had no standardized UHP binding. The boundary changed on 12 September 2026: UHP now normatively adopts Agent Plugins 1.0.0 as the package format for the optional Harness Plugins sub-protocol. HarnessRouter v0.17.2 is the first stable Community Edition release verified here to implement that binding, with PRs #180–#182, #185, #188 and #189 subsequently correcting backend-native MCP transport, launcher, readiness and bridge-packaging fidelity. PR #190 does not change that implementation boundary.

The standards still solve different problems:

Agent Plugins defines the portable extension package.
UHP defines how a product drives a complete harness and, when this optional capability is implemented, how that package is installed into and exported from the harness.
MCP remains authoritative for MCP wire behavior.
Agent Skills remains authoritative for skill package semantics.

See UHP vs Agent Plugins for the boundary comparison and Conformance for the measurement rules.

What changed

Review a package before binding it to execution

Harness object and derived state

Why stdio MCP appears here

Effective harness composition

Export is part of the contract

Capability discovery and errors

Security boundary

Conformance impact at introduction

Reference implementation — September snapshot

Relationship to Agent Plugins

Primary sources