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
conformance: the protocol schema ships inside the package, and the harness is resolved before the first task (#217)
Yominmafc520abedc69
diff --git a/protocol/conformance/README.md b/protocol/conformance/README.mdindex 76c34950..dfe9e3d6 100644--- a/protocol/conformance/README.md+++ b/protocol/conformance/README.md@@ -7,7 +7,7 @@ over HTTP, and anyone can run it against anyone's implementation.## Running it```bash-pip install -e protocol/conformance+pip install "git+https://github.com/HarnessRouter/harnessrouter.git#subdirectory=protocol/conformance"uhp-conformance \--base-url https://your-uhp-server \@@ -16,6 +16,16 @@ uhp-conformance \--json report.json```+The installed package includes the schema for its UHP version; it can validate responses without+a repository checkout, and a package that has somehow lost it reports every schema-backed check as+an error of the suite rather than a skip. For development, run `pip install -e protocol/conformance`+from the repository root instead.++`--harness-id` takes the harness's id (`chrn_…` on HarnessRouter), never its name: an id that+matches nothing ends the run before the first task, as does a named harness with no default model+when `--model` is not given. The harness and model the tasks run on are printed before the first+check.+| Option | Meaning ||---|---|| `--base-url` | Server root. The suite appends `/v1/...` itself. |@@ -252,3 +262,22 @@ Rules for a good check:Per [GOVERNANCE.md](../GOVERNANCE.md), a specification change is not complete until a check enforcesit — a rule nothing tests is a wish.++## Testing the package++From the repository root:++```bash+pip install -e protocol/conformance pytest build "setuptools>=68" wheel+python -m pytest protocol/conformance/tests -q+```++Without `build`, `setuptools` and `wheel` the two distribution tests skip and say why; the rest of+the suite, the byte-for-byte schema comparison included, runs with the package alone.++The schema in `protocol/schema/` is the source of truth. The package carries an exact copy of the+version named by `UHP_VERSION` in `uhp_conformance/uhp-<version>.schema.json`; copy it again whenever+that schema changes. A byte-for-byte comparison in the tests prevents the packaged copy from+drifting. The distribution tests also build both a wheel and a source distribution, install each+outside the checkout, and check that valid data passes and invalid data fails schema validation.+They use the installed build dependencies and do not fetch packages or call an agent server.diff --git a/protocol/conformance/pyproject.toml b/protocol/conformance/pyproject.tomlindex ec86c199..07055ba3 100644--- a/protocol/conformance/pyproject.toml+++ b/protocol/conformance/pyproject.toml@@ -1,6 +1,6 @@[project]name = "uhp-conformance"-version = "2026.9.12"+version = "2026.9.12.post1"description = "Conformance suite for the Unified Harness Protocol (UHP)"readme = "README.md"requires-python = ">=3.10"@@ -16,3 +16,6 @@ build-backend = "setuptools.build_meta"[tool.setuptools]packages = ["uhp_conformance"]++[tool.setuptools.package-data]+uhp_conformance = ["uhp-*.schema.json"]diff --git a/protocol/conformance/tests/test_harness_selection.py b/protocol/conformance/tests/test_harness_selection.pynew file mode 100644index 00000000..7485a48e--- /dev/null+++ b/protocol/conformance/tests/test_harness_selection.py@@ -0,0 +1,99 @@+"""The suite says which harness its tasks run on and never falls back silently (#203), and an+installation without the schema is an error of the suite, never a skip that reads as the server's.+"""+from __future__ import annotations++import json+import socket+import subprocess+import sys+import threading+from http.server import BaseHTTPRequestHandler, HTTPServer++import pytest++from uhp_conformance import checks, context+from uhp_conformance.client import Client+from uhp_conformance.context import Context+from uhp_conformance.registry import Outcome, REGISTRY+++HARNESSES = [{"id": "chrn_first", "name": "first", "defaultModel": "m1"},+ {"id": "chrn_second", "name": "second", "defaultModel": ""}]+++class _Stub(BaseHTTPRequestHandler):+ def log_message(self, *a):+ pass++ def do_GET(self):+ path = self.path.split("?", 1)[0]+ if path == "/v1/harnesses":+ body, status = {"harnesses": HARNESSES}, 200+ elif path.startswith("/v1/harnesses/"):+ hid = path.rsplit("/", 1)[1]+ found = [h for h in HARNESSES if h["id"] == hid]+ body, status = (found[0], 200) if found else ({"error": {"code": "harness_not_found"}}, 404)+ else:+ body, status = {"object": "uhp.discovery", "versions": ["2026-09-12"]}, 200+ raw = json.dumps(body).encode()+ self.send_response(status)+ self.send_header("content-type", "application/json")+ self.send_header("content-length", str(len(raw)))+ self.end_headers()+ self.wfile.write(raw)++[email protected](scope="module")+def stub():+ srv = HTTPServer(("127.0.0.1", 0), _Stub)+ threading.Thread(target=srv.serve_forever, daemon=True).start()+ yield f"http://127.0.0.1:{srv.server_address[1]}"+ srv.shutdown()+++def _cli(*args):+ return subprocess.run([sys.executable, "-m", "uhp_conformance.cli", *args],+ capture_output=True, text=True, timeout=60)+++def test_a_harness_id_that_matches_nothing_stops_the_run_before_the_first_task(stub):+ r = _cli("--base-url", stub, "--api-key", "k", "--harness-id", "smoke-hermes", "--class", "core")+ assert r.returncode == 2+ assert "no harness with id 'smoke-hermes'" in r.stderr and "not its name" in r.stderr+++def test_a_named_harness_without_a_default_model_needs_a_model(stub):+ r = _cli("--base-url", stub, "--api-key", "k", "--harness-id", "chrn_second", "--class", "core")+ assert r.returncode == 2 and "has no default model" in r.stderr+++def test_the_harness_the_tasks_run_on_is_announced(stub):+ r = _cli("--base-url", stub, "--api-key", "k", "--harness-id", "chrn_first", "--class", "core",+ "--only", "D-01", "--plain")+ assert "tasks run on harness chrn_first (first), model m1" in r.stderr+++def test_the_checks_never_fall_back_to_another_harness(stub):+ ctx = Context(client=Client(stub, "k"), harness_id="chrn_gone")+ with pytest.raises(RuntimeError, match="no harness with id 'chrn_gone'"):+ checks._harness(ctx)+ ctx = Context(client=Client(stub, "k"), harness_id="chrn_second")+ assert checks._harness(ctx)["id"] == "chrn_second"+ ctx = Context(client=Client(stub, "k"))+ assert checks._harness(ctx)["id"] == "chrn_first" # unnamed: the first listed+++def test_a_missing_schema_is_an_error_of_the_suite_not_a_skip(monkeypatch, tmp_path):+ """Thirty checks once skipped on an install without the schema and the report read as a+ partial server (#203). The check reports ERROR: the suite could not run."""+ monkeypatch.setattr(context, "SCHEMA_RESOURCE", tmp_path / "absent.json")+ ctx = Context(client=Client("http://unused.invalid", ""))+ with pytest.raises(RuntimeError, match="schema is missing from this installation"):+ ctx.validate({"id": "x"}, "File")+ monkeypatch.setattr(context, "jsonschema", None)+ with pytest.raises(RuntimeError, match="jsonschema is not installed"):+ Context(client=Client("http://unused.invalid", "")).validate({}, "File")+ check = next(c for c in REGISTRY if c.id == "D-03")+ r = check.run(Context(client=Client("http://unused.invalid", "")))+ assert r.outcome is Outcome.ERROR and "jsonschema is not installed" in r.detaildiff --git a/protocol/conformance/tests/test_schema_distribution.py b/protocol/conformance/tests/test_schema_distribution.pynew file mode 100644index 00000000..1ddc9d4c--- /dev/null+++ b/protocol/conformance/tests/test_schema_distribution.py@@ -0,0 +1,82 @@+"""Installing the suite outside a checkout must still run its schema checks (#203)."""+from __future__ import annotations++from importlib import resources+from pathlib import Path+import shutil+import subprocess+import sys++import pytest++from uhp_conformance import UHP_VERSION+++PROJECT = Path(__file__).resolve().parents[1]+SCHEMA_NAME = f"uhp-{UHP_VERSION}.schema.json"+++def test_bundled_schema_matches_the_specification():+ """The protocol owns the schema; the package carries an exact release snapshot of it."""+ canonical = PROJECT.parent / "schema" / SCHEMA_NAME+ bundled = resources.files("uhp_conformance").joinpath(SCHEMA_NAME)+ assert bundled.read_bytes() == canonical.read_bytes(), (+ f"refresh uhp_conformance/{SCHEMA_NAME} from protocol/schema/{SCHEMA_NAME}"+ )+++def _run(*args, cwd):+ result = subprocess.run(+ [sys.executable, "-I", *args], cwd=cwd, text=True, capture_output=True,+ timeout=120,+ )+ assert result.returncode == 0, result.stdout + result.stderr+ return result.stdout++[email protected](scope="module")+def distributions(tmp_path_factory):+ # The build tools are not part of the package's own dependencies: without them these two+ # tests say so and step aside, and the byte-for-byte test above still runs everywhere.+ for tool in ("build", "setuptools", "wheel"):+ pytest.importorskip(tool, reason=f"{tool} is not installed; pip install build setuptools wheel")+ root = tmp_path_factory.mktemp("conformance-dist")+ source = root / "source"+ shutil.copytree(+ PROJECT, source,+ ignore=shutil.ignore_patterns("*.egg-info", "__pycache__", "build", "dist", ".pytest_cache"),+ )+ # Only the conformance project is copied: no sibling protocol/schema directory can rescue+ # an incomplete distribution, and a stale local build/ or egg-info cannot supply its files.+ output = root / "dist"+ _run("-m", "build", "--no-isolation", "--wheel", "--sdist", "--outdir", str(output),+ cwd=source)+ return {"wheel": next(output.glob("*.whl")), "sdist": next(output.glob("*.tar.gz"))}++[email protected]("kind", ["wheel", "sdist"])+def test_installed_distribution_validates_instead_of_skipping(distributions, tmp_path, kind):+ target = tmp_path / "installed"+ # jsonschema and build requirements are already test dependencies. Installing the sdist+ # builds another wheel from its contents, without fetching anything or using the checkout.+ _run("-m", "pip", "install", "--no-deps", "--no-build-isolation", "--no-index",+ "--target", str(target), str(distributions[kind]), cwd=tmp_path)+ _run("-c", """+import pathlib+import sys++target = pathlib.Path(sys.argv[1]).resolve()+sys.path.insert(0, str(target))+from uhp_conformance import context+from uhp_conformance.client import Client++assert pathlib.Path(context.__file__).resolve().is_relative_to(target)+ctx = context.Context(client=Client("http://unused.invalid", ""))+ctx.validate({"id": "file_1", "filename": "report.csv"}, "File")+try:+ ctx.validate({"id": "file_1", "filename": 42}, "File")+except AssertionError as error:+ assert "does not match schema File" in str(error)+else:+ raise AssertionError("the installed schema accepted an invalid filename")+""", str(target), cwd=tmp_path)diff --git a/protocol/conformance/uhp_conformance/__init__.py b/protocol/conformance/uhp_conformance/__init__.pyindex d2063ec4..82070330 100644--- a/protocol/conformance/uhp_conformance/__init__.py+++ b/protocol/conformance/uhp_conformance/__init__.py@@ -1,3 +1,3 @@"""UHP conformance suite — the definition of "conformant" for the Unified Harness Protocol."""-__version__ = "2026.9.12"+__version__ = "2026.9.12.post1"UHP_VERSION = "2026-09-12"diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.pyindex f2df56e9..067d0ebb 100644--- a/protocol/conformance/uhp_conformance/checks.py+++ b/protocol/conformance/uhp_conformance/checks.py@@ -37,7 +37,14 @@ def _harness(ctx) -> dict:if not items:raise Skip("this server has no configured harnesses, so no task can be run")if ctx.harness_id:- items = [h for h in items if h.get("id") == ctx.harness_id] or items+ # Never a silent fallback: a named harness that is not there is the caller's mistake+ # (a name given for an id, a typo), and two runs against different --harness-id values+ # once produced byte-identical reports because both fell back to the first harness+ # listed (#203). The CLI resolves the id before the first task; this is the guard for a+ # harness that disappears mid-run.+ items = [h for h in items if h.get("id") == ctx.harness_id]+ if not items:+ raise RuntimeError(f"no harness with id {ctx.harness_id!r} on this server")ctx.state["harness"] = items[0]return items[0]diff --git a/protocol/conformance/uhp_conformance/cli.py b/protocol/conformance/uhp_conformance/cli.pyindex 9e94aafe..ded89b67 100644--- a/protocol/conformance/uhp_conformance/cli.py+++ b/protocol/conformance/uhp_conformance/cli.py@@ -49,16 +49,26 @@ def main(argv=None) -> int:ctx = Context(client=Client(a.base_url, a.api_key, headers=extra), harness_id=a.harness_id,model=a.model, task_timeout=a.task_timeout)- # A harness with no default model and no --model runs every task with whatever the server- # falls back to, which on a self-hosted instance may be an id its provider does not serve: each- # task then waits out --task-timeout and a full run takes half an hour to say nothing (#199).- # Say it before the first task instead.- if a.harness_id and not a.model:+ # The harness the tasks run on is resolved BEFORE the first task, and named. A --harness-id+ # that matches nothing (a harness name given for an id, a typo) once fell back silently to+ # the first harness listed, and two runs against different ids produced byte-identical+ # reports (#203). A harness with no default model and no --model runs every task with+ # whatever the server falls back to, which on a self-hosted instance may be an id its+ # provider does not serve: each task then waits out --task-timeout and a full run takes half+ # an hour to say nothing (#199). Both are said here, in one line, before anything runs.+ if a.harness_id:r = ctx.client.get(f"/v1/harnesses/{a.harness_id}")- if r.status == 200 and not str((r.json or {}).get("defaultModel") or "").strip():+ if r.status != 200 or not isinstance(r.json, dict):+ print(f"no harness with id {a.harness_id!r} on this server (HTTP {r.status}); pass the "+ "harness's id, not its name, or omit --harness-id to use the first listed",+ file=sys.stderr)+ return 2+ if not a.model and not str(r.json.get("defaultModel") or "").strip():print(f"harness {a.harness_id} has no default model; pass --model <id> so the tasks ""run on a model this server serves", file=sys.stderr)return 2+ print(f"tasks run on harness {a.harness_id} ({r.json.get('name') or 'unnamed'}), model "+ f"{a.model or r.json.get('defaultModel')}", file=sys.stderr)selected = checks_for(a.cls)if a.only:diff --git a/protocol/conformance/uhp_conformance/context.py b/protocol/conformance/uhp_conformance/context.pyindex 6c0adf1d..437c4556 100644--- a/protocol/conformance/uhp_conformance/context.py+++ b/protocol/conformance/uhp_conformance/context.py@@ -2,18 +2,18 @@from __future__ import annotationsimport json-import pathlibfrom dataclasses import dataclass, field+from importlib import resourcestry:import jsonschemaexcept ImportError: # pragma: no coverjsonschema = None+from . import UHP_VERSIONfrom .client import Client-SCHEMA_PATH = (pathlib.Path(__file__).resolve().parents[2]- / "schema" / "uhp-2026-09-12.schema.json")+SCHEMA_RESOURCE = resources.files("uhp_conformance").joinpath(f"uhp-{UHP_VERSION}.schema.json")@dataclass@@ -26,18 +26,24 @@ class Context:_schema: dict | None = Nonedef validate(self, instance, definition: str) -> None:- """Validate `instance` against a `$defs` entry, or skip loudly if that is impossible.-- A missing validator must never look like a pass, so this raises Skip rather than returning- quietly — an unrunnable check is reported as unrun.+ """Validate `instance` against a `$defs` entry, or fail the check if that is impossible.++ A missing validator must never look like a pass, and it must not look like "not applicable"+ either: the schema ships inside this package and jsonschema is a declared dependency, so+ their absence is a broken installation of the suite, and the check reports ERROR (the+ suite could not run) rather than SKIP (the server offered nothing to check). Thirty+ checks once skipped this way on a pip install that lacked the schema (#203), and a report+ with thirty skips read as a partial server rather than a partial suite."""- from .registry import Skipif jsonschema is None:- raise Skip("jsonschema is not installed, so schema validation cannot run")+ raise RuntimeError("jsonschema is not installed; the suite needs it to validate "+ "responses (pip install jsonschema)")if self._schema is None:- if not SCHEMA_PATH.exists():- raise Skip(f"schema not found at {SCHEMA_PATH}")- self._schema = json.loads(SCHEMA_PATH.read_text())+ if not SCHEMA_RESOURCE.is_file():+ raise RuntimeError(f"the UHP {UHP_VERSION} schema is missing from this installation "+ f"of uhp-conformance (expected {SCHEMA_RESOURCE}); reinstall the "+ "package")+ self._schema = json.loads(SCHEMA_RESOURCE.read_text(encoding="utf-8"))doc = {**self._schema, "$ref": f"#/$defs/{definition}"}errors = sorted(jsonschema.Draft202012Validator(doc).iter_errors(instance),key=lambda e: list(e.path))diff --git a/protocol/conformance/uhp_conformance/uhp-2026-09-12.schema.json b/protocol/conformance/uhp_conformance/uhp-2026-09-12.schema.jsonnew file mode 100644index 00000000..296043f1--- /dev/null+++ b/protocol/conformance/uhp_conformance/uhp-2026-09-12.schema.json@@ -0,0 +1,1367 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://unifiedharnessprotocol.org/schema/uhp-2026-09-12.schema.json",+ "title": "Unified Harness Protocol",+ "description": "Object definitions for UHP 2026-09-12. Generated from uhp-2026-09-12.openapi.yaml by build.py — do not edit by hand.",+ "$defs": {+ "Discovery": {+ "type": "object",+ "required": [+ "object",+ "protocol",+ "versions",+ "default_version",+ "conformance_class",+ "capabilities"+ ],+ "properties": {+ "object": {+ "type": "string",+ "const": "uhp.discovery"+ },+ "protocol": {+ "type": "string",+ "const": "uhp"+ },+ "versions": {+ "type": "array",+ "minItems": 1,+ "items": {+ "type": "string"+ }+ },+ "default_version": {+ "type": "string"+ },+ "conformance_class": {+ "type": "string",+ "enum": [+ "core",+ "extended",+ "full"+ ]+ },+ "capabilities": {+ "$ref": "#/$defs/Capabilities"+ },+ "plugin_schemas": {+ "type": "array",+ "items": {+ "type": "string",+ "format": "uri"+ },+ "description": "The Agent Plugins manifest schema identifiers this server installs. Present and non-empty\nwhen `capabilities.plugins` is true.\n",+ "examples": [+ [+ "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"+ ]+ ]+ },+ "implementation": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "version": {+ "type": "string"+ }+ },+ "additionalProperties": true+ }+ },+ "additionalProperties": true+ },+ "Capabilities": {+ "type": "object",+ "description": "Named booleans. A server reports `false` for a capability it does not implement rather than\nomitting it, so a client can distinguish \"not supported\" from \"server predates this field\".\nA client treats an absent key as `false`.\n",+ "properties": {+ "streaming": {+ "type": "boolean"+ },+ "sessions": {+ "type": "boolean"+ },+ "cancellation": {+ "type": "boolean"+ },+ "files_input": {+ "type": "boolean"+ },+ "files_output": {+ "type": "boolean"+ },+ "session_listing": {+ "type": "boolean"+ },+ "harness_management": {+ "type": "boolean"+ },+ "session_sharing": {+ "type": "boolean"+ },+ "idempotency": {+ "type": "boolean"+ },+ "plugins": {+ "type": "boolean",+ "description": "The server installs Agent Plugins packages into harnesses, serves their files, and exports\na harness as a package. Optional at every class.\n"+ }+ },+ "additionalProperties": {+ "type": "boolean"+ }+ },+ "Harness": {+ "type": "object",+ "required": [+ "id",+ "name",+ "base"+ ],+ "properties": {+ "id": {+ "type": "string",+ "pattern": "^chrn_"+ },+ "object": {+ "type": "string",+ "const": "harness"+ },+ "name": {+ "type": "string"+ },+ "base": {+ "type": "string",+ "description": "Opaque. Not enumerated by this specification — a client must treat it as a string, or the\nprotocol would need revising every time a harness is released.\n",+ "examples": [+ "codex",+ "claude-code",+ "hermes"+ ]+ },+ "baseLabel": {+ "type": "string"+ },+ "defaultModel": {+ "type": "string"+ },+ "systemPrompt": {+ "type": "string"+ },+ "mcpServers": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/McpServer"+ }+ },+ "skills": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Skill"+ }+ },+ "plugins": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Plugin"+ },+ "description": "Installed plugins. Their servers and skills join the harness's own for every turn;\n`mcpServers` and `skills` above report only what was written to them directly.\n"+ },+ "disabledTools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "maxStep": {+ "type": [+ "integer",+ "null"+ ]+ },+ "timeoutSeconds": {+ "type": [+ "integer",+ "null"+ ]+ },+ "createdAt": {+ "type": "integer",+ "description": "Unix milliseconds"+ }+ },+ "additionalProperties": true+ },+ "McpServer": {+ "type": "object",+ "required": [+ "name",+ "url"+ ],+ "description": "A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a\ndisabled entry must not be contacted at all. An unreachable server must not fail the task.\nUnchanged from 2026-08-11: a process (stdio) server is declared inside a plugin, see\nPluginMcpServer.\n",+ "properties": {+ "name": {+ "type": "string",+ "description": "Sanitised to a CLI-safe identifier by the server."+ },+ "url": {+ "type": "string",+ "format": "uri"+ },+ "transport": {+ "type": "string",+ "enum": [+ "http",+ "sse"+ ],+ "default": "http"+ },+ "enabled": {+ "type": "boolean",+ "default": true+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ "auth": {+ "type": "string",+ "description": "Bearer token, or a server-side reference the server resolves. A server must never return\na resolved credential to a client.\n"+ }+ },+ "additionalProperties": true+ },+ "PluginMcpServer": {+ "type": "object",+ "required": [+ "name"+ ],+ "description": "An MCP server a plugin's mcp.json declares, derived by the server. The harness MCP server\nobject plus the `stdio` transport: `url` is required for `http` and `sse`, `command` for\n`stdio`. Placeholders are reported unexpanded; `enabled` is always true, the plugin's own\n`enabled` governs.\n",+ "properties": {+ "name": {+ "type": "string"+ },+ "transport": {+ "type": "string",+ "enum": [+ "http",+ "sse",+ "stdio"+ ],+ "default": "http",+ "description": "`http` is Streamable HTTP (`streamable-http` in mcp.json); `sse` the older HTTP+SSE\ntransport; `stdio` a process the server launches inside the agent's sandbox.\n"+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "Endpoint (`http` and `sse`)."+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Fixed request headers (`http` and `sse`). Never subject to placeholder expansion."+ },+ "command": {+ "type": "string",+ "description": "One executable token (`stdio`): a bare name resolved on the sandbox's search path, or a\nplugin-relative path beginning with `./`. Never a shell string, never expanded.\n"+ },+ "args": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Arguments (`stdio`). `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expand at run time."+ },+ "env": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Environment overlay (`stdio`). Must not name PLUGIN_ROOT or PLUGIN_DATA; the server sets\nthose. Values expand at run time.\n"+ },+ "cwd": {+ "type": "string",+ "description": "Working directory (`stdio`). Defaults to the plugin root; must stay within the plugin\nroot or PLUGIN_DATA.\n"+ },+ "enabled": {+ "type": "boolean",+ "default": true+ }+ },+ "allOf": [+ {+ "if": {+ "properties": {+ "transport": {+ "const": "stdio"+ }+ },+ "required": [+ "transport"+ ]+ },+ "then": {+ "required": [+ "command"+ ]+ },+ "else": {+ "required": [+ "url"+ ]+ }+ }+ ],+ "additionalProperties": true+ },+ "Skill": {+ "type": "object",+ "required": [+ "name"+ ],+ "description": "A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent\ncan read it — materialising only SKILL.md breaks every skill carrying references, scripts or\ndata. Round-tripping a harness through GET and PUT must not lose skill contents.\n",+ "properties": {+ "name": {+ "type": "string"+ },+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "false suppresses the skill, including one inherited from the base."+ },+ "files": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/SkillFile"+ },+ "description": "The bundle. Must contain a SKILL.md."+ },+ "content": {+ "type": "string",+ "description": "Shorthand for a single-file bundle whose only member is SKILL.md."+ },+ "blob": {+ "type": "string",+ "description": "Server-assigned handle for a bundle stored out of line. A client receives it, passes it\nback unchanged, and reads the files from the skill files endpoint.\n"+ }+ },+ "additionalProperties": true+ },+ "SkillFile": {+ "type": "object",+ "required": [+ "path"+ ],+ "description": "One file of a skill folder or of a plugin package.",+ "properties": {+ "path": {+ "type": "string",+ "description": "Relative to the skill's own folder, or to the plugin root; nested directories are\nsupported. A server must reject a path that escapes the folder.\n",+ "examples": [+ "SKILL.md",+ "references/codes.md",+ "assets/logo.png"+ ]+ },+ "content": {+ "type": "string",+ "description": "Text content."+ },+ "content_b64": {+ "type": "string",+ "description": "Base64 for binary content; preserved byte-for-byte."+ }+ },+ "additionalProperties": true+ },+ "FileList": {+ "type": "object",+ "required": [+ "files"+ ],+ "properties": {+ "files": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/SkillFile"+ }+ }+ }+ },+ "Plugin": {+ "type": "object",+ "required": [+ "name"+ ],+ "description": "An Agent Plugins package installed into a harness: `plugin.json` at the root, MCP servers in\n`mcp.json`, skills under `skills/`. A client writes `files` (or passes back `blob`) and\noptionally `name` and `enabled`; the server derives `manifest`, `mcpServers`, `skills` and\n`skipped` from the package on every write and ignores those fields on input. A refused\npackage leaves the harness unchanged.\n",+ "properties": {+ "name": {+ "type": "string",+ "pattern": "^(?!.*(--|\\.\\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$",+ "maxLength": 64,+ "description": "The manifest's `name`. Optional on write; if sent it must equal the manifest's."+ },+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "false keeps the plugin installed and inert; nothing in it is materialised or contacted."+ },+ "files": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/SkillFile"+ },+ "description": "The package. Must contain `plugin.json` at its root."+ },+ "blob": {+ "type": "string",+ "description": "Server-assigned handle for a package stored out of line. A client passes it back unchanged\nand reads the files from the plugin files endpoint.\n"+ },+ "manifest": {+ "$ref": "#/$defs/PluginManifest"+ },+ "mcpServers": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/PluginMcpServer"+ },+ "description": "Derived from `mcp.json`. Placeholders are reported unexpanded; `enabled` is always true,\nthe plugin's own `enabled` governs.\n"+ },+ "skills": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/PluginSkill"+ },+ "description": "Derived from `skills/`, one entry per immediate child directory with a SKILL.md."+ },+ "skipped": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/PluginSkipped"+ },+ "description": "What the server found and could not load. Present on every plugin object the server\nreturns, empty when nothing was skipped.\n"+ }+ },+ "additionalProperties": true+ },+ "PluginManifest": {+ "type": "object",+ "required": [+ "$schema",+ "name"+ ],+ "description": "`plugin.json`, parsed. Mirrors the Agent Plugins 1.0.0 manifest schema\n(https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, Apache-2.0) field for field, and\npermits additional properties because a UHP client ignores fields it does not know. The\nschema a manifest's own `$schema` names is authoritative; a server validates against that.\n",+ "properties": {+ "$schema": {+ "type": "string",+ "format": "uri"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 64,+ "pattern": "^(?!.*(--|\\.\\.))[a-z0-9]([a-z0-9.-]*[a-z0-9])?$"+ },+ "version": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "author": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "email": {+ "type": "string"+ },+ "url": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "homepage": {+ "type": "string"+ },+ "repository": {+ "type": "string"+ },+ "license": {+ "type": "string"+ },+ "keywords": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "extensions": {+ "type": "object",+ "description": "Client-specific data keyed by reverse-domain namespace, per Agent Plugins §8.",+ "additionalProperties": {+ "type": "object"+ }+ }+ },+ "additionalProperties": true+ },+ "PluginSkill": {+ "type": "object",+ "required": [+ "name"+ ],+ "properties": {+ "name": {+ "type": "string",+ "description": "The SKILL.md frontmatter name",+ "equal to the directory name.": null+ },+ "description": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "PluginSkipped": {+ "type": "object",+ "required": [+ "path",+ "reason"+ ],+ "properties": {+ "path": {+ "type": "string",+ "description": "Where in the package, e.g. `skills/broken`, `mcp.json#/mcpServers/redline`, `plugin.json#/vendorField`.",+ "examples": [+ "skills/broken",+ "mcp.json#/mcpServers/redline"+ ]+ },+ "reason": {+ "type": "string",+ "description": "One sentence."+ }+ },+ "additionalProperties": true+ },+ "HarnessCreate": {+ "type": "object",+ "required": [+ "base"+ ],+ "properties": {+ "name": {+ "type": "string"+ },+ "base": {+ "type": "string"+ },+ "default_model": {+ "type": "string"+ },+ "system_prompt": {+ "type": "string"+ },+ "mcp_servers": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/McpServer"+ }+ },+ "skills": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Skill"+ }+ },+ "plugins": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Plugin"+ },+ "description": "Requires the `plugins` capability. Each item needs `files` or `blob`."+ },+ "disabled_tools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "max_step": {+ "type": [+ "integer",+ "null"+ ]+ },+ "timeout_seconds": {+ "type": [+ "integer",+ "null"+ ]+ }+ },+ "additionalProperties": true+ },+ "ModelCatalog": {+ "type": "object",+ "required": [+ "backends"+ ],+ "properties": {+ "backends": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "required": [+ "default",+ "models"+ ],+ "properties": {+ "default": {+ "type": "string"+ },+ "models": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Model"+ }+ }+ }+ }+ }+ }+ },+ "HarnessModels": {+ "type": "object",+ "required": [+ "models"+ ],+ "properties": {+ "harness_id": {+ "type": "string"+ },+ "backend": {+ "type": "string"+ },+ "default": {+ "type": "string"+ },+ "fallback": {+ "type": "string"+ },+ "models": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Model"+ }+ }+ }+ },+ "Model": {+ "type": "object",+ "required": [+ "id",+ "available"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "label": {+ "type": "string"+ },+ "backend": {+ "type": "string"+ },+ "available": {+ "type": "boolean",+ "description": "Computed, not asserted: true means the server can serve this model for this harness right\nnow. Listing a model as available and then failing the task is the worst outcome for a\nclient, because a user has already chosen it.\n"+ },+ "default": {+ "type": "boolean"+ }+ },+ "additionalProperties": true+ },+ "CreateResponseRequest": {+ "type": "object",+ "required": [+ "input"+ ],+ "properties": {+ "input": {+ "oneOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": true+ }+ }+ ],+ "description": "A bare string is shorthand for one user message."+ },+ "model": {+ "type": "string",+ "description": "Canonical model id. Omitted means the harness default."+ },+ "metadata": {+ "type": "object",+ "description": "Client metadata. `harness_id` selects the configured harness.",+ "properties": {+ "harness_id": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "stream": {+ "type": "boolean",+ "default": false+ },+ "previous_response_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "instructions": {+ "type": "string"+ },+ "store": {+ "type": "boolean",+ "default": true+ },+ "max_output_tokens": {+ "type": [+ "integer",+ "null"+ ]+ },+ "max_step": {+ "type": [+ "integer",+ "null"+ ],+ "description": "Agent step (tool-call round) budget"+ },+ "timeout_seconds": {+ "type": [+ "integer",+ "null"+ ],+ "description": "Wall-clock budget"+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": true+ },+ "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. A UHP harness invokes and executes tools\nitself and reports them in `output`; there is no input path for a tool result, so the\nclient-executed tool loop this field implies cannot be completed by a conformant server.\nConfigure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.\n"+ },+ "include": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in\n`metadata.ignored_fields` on the response. No values are enumerated, so any string a\nserver recognised would be one it named itself. Tasks §1.4.\n"+ },+ "background": {+ "type": "boolean",+ "default": false+ }+ },+ "additionalProperties": true+ },+ "Response": {+ "type": "object",+ "required": [+ "id",+ "object",+ "created_at",+ "status",+ "output",+ "model"+ ],+ "properties": {+ "id": {+ "type": "string",+ "pattern": "^resp_"+ },+ "object": {+ "type": "string",+ "const": "response"+ },+ "created_at": {+ "type": "integer",+ "description": "Unix seconds"+ },+ "status": {+ "$ref": "#/$defs/ResponseStatus"+ },+ "error": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "$ref": "#/$defs/Error"+ }+ ],+ "description": "Non-null only when status is `failed`."+ },+ "incomplete_details": {+ "type": [+ "object",+ "null"+ ],+ "additionalProperties": true+ },+ "previous_response_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "model": {+ "type": "string",+ "description": "The model that actually ran."+ },+ "output": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/OutputItem"+ }+ },+ "store": {+ "type": "boolean"+ },+ "usage": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "$ref": "#/$defs/Usage"+ }+ ],+ "description": "null when the server cannot account for usage. A fabricated zero would be worse than an\nhonest absence, because a client cannot tell it from a free task.\n"+ },+ "metadata": {+ "type": "object",+ "properties": {+ "session_id": {+ "type": "string"+ },+ "requested_model": {+ "type": "string",+ "description": "Present when the server ran a different model than was requested."+ },+ "model_fallback": {+ "type": "boolean"+ },+ "model_fallback_reason": {+ "type": "string"+ },+ "ignored_fields": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Request fields the server did not act on, by name, in any order. Required when the\nrequest carried `tools` or `include`, which are reserved and ignored. A silently\nignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.\n"+ }+ },+ "additionalProperties": true+ }+ },+ "additionalProperties": true+ },+ "ResponseStatus": {+ "type": "string",+ "enum": [+ "in_progress",+ "completed",+ "failed",+ "incomplete",+ "cancelled"+ ],+ "description": "`incomplete` means a budget stopped the work and is usually worth continuing.\n`failed` means it could not be done. `cancelled` means the client asked for a stop, and must\nnever be reported as `failed`.\n"+ },+ "OutputItem": {+ "type": "object",+ "required": [+ "type"+ ],+ "description": "A client must tolerate item types it does not recognise. A client that renders only `message`\nitems and ignores the rest is a valid client.\n",+ "properties": {+ "id": {+ "type": "string"+ },+ "type": {+ "type": "string",+ "examples": [+ "message",+ "reasoning",+ "function_call",+ "function_call_output"+ ]+ },+ "status": {+ "type": "string"+ },+ "role": {+ "type": "string"+ },+ "content": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/ContentPart"+ }+ },+ "summary": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": true+ }+ },+ "call_id": {+ "type": "string"+ },+ "name": {+ "type": "string"+ },+ "arguments": {+ "type": "string",+ "description": "JSON",+ "as a string": null+ },+ "output": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "ContentPart": {+ "type": "object",+ "required": [+ "type"+ ],+ "properties": {+ "type": {+ "type": "string",+ "examples": [+ "output_text"+ ]+ },+ "text": {+ "type": "string"+ },+ "annotations": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Annotation"+ }+ }+ },+ "additionalProperties": true+ },+ "Annotation": {+ "type": "object",+ "required": [+ "type"+ ],+ "properties": {+ "type": {+ "type": "string",+ "const": "container_file_citation"+ },+ "container_id": {+ "type": "string"+ },+ "file_id": {+ "type": "string"+ },+ "filename": {+ "type": "string"+ },+ "download_url": {+ "type": "string",+ "format": "uri"+ },+ "start_index": {+ "type": "integer"+ },+ "end_index": {+ "type": "integer"+ }+ },+ "additionalProperties": true+ },+ "Usage": {+ "type": "object",+ "properties": {+ "input_tokens": {+ "type": "integer",+ "minimum": 0+ },+ "output_tokens": {+ "type": "integer",+ "minimum": 0+ },+ "total_tokens": {+ "type": "integer",+ "minimum": 0+ },+ "cache_read_tokens": {+ "type": "integer",+ "minimum": 0+ },+ "cache_write_tokens": {+ "type": "integer",+ "minimum": 0+ }+ },+ "additionalProperties": true+ },+ "SessionShare": {+ "type": "object",+ "description": "A published read-only view of a session (Sessions §5). `url` may be relative, resolving\nagainst the base URL the caller is already using — a server behind a proxy cannot know its\npublic origin, and a base-relative path survives every fronting. The share's id MUST NOT\nfunction as a credential for the rest of the API.\n",+ "required": [+ "id",+ "url"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "url": {+ "type": "string"+ },+ "object": {+ "type": "string",+ "description": "SHOULD be \"session.share\""+ },+ "enabled": {+ "type": "boolean"+ }+ },+ "additionalProperties": true+ },+ "TurnItem": {+ "type": "object",+ "description": "One turn of a session's history (Sessions §3). Previously an object with no stated shape,\nwhich kept every conformance check at \"the endpoint answered 200\" and made transcript\nrebuilding an exercise in one implementation's habits.\n",+ "required": [+ "id",+ "status"+ ],+ "properties": {+ "id": {+ "type": "string",+ "description": "The response id, usable with GET /v1/responses/{id}"+ },+ "status": {+ "type": "string"+ },+ "user": {+ "type": "string"+ },+ "assistant": {+ "type": "string"+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": true+ }+ },+ "files": {+ "type": "array",+ "items": {+ "type": "object",+ "additionalProperties": true+ }+ }+ },+ "additionalProperties": true+ },+ "Session": {+ "type": "object",+ "required": [+ "id"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "object": {+ "type": "string",+ "const": "session"+ },+ "harness_id": {+ "type": "string"+ },+ "title": {+ "type": "string"+ },+ "status": {+ "type": "string"+ },+ "created_at": {+ "type": "integer"+ },+ "updated_at": {+ "type": "integer"+ }+ },+ "additionalProperties": true+ },+ "SessionList": {+ "type": "object",+ "required": [+ "sessions"+ ],+ "properties": {+ "sessions": {+ "type": "array",+ "items": {+ "$ref": "#/$defs/Session"+ }+ },+ "next_cursor": {+ "type": [+ "string",+ "null"+ ],+ "description": "null on the last page. A client must not be required to detect the end by receiving fewer\nitems than requested — that heuristic is wrong whenever a page is exactly full.\n"+ }+ },+ "additionalProperties": true+ },+ "File": {+ "type": "object",+ "required": [+ "id",+ "filename"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "object": {+ "type": "string",+ "const": "file"+ },+ "container_id": {+ "type": "string"+ },+ "filename": {+ "type": "string"+ },+ "bytes": {+ "type": "integer",+ "minimum": 0+ },+ "created_at": {+ "type": "integer"+ }+ },+ "additionalProperties": true+ },+ "ErrorEnvelope": {+ "type": "object",+ "required": [+ "error"+ ],+ "properties": {+ "error": {+ "$ref": "#/$defs/Error"+ },+ "detail": {+ "type": "string",+ "deprecated": true,+ "description": "A human-readable alias of `error.message`, retained for clients written against\nimplementations that predate this envelope. Carries no information not in `error`.\n"+ }+ },+ "additionalProperties": true+ },+ "Error": {+ "type": "object",+ "required": [+ "type",+ "code",+ "message"+ ],+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "invalid_request_error",+ "authentication_error",+ "permission_error",+ "rate_limit_error",+ "harness_error",+ "server_error"+ ]+ },+ "code": {+ "type": "string",+ "description": "Specific and machine-readable. Servers may define additional codes for conditions this\nspecification does not cover, and must namespace them with a vendor prefix so a future\nversion cannot collide with them.\n",+ "examples": [+ "unsupported_protocol_version",+ "invalid_input",+ "harness_not_found",+ "response_not_found",+ "session_not_found",+ "plugin_not_found",+ "file_not_found",+ "session_expired",+ "harness_mismatch",+ "session_busy",+ "plugin_conflict",+ "file_too_large",+ "model_unavailable",+ "unsupported_base",+ "plugin_invalid",+ "unsupported_plugin_schema",+ "unsupported_transport",+ "missing_credential",+ "invalid_credential",+ "insufficient_scope",+ "rate_limited",+ "quota_exhausted",+ "harness_error",+ "harness_unavailable",+ "provider_error",+ "timeout",+ "cancelled",+ "preview_unavailable",+ "preview_failed"+ ]+ },+ "message": {+ "type": "string",+ "description": "One sentence, safe to show a user. Must not contain credentials, internal hostnames, file\npaths, or stack traces.\n"+ },+ "param": {+ "type": [+ "string",+ "null"+ ],+ "description": "Dotted path to the offending field."+ },+ "detail": {+ "type": [+ "object",+ "null"+ ],+ "additionalProperties": true+ }+ },+ "additionalProperties": true+ },+ "Event": {+ "type": "object",+ "required": [+ "type",+ "sequence_number"+ ],+ "description": "One streamed event. `sequence_number` starts at 0 and increases by exactly 1 per event, so a\nclient can detect a dropped event rather than silently rendering a gap.\n",+ "properties": {+ "type": {+ "type": "string",+ "examples": [+ "response.created",+ "response.in_progress",+ "response.output_item.added",+ "response.output_item.done",+ "response.content_part.added",+ "response.content_part.done",+ "response.output_text.delta",+ "response.output_text.done",+ "response.output_text.annotation.added",+ "response.reasoning_summary_part.added",+ "response.reasoning_summary_text.delta",+ "response.reasoning_summary_part.done",+ "response.function_call_arguments.delta",+ "response.function_call_arguments.done",+ "response.completed",+ "response.incomplete",+ "response.failed",+ "error"+ ]+ },+ "sequence_number": {+ "type": "integer",+ "minimum": 0+ },+ "response": {+ "$ref": "#/$defs/Response"+ },+ "item": {+ "$ref": "#/$defs/OutputItem"+ },+ "part": {+ "$ref": "#/$defs/ContentPart"+ },+ "annotation": {+ "$ref": "#/$defs/Annotation"+ },+ "delta": {+ "type": "string"+ },+ "text": {+ "type": "string"+ },+ "arguments": {+ "type": "string"+ },+ "item_id": {+ "type": "string"+ },+ "output_index": {+ "type": "integer",+ "minimum": 0+ },+ "content_index": {+ "type": "integer",+ "minimum": 0+ },+ "summary_index": {+ "type": "integer",+ "minimum": 0+ },+ "annotation_index": {+ "type": "integer",+ "minimum": 0+ },+ "code": {+ "type": "string"+ },+ "message": {+ "type": "string"+ },+ "param": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "additionalProperties": true+ }+ }+}