Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

UHP 2026-10-19: retiring a harness may retire its sessions under a stated restore window (#515)

github-actions[bot]2b34603edfa8
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index 50a4e3bb..1eab53c3 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -2,6 +2,40 @@
All notable changes to the Unified Harness Protocol.
+## 2026-10-19
+
+Against `2026-10-04`, one rule changes and the rest is additive.
+
+**Retiring a harness may retire its sessions with it, under a stated restore window**
+([Harnesses §5.3](versions/2026-10-19/harnesses.md#53-delete)). Every earlier version said a server
+MUST NOT delete the sessions or responses that used a deleted harness. That stays the rule for a
+server that reports the new `harness_retirement` capability `false`, or says nothing. A server that
+reports it `true` MAY remove them with the harness, under three conditions:
+- it states the window when the harness is retired: the delete response carries
+ `sessions: "retired"` and `restorableUntil` (Unix seconds), and its own interface tells the person
+ the window's length before they confirm;
+- within the window, a restore brings back the harness and its sessions together;
+- only after the window may it remove them for good. The one exception is a person's own request
+ to erase their data, which may remove their retired sessions sooner;
+- it never retires a harness mid-task: it cancels the task first, or refuses the delete with `409`
+ and the new code `harness_busy`, saying why.
+
+A server may withhold them from lists and reads while the window runs. The delete response gains
+`sessions` (`kept` or `retired`; absent means kept) and `restorableUntil`. This is the one change
+that is not additive. [Versioning](VERSIONING.md#the-current-versions-known-compromises) records what
+it means for a server that also serves an earlier version.
+
+**Harness writes refuse what they cannot store**, now stated in
+[Harnesses §5.1](versions/2026-10-19/harnesses.md#51-create): a field the harness does not have and
+a `default_model` its base does not run are `422`, the latter with `model_not_available`, now in
+the error table beside the task-time `model_unavailable`. Both maintained servers have done this
+since 2026-10-10.
+
+**Conformance suite 2026.10.19.** New check F-09 (class Full) creates a harness, runs a task on it
+and deletes the harness. A server whose `harness_retirement` is `false` or absent passes when the
+session still reads afterwards and the response says nothing else. One that reports it `true` passes
+when the delete response says `sessions: "retired"` with a future `restorableUntil`.
+
## Conformance suite 2026.10.4.post11 (2026-10-15)
No change to the protocol, the schema or any verdict a conformant server gets. ME-01 assumed the
diff --git a/protocol/README.md b/protocol/README.md
index 57582275..4982a7a2 100644
--- a/protocol/README.md
+++ b/protocol/README.md
@@ -38,9 +38,9 @@ job, not a completion.
| | |
|---|---|
-| **Current version** | `2026-10-04` |
+| **Current version** | `2026-10-19` |
| **Status** | Draft standard — stable enough to build on, versioned so it can change safely |
-| **Specification** | [`versions/2026-10-04/`](versions/2026-10-04/) |
+| **Specification** | [`versions/2026-10-19/`](versions/2026-10-19/) |
| **Machine-readable** | [`schema/`](schema/) — OpenAPI 3.1 + JSON Schema 2020-12 |
| **Conformance suite** | [`conformance/`](conformance/) — runnable, and the definition of "conformant" |
| **Change process** | [`GOVERNANCE.md`](GOVERNANCE.md) |
@@ -65,19 +65,19 @@ your client depends on, that is a specification bug — please
| Chapter | What it defines |
|---|---|
-| [Architecture](versions/2026-10-04/architecture.md) | Roles, conformance classes, and the object model |
-| [Lifecycle](versions/2026-10-04/lifecycle.md) | Version negotiation, capability discovery, task lifecycle |
-| [Harnesses](versions/2026-10-04/harnesses.md) | Discovering, selecting and configuring a harness |
-| [Plugins](versions/2026-10-04/plugins.md) | Packages of tools and skills, installed into a harness as one unit |
-| [Environments](versions/2026-10-04/environments.md) | A project's files and installed dependencies, built once and read-only in every session that names it |
-| [Memories](versions/2026-10-04/memories.md) | Memory that outlasts a session: a tree of memories, access per node, records, recall, providers |
-| [Tasks](versions/2026-10-04/tasks.md) | Sending work and receiving a result |
-| [Streaming](versions/2026-10-04/streaming.md) | Following progress as it happens |
-| [Sessions](versions/2026-10-04/sessions.md) | Continuing a conversation, and cancelling one |
-| [Files](versions/2026-10-04/files.md) | Sending files in, getting artifacts out |
-| [Errors](versions/2026-10-04/errors.md) | Failure taxonomy, retries and idempotency |
-| [Security](versions/2026-10-04/security.md) | What an implementer must get right, collected in one place |
-| [Schema](versions/2026-10-04/schema.md) | The machine-readable definitions and how to use them |
+| [Architecture](versions/2026-10-19/architecture.md) | Roles, conformance classes, and the object model |
+| [Lifecycle](versions/2026-10-19/lifecycle.md) | Version negotiation, capability discovery, task lifecycle |
+| [Harnesses](versions/2026-10-19/harnesses.md) | Discovering, selecting and configuring a harness |
+| [Plugins](versions/2026-10-19/plugins.md) | Packages of tools and skills, installed into a harness as one unit |
+| [Environments](versions/2026-10-19/environments.md) | A project's files and installed dependencies, built once and read-only in every session that names it |
+| [Memories](versions/2026-10-19/memories.md) | Memory that outlasts a session: a tree of memories, access per node, records, recall, providers |
+| [Tasks](versions/2026-10-19/tasks.md) | Sending work and receiving a result |
+| [Streaming](versions/2026-10-19/streaming.md) | Following progress as it happens |
+| [Sessions](versions/2026-10-19/sessions.md) | Continuing a conversation, and cancelling one |
+| [Files](versions/2026-10-19/files.md) | Sending files in, getting artifacts out |
+| [Errors](versions/2026-10-19/errors.md) | Failure taxonomy, retries and idempotency |
+| [Security](versions/2026-10-19/security.md) | What an implementer must get right, collected in one place |
+| [Schema](versions/2026-10-19/schema.md) | The machine-readable definitions and how to use them |
## Quick shape of it
@@ -100,13 +100,13 @@ The stream is Server-Sent Events. The last event carries the finished `response`
any files the agent produced. To continue the same conversation, send the next request with
`previous_response_id` set to the id you just received.
-Full walk-through: [Tasks](versions/2026-10-04/tasks.md).
+Full walk-through: [Tasks](versions/2026-10-19/tasks.md).
## Relationship to the OpenAI Responses API
UHP's task surface is deliberately shaped like the OpenAI Responses API, and a conformant server
-MUST accept the subset of that request body described in [Tasks](versions/2026-10-04/tasks.md) and
-emit the event vocabulary described in [Streaming](versions/2026-10-04/streaming.md).
+MUST accept the subset of that request body described in [Tasks](versions/2026-10-19/tasks.md) and
+emit the event vocabulary described in [Streaming](versions/2026-10-19/streaming.md).
This is a compatibility decision, not an accident. Products already have code that speaks Responses;
existing SDKs, streaming parsers, and UI components work against a UHP server with no changes. What
@@ -120,7 +120,7 @@ of an existing field. A client that ignores every UHP extension still gets a wor
## Implementing UHP
-1. Read [Architecture](versions/2026-10-04/architecture.md) and pick a conformance class.
+1. Read [Architecture](versions/2026-10-19/architecture.md) and pick a conformance class.
2. Generate types from [`schema/uhp-2026-09-12.openapi.yaml`](schema/uhp-2026-09-12.openapi.yaml).
3. Run the [conformance suite](conformance/) against your server while you build:
```bash
diff --git a/protocol/VERSIONING.md b/protocol/VERSIONING.md
index ad79795a..d5fb4277 100644
--- a/protocol/VERSIONING.md
+++ b/protocol/VERSIONING.md
@@ -2,8 +2,8 @@
## The scheme
-UHP versions are dates — `YYYY-MM-DD`, the day the version was published. `2026-10-04` is the
-current version; `2026-09-28`, `2026-09-12` and `2026-08-11` remain published and served.
+UHP versions are dates — `YYYY-MM-DD`, the day the version was published. `2026-10-19` is the
+current version; `2026-10-04`, `2026-09-28`, `2026-09-12` and `2026-08-11` remain published and served.
Dates were chosen over semantic versioning deliberately. SemVer's promise is that a major bump means
"expect breakage" and a minor bump means "safe" — a promise that is only as good as the discipline
@@ -54,7 +54,8 @@ A server MUST:
3. Support at least one full version at a time, and SHOULD support the previous version for at least
six months after a new one is published. When the newer version is additive, as `2026-10-04` is
to `2026-09-28`, that one to `2026-09-12` and that one to `2026-08-11`, all are served from one code path: the same objects answer either request,
- and the only difference a client sees is the version echoed in the header.
+ and the only difference a client sees is the version echoed in the header. `2026-10-19` is
+ additive to `2026-10-04` except in one rule, which the known compromises below describe.
## Deprecation
@@ -86,5 +87,12 @@ smooth ones.
and a harness on a model no base runs refused every task given to it; a client, and above all an
agent driving the API, had no way to learn why. What the harness object comes back with and cannot be written (`id`,
`object`, `createdAt` and the server's own read-only fields) is still accepted and ignored, so a
- harness read and sent back saves. The next version states both rules in
- [Harnesses §5](versions/2026-10-04/harnesses.md#5-managing-harnesses).
+ harness read and sent back saves. `2026-10-19` states both rules in
+ [Harnesses §5.1](versions/2026-10-19/harnesses.md#51-create).
+- **Retiring a harness under an earlier version.** `2026-10-19` lets a server that reports
+ `harness_retirement` retire a harness's sessions with it, restorable for a window it states and
+ removed after it ([Harnesses §5.3](versions/2026-10-19/harnesses.md#53-delete)). Every earlier
+ version says a server MUST NOT delete them. A server that retires sessions this way and also serves
+ an earlier version from one code path departs from that version's §5.3 for those requests; a
+ client that depends on a retired harness's history reads `harness_retirement` from discovery,
+ which a server reports whatever version the request names.
diff --git a/protocol/conformance/tests/test_harness_retirement.py b/protocol/conformance/tests/test_harness_retirement.py
new file mode 100644
index 00000000..48a39932
--- /dev/null
+++ b/protocol/conformance/tests/test_harness_retirement.py
@@ -0,0 +1,110 @@
+"""F-09 (Harnesses §5.3, 2026-10-19): a server keeps a deleted harness's sessions unless it reports
+`harness_retirement`, and one that does says so in the delete response with the restore window.
+Each verdict is read against a stub server that answers one way."""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from uhp_conformance import checks
+from uhp_conformance.client import Client
+from uhp_conformance.context import Context
+from uhp_conformance.registry import Skip
+
+MODE = {"delete": {}, "session_after": 200}
+
+
+class _Stub(BaseHTTPRequestHandler):
+ def log_message(self, *a):
+ pass
+
+ def _send(self, status, body):
+ 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)
+
+ def do_POST(self):
+ n = int(self.headers.get("content-length") or 0)
+ body = json.loads(self.rfile.read(n) or b"{}")
+ if self.path == "/v1/harnesses":
+ if body.get("base") == "uhp-conformance-unknown-base":
+ return self._send(422, {"error": {"code": "unsupported_base", "detail": {"supported": ["stub-base"]}}})
+ return self._send(200, {"id": "chrn_retire", "base": body.get("base")})
+ if self.path == "/v1/responses":
+ return self._send(200, {"status": "completed", "metadata": {"session_id": "hsess_retire"}})
+ self._send(404, {})
+
+ def do_DELETE(self):
+ if self.path == "/v1/harnesses/chrn_retire":
+ return self._send(200, {"id": "chrn_retire", "deleted": True, **MODE["delete"]})
+ self._send(200, {"deleted": True})
+
+ def do_GET(self):
+ if self.path == "/v1/sessions/hsess_retire":
+ return self._send(MODE["session_after"], {"id": "hsess_retire"})
+ self._send(404, {})
+
+
[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 _run(stub, *, retires, delete, session_after=200):
+ MODE["delete"], MODE["session_after"] = delete, session_after
+ ctx = Context(client=Client(stub, "k"))
+ ctx.state["discovery"] = {"capabilities": {"harness_retirement": retires}}
+ return checks.f09(ctx)
+
+
+def test_a_server_that_keeps_sessions_passes_when_the_session_still_reads(stub):
+ assert _run(stub, retires=False, delete={}).startswith("kept")
+ assert _run(stub, retires=False, delete={"sessions": "kept"}).startswith("kept")
+
+
+def test_a_kept_session_that_no_longer_reads_fails(stub):
+ with pytest.raises(AssertionError, match="stay readable"):
+ _run(stub, retires=False, delete={}, session_after=404)
+
+
+def test_retiring_sessions_without_reporting_the_capability_fails(stub):
+ with pytest.raises(AssertionError, match="must report the capability"):
+ _run(stub, retires=False, delete={"sessions": "retired", "restorableUntil": int(time.time()) + 86400})
+
+
+def test_a_retiring_server_passes_with_the_window_stated_and_may_answer_404_inside_it(stub):
+ until = int(time.time()) + 30 * 86400
+ out = _run(stub, retires=True, delete={"sessions": "retired", "restorableUntil": until}, session_after=404)
+ assert out == f"retired with the harness, restorable until {until}"
+
+
+def test_a_retiring_server_fails_without_the_window_or_with_one_in_the_past(stub):
+ with pytest.raises(AssertionError, match="sessions: \"retired\""):
+ _run(stub, retires=True, delete={})
+ with pytest.raises(AssertionError, match="in the future"):
+ _run(stub, retires=True, delete={"sessions": "retired"})
+ with pytest.raises(AssertionError, match="in the future"):
+ _run(stub, retires=True, delete={"sessions": "retired", "restorableUntil": int(time.time()) - 1})
+
+
+def test_no_session_to_retire_is_a_skip_not_a_verdict(stub, monkeypatch):
+ orig = _Stub.do_POST
+
+ def no_session(self):
+ if self.path == "/v1/responses":
+ self.rfile.read(int(self.headers.get("content-length") or 0))
+ return self._send(200, {"status": "completed", "metadata": {}})
+ return orig(self)
+ monkeypatch.setattr(_Stub, "do_POST", no_session)
+ with pytest.raises(Skip):
+ _run(stub, retires=False, delete={})
diff --git a/protocol/conformance/uhp_conformance/__init__.py b/protocol/conformance/uhp_conformance/__init__.py
index 10fa07bb..5bac285b 100644
--- a/protocol/conformance/uhp_conformance/__init__.py
+++ b/protocol/conformance/uhp_conformance/__init__.py
@@ -3,8 +3,8 @@
# and a report prints it as `suite_version`, so a report always names the code that produced it.
# It used to be written twice, and from 2026.10.4 to 2026.10.4.post8 only the packaging copy moved:
# every report of those nine revisions called itself 2026.9.12.post4.
-__version__ = "2026.10.4.post11"
-UHP_VERSION = "2026-10-04"
+__version__ = "2026.10.19"
+UHP_VERSION = "2026-10-19"
# The MCP server the plugin checks point a plugin at. It must resolve and answer: a host is
# allowed to refuse a server it cannot reach at configuration time and record that in `skipped`,
# so an unresolvable placeholder made those checks measure the refusal instead of the plugin. The
diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.py
index 9fcc78eb..b64c0795 100644
--- a/protocol/conformance/uhp_conformance/checks.py
+++ b/protocol/conformance/uhp_conformance/checks.py
@@ -18,7 +18,7 @@ import uuid
from .registry import Skip, check
-SPEC = "protocol/versions/2026-10-04"
+SPEC = "protocol/versions/2026-10-19"
# ── shared fixtures ────────────────────────────────────────────────────────────────────
@@ -1261,6 +1261,50 @@ def f08(ctx):
return f"deleted {sid}, now 404"
+@check("F-09", "Deleting a harness keeps its sessions, or states how long they can be restored", "full",
+ f"{SPEC}/harnesses.md#53-delete")
+def f09(ctx):
+ # §5.3 gives a server two rules and makes it say which one it follows: the capability says it
+ # before the delete, the delete response says it again with the window. A server that reports
+ # nothing keeps the sessions, which is what every version before 2026-10-19 required of all.
+ retires = bool(((ctx.state.get("discovery") or {}).get("capabilities") or {}).get("harness_retirement"))
+ h = _managed_harness(ctx)
+ body = {"input": PROMPT, "metadata": {"harness_id": h["id"]}, "stream": False}
+ if ctx.model:
+ body["model"] = ctx.model
+ r = ctx.client.post("/v1/responses", body=body)
+ sid = ((r.json or {}).get("metadata") or {}).get("session_id") if r.status == 200 else None
+ if not sid:
+ ctx.client.delete(f"/v1/harnesses/{h['id']}")
+ raise Skip(f"a task on a new harness returned no session_id (HTTP {r.status}), so there is no "
+ "session for the delete to keep or retire")
+ gone = ctx.client.delete(f"/v1/harnesses/{h['id']}")
+ assert gone.status in (200, 204), f"delete returned HTTP {gone.status}"
+ out = (gone.json or {}) if gone.status == 200 else {}
+ said = out.get("sessions") or "kept"
+ if retires:
+ assert said == "retired", (
+ f"the server reports harness_retirement true, but its delete response says sessions "
+ f"{said!r}; §5.3 requires sessions: \"retired\" with the window, so a client can tell the "
+ "person what happened to their history")
+ until = out.get("restorableUntil")
+ assert isinstance(until, int) and until > time.time(), (
+ f"restorableUntil must be a Unix time in the future, the end of the restore window the "
+ f"person is told about; got {until!r}")
+ return f"retired with the harness, restorable until {until}"
+ assert said == "kept", (
+ f"the delete response says sessions {said!r} while harness_retirement is false or absent; "
+ "a server that retires sessions must report the capability, so a client can warn first")
+ after = ctx.client.get(f"/v1/sessions/{sid}")
+ try:
+ assert after.status == 200, (
+ f"the session of a deleted harness answered HTTP {after.status}; with harness_retirement "
+ "false §5.3 requires it to stay readable")
+ finally:
+ ctx.client.delete(f"/v1/sessions/{sid}")
+ return f"kept: {sid} still reads after its harness was deleted"
+
+
@check("F-02", "Creating a harness with an unsupported base is refused", "full",
f"{SPEC}/harnesses.md#41-create")
def f02(ctx):
diff --git a/protocol/conformance/uhp_conformance/uhp-2026-10-19.schema.json b/protocol/conformance/uhp_conformance/uhp-2026-10-19.schema.json
new file mode 100644
index 00000000..ea25de01
--- /dev/null
+++ b/protocol/conformance/uhp_conformance/uhp-2026-10-19.schema.json
@@ -0,0 +1,3491 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://unifiedharnessprotocol.org/schema/uhp-2026-10-19.schema.json",
+ "title": "Unified Harness Protocol",
+ "description": "Object definitions for UHP 2026-10-19. Generated from uhp-2026-10-19.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"
+ },
+ "harness_retirement": {
+ "type": "boolean",
+ "description": "Retiring a harness retires its sessions and responses with it, restorable until a time\nthe delete response states (`restorableUntil`) and removed after it. `false`, or absent:\nthey are kept. See Harnesses §5.3.\n"
+ },
+ "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"
+ },
+ "environments": {
+ "type": "boolean",
+ "description": "The server holds environments: a project's files and installed dependencies, built once,\nread-only at a fixed path in every session that names one. Optional at every class.\n"
+ },
+ "memories": {
+ "type": "boolean",
+ "description": "The server holds memories: a tree of memories with access granted per node, records kept\nby a connected provider, and tools a harness's agent reaches them with. 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"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment (`henv_`) this harness's tasks read, mounted read-only at its `mount`;\nempty when none. A task may name another with its own `environment` field.\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`."
+ },
+ "environment": {
+ "type": "string",
+ "description": "An environment id of the caller's scope",
+ "or empty. Requires the `environments` capability.": null
+ },
+ "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, the extension point of the Responses surface. `harness_id` selects the\nconfigured harness; `environment` names the environment this task reads, overriding the\nharness's (capability `environments`), refused with `environment_not_found` or\n`environment_not_ready` before the task starts.\n",
+ "properties": {
+ "harness_id": {
+ "type": "string"
+ },
+ "environment": {
+ "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"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment the task read, when it read one (capability `environments`)."
+ },
+ "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
+ },
+ "Environment": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "slug",
+ "status",
+ "mount"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "pattern": "^henv_"
+ },
+ "object": {
+ "type": "string",
+ "const": "environment"
+ },
+ "name": {
+ "type": "string"
+ },
+ "slug": {
+ "type": "string",
+ "description": "The path segment sessions see; derived from the name at creation and fixed after."
+ },
+ "description": {
+ "type": "string"
+ },
+ "entry": {
+ "type": "string",
+ "description": "How the project is run, in the owner's words; repeated to the agent."
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "empty",
+ "building",
+ "ready",
+ "failed"
+ ],
+ "description": "`ready` means a built version is active and tasks may read it. `empty` means nothing\nwas built yet; `building` and `failed` describe the latest build.\n"
+ },
+ "mount": {
+ "type": "string",
+ "description": "Where a session finds the environment, read-only. `/env/<slug>` on the reference server."
+ },
+ "version": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "description": "The active build",
+ "the one sessions read; null until one is ready.": null
+ },
+ "latestVersion": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "files": {
+ "type": "object",
+ "description": "The source's size (what the owner put in, before any build).",
+ "properties": {
+ "count": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ }
+ }
+ },
+ "packages": {
+ "type": "array",
+ "description": "What the active build installed, as the package managers report it.",
+ "items": {
+ "$ref": "#/$defs/EnvironmentPackage"
+ }
+ },
+ "declared": {
+ "type": "object",
+ "description": "What the owner declared, per manager, as the build installs it beside the project's own\nmanifests: `pip` (`name==1.0`), `npm` (`[email protected]`), `apt` (`name`). Each entry carries\nthe spec as written and its parsed name and version.\n",
+ "properties": {
+ "pip": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ },
+ "npm": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ },
+ "apt": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ }
+ }
+ },
+ "runtime": {
+ "type": "object",
+ "description": "The interpreter a build makes the virtual environment with; empty means the server's default.",
+ "properties": {
+ "python": {
+ "type": "string",
+ "examples": [
+ "3.12"
+ ]
+ }
+ }
+ },
+ "versions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentVersion"
+ }
+ },
+ "build": {
+ "description": "The latest build's status, or null before the first.",
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/$defs/EnvironmentVersion"
+ }
+ ]
+ },
+ "createdAt": {
+ "type": "integer",
+ "description": "Unix milliseconds"
+ },
+ "updatedAt": {
+ "type": "integer",
+ "description": "Unix milliseconds"
+ }
+ },
+ "additionalProperties": true
+ },
+ "DeclaredPackage": {
+ "type": "object",
+ "required": [
+ "spec"
+ ],
+ "properties": {
+ "spec": {
+ "type": "string",
+ "description": "As written: moviepy==2.1.1, [email protected], ffmpeg"
+ },
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentPackageCheck": {
+ "type": "object",
+ "required": [
+ "manager",
+ "name",
+ "spec",
+ "exists"
+ ],
+ "description": "What the manager's registry says about a spec, before any build.",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "environment.package"
+ },
+ "manager": {
+ "type": "string",
+ "enum": [
+ "pip",
+ "npm",
+ "apt"
+ ]
+ },
+ "name": {
+ "type": "string"
+ },
+ "spec": {
+ "type": "string"
+ },
+ "exists": {
+ "type": [
+ "boolean",
+ "null"
+ ],
+ "description": "null when the registry could not be asked"
+ },
+ "latest": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string",
+ "description": "The exact pin when it is published; empty otherwise"
+ },
+ "error": {
+ "type": "string",
+ "description": "In words: why the spec was refused, or why the registry could not be asked"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentRuntimes": {
+ "type": "object",
+ "description": "What a build can be made with on this server, and nothing that is not there.",
+ "properties": {
+ "python": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "examples": [
+ [
+ "3.12",
+ "3.13"
+ ]
+ ]
+ },
+ "node": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "examples": [
+ [
+ "22"
+ ]
+ ]
+ },
+ "os": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ }
+ },
+ "apt": {
+ "type": "boolean",
+ "description": "Whether apt packages can be declared here."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentPackage": {
+ "type": "object",
+ "required": [
+ "manager",
+ "name"
+ ],
+ "properties": {
+ "manager": {
+ "type": "string",
+ "examples": [
+ "pip",
+ "npm"
+ ]
+ },
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentVersion": {
+ "type": "object",
+ "required": [
+ "version",
+ "status"
+ ],
+ "properties": {
+ "version": {
+ "type": "integer",
+ "minimum": 1
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "building",
+ "ready",
+ "failed",
+ "unknown"
+ ]
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "files": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ },
+ "packages": {
+ "type": "integer",
+ "description": "How many packages the build installed."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentBuild": {
+ "type": "object",
+ "required": [
+ "id",
+ "version",
+ "status"
+ ],
+ "description": "A build's record; the log is the installers' own output, capped by the server.",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "environment.build"
+ },
+ "version": {
+ "type": "integer"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "building",
+ "ready",
+ "failed"
+ ]
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "stage": {
+ "type": "string",
+ "description": "The step a running build is on; empty once it ended"
+ },
+ "log": {
+ "type": "string"
+ },
+ "packages": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentPackage"
+ }
+ },
+ "files": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Must start with a letter or digit; the slug derives from it."
+ },
+ "description": {
+ "type": "string"
+ },
+ "entry": {
+ "type": "string"
+ },
+ "packages": {
+ "type": "object",
+ "description": "Declared packages per manager, as spec strings; omitted on update means unchanged.",
+ "properties": {
+ "pip": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "npm": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "apt": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "runtime": {
+ "type": "object",
+ "properties": {
+ "python": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentList": {
+ "type": "object",
+ "required": [
+ "environments"
+ ],
+ "properties": {
+ "environments": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/Environment"
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentFileEntry": {
+ "type": "object",
+ "required": [
+ "path",
+ "dir"
+ ],
+ "properties": {
+ "path": {
+ "type": "string",
+ "description": "Relative to the environment's root."
+ },
+ "dir": {
+ "type": "boolean"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "mtime": {
+ "type": "integer",
+ "description": "Unix seconds."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentFileList": {
+ "type": "object",
+ "required": [
+ "entries"
+ ],
+ "properties": {
+ "entries": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentFileEntry"
+ }
+ },
+ "count": {
+ "type": "integer",
+ "description": "Files",
+ "not directories.": null
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentImport": {
+ "type": "object",
+ "description": "The JSON form of an import: a git repository. The other form is the archive itself as the\nrequest body (a zip or a tar, any content type but `application/json`).\n",
+ "properties": {
+ "git": {
+ "type": "object",
+ "required": [
+ "url"
+ ],
+ "properties": {
+ "url": {
+ "type": "string"
+ },
+ "ref": {
+ "type": "string",
+ "description": "A branch or tag; the default branch when omitted."
+ }
+ }
+ },
+ "replace": {
+ "type": "boolean",
+ "default": false,
+ "description": "Clear the source before importing."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentImportResult": {
+ "type": "object",
+ "properties": {
+ "written": {
+ "type": "integer"
+ },
+ "skipped": {
+ "type": "integer",
+ "description": "Members that must not land (links",
+ "escapes) and were dropped.": null
+ },
+ "count": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "Session": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "session"
+ },
+ "harness_id": {
+ "type": "string"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment the session's turns read",
+ "when one did.": null
+ },
+ "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",
+ "harness_busy",
+ "plugin_conflict",
+ "file_too_large",
+ "model_unavailable",
+ "model_not_available",
+ "unsupported_base",
+ "plugin_invalid",
+ "unsupported_plugin_schema",
+ "environment_not_found",
+ "environment_not_ready",
+ "environment_busy",
+ "environment_exists",
+ "environment_invalid",
+ "environment_unavailable",
+ "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
+ },
+ "Memory": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Opaque to a client. A server that maps a tree it already has keeps that tree's own ids."
+ },
+ "object": {
+ "type": "string",
+ "const": "memory"
+ },
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string",
+ "description": "What this memory holds; an agent reads it to decide whether to look inside."
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "ancestors": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Ids from the root down to the parent, as far up as the caller may see."
+ },
+ "restricted": {
+ "type": "boolean",
+ "description": "When true, grants on ancestors stop here."
+ },
+ "provider": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ },
+ "description": "The effective privileges of the caller on this memory."
+ },
+ "records": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ }
+ },
+ "children": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": "integer"
+ }
+ }
+ },
+ "createdAt": {
+ "type": "integer"
+ },
+ "updatedAt": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryPrivilege": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write",
+ "create",
+ "delete"
+ ]
+ },
+ "MemoryCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "restricted": {
+ "type": "boolean"
+ },
+ "provider": {
+ "type": "string",
+ "description": "A connected provider; inherited from the parent when omitted."
+ }
+ }
+ },
+ "MemoryUpdate": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "restricted": {
+ "type": "boolean"
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ }
+ },
+ "MemoryList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/Memory"
+ }
+ }
+ }
+ },
+ "MemoryDeleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "deleted": {
+ "type": "boolean"
+ },
+ "memories": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Every memory removed: the named one and its descendants."
+ }
+ }
+ },
+ "Deleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "deleted": {
+ "type": "boolean"
+ }
+ },
+ "additionalProperties": true
+ },
+ "FreeObject": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "MemoryNeighbour": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "records": {
+ "type": "object"
+ },
+ "children": {
+ "type": "object"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ },
+ "MemoryGrant": {
+ "type": "object",
+ "required": [
+ "id",
+ "memory_id",
+ "principal",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.grant"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "principal": {
+ "type": "string",
+ "pattern": "^(member|group|x\\.[a-z0-9_.-]+):.+",
+ "description": "Who holds the grant, `<kind>:<id>`: a `member` (a person or an agent), a `group`, or a kind of the server's own, `x.`-prefixed."
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ },
+ "inherited": {
+ "type": "boolean",
+ "description": "True when the grant sits on an ancestor."
+ }
+ }
+ },
+ "MemoryGrantCreate": {
+ "type": "object",
+ "required": [
+ "principal",
+ "privileges"
+ ],
+ "properties": {
+ "principal": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ },
+ "MemoryGrantList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryGrant"
+ }
+ }
+ }
+ },
+ "MemoryReference": {
+ "type": "object",
+ "required": [
+ "record_id"
+ ],
+ "properties": {
+ "rel": {
+ "type": "string"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "record_id": {
+ "type": "string"
+ },
+ "available": {
+ "type": "boolean",
+ "description": "False when the reader may not read the target; nothing else of it is returned."
+ }
+ }
+ },
+ "MemoryRecord": {
+ "type": "object",
+ "required": [
+ "id",
+ "memory_id",
+ "type",
+ "trust"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Assigned by the provider and opaque to a client."
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.record"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string",
+ "description": "episode, fact, note, procedure, link, entity, or an extension type."
+ },
+ "title": {
+ "type": "string",
+ "maxLength": 300,
+ "description": "One line that names the record. Optional; a search matches it with the content."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ },
+ "description": "An ordered list of parts. Always a list on a read."
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "version": {
+ "type": "integer"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "active",
+ "superseded",
+ "forgotten"
+ ]
+ },
+ "supersedes": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "description": "The number of the version this one replaced; null on the first."
+ },
+ "time": {
+ "type": "object",
+ "properties": {
+ "valid_from": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "valid_to": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "written_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "invalidated_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ }
+ },
+ "written_by": {
+ "$ref": "#/$defs/MemoryWriter"
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "follows": {
+ "type": "object",
+ "description": "Present only on a record the server derives from a source it keeps outside the memory (a section of a document). Such a record is not revised or forgotten through the memory.",
+ "properties": {
+ "kind": {
+ "type": "string",
+ "description": "What the source is, in a word: `document`."
+ },
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string",
+ "description": "What a person calls the source."
+ }
+ },
+ "additionalProperties": true
+ },
+ "trust": {
+ "type": "string",
+ "const": "untrusted"
+ },
+ "closed": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only on the answer to remembering a fact whose `holds` is `one`: the records it ended. Never stored."
+ },
+ "conflicts": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only on the answer to remembering a fact whose `holds` is `one`: the records it was linked to with `contradicts`. Never stored."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryContentPart": {
+ "type": "object",
+ "required": [
+ "type"
+ ],
+ "description": "One part of the content of a record. `text` and `file` are defined; any other kind is `x.`-prefixed and carried unchanged.",
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "text": {
+ "type": "string",
+ "description": "The words of a text part, or the words that stand for a file."
+ },
+ "text_source": {
+ "type": "string",
+ "enum": [
+ "stated",
+ "derived"
+ ]
+ },
+ "role": {
+ "type": "string",
+ "enum": [
+ "user",
+ "assistant",
+ "system",
+ "tool"
+ ]
+ },
+ "name": {
+ "type": "string",
+ "description": "Who said it, when the role alone does not: two people in one conversation are both `user`."
+ },
+ "file": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "media_type": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer"
+ },
+ "version": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryRecordCreate": {
+ "type": "object",
+ "required": [
+ "content"
+ ],
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "time": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryRecordRevise": {
+ "type": "object",
+ "properties": {
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "time": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryRecordList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ }
+ },
+ "next": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "job": {
+ "$ref": "#/$defs/MemoryJob"
+ },
+ "parent": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ },
+ "children": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ }
+ }
+ }
+ },
+ "MemoryObserve": {
+ "type": "object",
+ "required": [
+ "episodes"
+ ],
+ "properties": {
+ "episodes": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "object",
+ "required": [
+ "content"
+ ],
+ "properties": {
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "time": {
+ "type": "object",
+ "properties": {
+ "valid_from": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "When it happened. Left out, now."
+ }
+ },
+ "additionalProperties": true
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ }
+ },
+ "MemoryJob": {
+ "type": "object",
+ "required": [
+ "id",
+ "status"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "memory.job"
+ },
+ "id": {
+ "type": "string"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "queued",
+ "running",
+ "pending",
+ "completed",
+ "failed"
+ ],
+ "description": "`pending` when the provider cannot tell queued from running."
+ },
+ "error": {
+ "type": "string"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "description": "The records the job wrote."
+ },
+ "closed": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Records ended by a `one` fact the job wrote."
+ },
+ "conflicts": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Records linked with `contradicts` by a `one` fact the job wrote."
+ },
+ "usage": {
+ "type": "object",
+ "additionalProperties": true,
+ "description": "Tokens, when a model did the work: `input_tokens`, `output_tokens`."
+ },
+ "created_at": {
+ "type": "integer"
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ }
+ },
+ "MemoryWriter": {
+ "type": "object",
+ "description": "Who wrote a record, stamped by the server from the authenticated caller. `kind` and `id` joined by a colon are the principal a grant would name.",
+ "required": [
+ "kind",
+ "id"
+ ],
+ "properties": {
+ "kind": {
+ "type": "string",
+ "pattern": "^(member|provider|x\\.[a-z0-9_.-]+)$"
+ },
+ "id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "human",
+ "agent"
+ ],
+ "description": "For a member: a person or an agent. No rule depends on it."
+ },
+ "on_behalf_of": {
+ "type": "string",
+ "description": "When the provider wrote it: the principal whose observation it was derived from."
+ },
+ "consolidation_id": {
+ "type": "string",
+ "description": "When the provider wrote it: the consolidation run that concluded it."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryFilter": {
+ "type": "object",
+ "description": "One of `{field, op, value}`, `{and: [...]}` or `{or: [...]}`.",
+ "additionalProperties": true
+ },
+ "MemoryPrime": {
+ "type": "object",
+ "required": [
+ "records",
+ "tokens",
+ "truncated"
+ ],
+ "properties": {
+ "records": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ }
+ },
+ "tokens": {
+ "type": "integer",
+ "description": "The provider's own estimate of what the records cost."
+ },
+ "truncated": {
+ "type": "boolean",
+ "description": "True when a standing record was left out."
+ }
+ }
+ },
+ "MemoryRecallRequest": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Meaning."
+ },
+ "text": {
+ "type": "string",
+ "description": "Words."
+ },
+ "filters": {
+ "$ref": "#/$defs/MemoryFilter"
+ },
+ "types": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "as_of": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "include": {
+ "type": "string",
+ "enum": [
+ "active",
+ "all"
+ ]
+ },
+ "depth": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "minimum": 0,
+ "description": "Levels below to search: 0 is this memory alone. Left out, the whole readable subtree."
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100
+ }
+ }
+ },
+ "MemoryRecall": {
+ "type": "object",
+ "required": [
+ "results",
+ "degraded",
+ "abstain"
+ ],
+ "properties": {
+ "results": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "record",
+ "memory"
+ ],
+ "properties": {
+ "record": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "memory": {
+ "type": "object",
+ "description": "The memory this result is in, the one asked or one below it.",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "score": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "why": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "parent": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ },
+ "children": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ }
+ },
+ "degraded": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "What the request asked for and was not done."
+ },
+ "abstain": {
+ "type": "boolean",
+ "description": "True when the provider judges that nothing it returned answers the question."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryGraphRequest": {
+ "type": "object",
+ "properties": {
+ "around": {
+ "type": "string",
+ "description": "A record to start from. Left out, every record of this memory."
+ },
+ "hops": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 3,
+ "description": "References away from the start, in either direction. Default 1."
+ },
+ "types": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1
+ }
+ }
+ },
+ "MemoryRecordRef": {
+ "type": "object",
+ "description": "A record by where it is. `memory_id` is absent on the far end of an edge the caller may not follow.",
+ "required": [
+ "record_id"
+ ],
+ "properties": {
+ "memory_id": {
+ "type": "string"
+ },
+ "record_id": {
+ "type": "string"
+ }
+ }
+ },
+ "MemoryGraph": {
+ "type": "object",
+ "required": [
+ "nodes",
+ "edges",
+ "truncated"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "memory.graph"
+ },
+ "nodes": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "record",
+ "memory"
+ ],
+ "properties": {
+ "record": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "memory": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "from",
+ "to",
+ "available"
+ ],
+ "properties": {
+ "from": {
+ "$ref": "#/$defs/MemoryRecordRef"
+ },
+ "to": {
+ "$ref": "#/$defs/MemoryRecordRef"
+ },
+ "rel": {
+ "type": "string",
+ "description": "What the reference means. Absent when the target is not readable by the caller."
+ },
+ "available": {
+ "type": "boolean"
+ }
+ }
+ }
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "degraded": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryErase": {
+ "type": "object",
+ "required": [
+ "record_ids"
+ ],
+ "properties": {
+ "record_ids": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "MemoryErasure": {
+ "type": "object",
+ "required": [
+ "erased",
+ "unreachable"
+ ],
+ "properties": {
+ "erased": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "unreachable": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Content the provider could not remove. Empty is a guarantee."
+ }
+ }
+ },
+ "MemoryQuery": {
+ "type": "object",
+ "required": [
+ "body"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "params": {
+ "type": "object",
+ "additionalProperties": true,
+ "description": "A JSON Schema for the parameters."
+ },
+ "requires": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write"
+ ]
+ },
+ "language": {
+ "type": "string",
+ "description": "Opaque to the protocol."
+ },
+ "body": {
+ "type": "string",
+ "description": "Opaque to the protocol."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryQueryList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryQuery"
+ }
+ }
+ }
+ },
+ "MemoryQueryRun": {
+ "type": "object",
+ "properties": {
+ "params": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryFreeQuery": {
+ "type": "object",
+ "required": [
+ "statement"
+ ],
+ "properties": {
+ "language": {
+ "type": "string"
+ },
+ "statement": {
+ "type": "string"
+ },
+ "params": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "write": {
+ "type": "boolean"
+ }
+ }
+ },
+ "MemoryOperationResult": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "result": {}
+ }
+ },
+ "MemorySnapshot": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "at"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.snapshot"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ },
+ "at": {
+ "type": "string"
+ }
+ }
+ },
+ "MemorySnapshotCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
+ "MemorySnapshotList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemorySnapshot"
+ }
+ }
+ }
+ },
+ "MemoryConsolidation": {
+ "type": "object",
+ "required": [
+ "id",
+ "status"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.consolidation"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "queued",
+ "running",
+ "completed",
+ "stopped",
+ "failed"
+ ]
+ },
+ "trigger": {
+ "type": "string"
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "read": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "changes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "usage": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "budget": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "written_by": {
+ "$ref": "#/$defs/MemoryWriter"
+ },
+ "error": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryConsolidationStart": {
+ "type": "object",
+ "properties": {
+ "budget": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryConsolidationList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryConsolidation"
+ }
+ }
+ }
+ },
+ "MemoryProvider": {
+ "type": "object",
+ "required": [
+ "id",
+ "isolation"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "isolation": {
+ "type": "string",
+ "enum": [
+ "container",
+ "enforced_filter"
+ ]
+ },
+ "derivation": {
+ "type": "string",
+ "enum": [
+ "write_time",
+ "background",
+ "agent",
+ "none"
+ ]
+ },
+ "prime": {
+ "type": "boolean",
+ "description": "Whether the provider answers the prime read with its standing records."
+ },
+ "holds": {
+ "type": "boolean",
+ "description": "Whether the provider ends and links facts by `attributes.holds`."
+ },
+ "observe": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "recall": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "history": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "erase": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "queries": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "graph": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "string",
+ "enum": [
+ "derived",
+ "stated",
+ "none"
+ ],
+ "description": "Where a memory's entities come from on this provider."
+ }
+ },
+ "additionalProperties": true
+ },
+ "content": {
+ "type": "object",
+ "description": "What the content of a record may carry on this provider.",
+ "properties": {
+ "media": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Media types kept, as patterns such as `text/*` or `image/*`."
+ },
+ "bytes": {
+ "type": "string",
+ "enum": [
+ "kept",
+ "referenced"
+ ]
+ },
+ "describes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryProviderList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryProvider"
+ }
+ }
+ }
+ },
+ "MemoryType": {
+ "type": "object",
+ "required": [
+ "type"
+ ],
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "core": {
+ "type": "boolean"
+ },
+ "description": {
+ "type": "string"
+ },
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "text": {
+ "type": "string"
+ },
+ "operations": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "name",
+ "requires"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "input": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "requires": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryTypeList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryType"
+ }
+ }
+ }
+ },
+ "HarnessMemorySettings": {
+ "type": "object",
+ "properties": {
+ "default_memory_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Where an unaddressed remember goes and where turns are recorded. A memory the agent may write."
+ },
+ "observe": {
+ "type": "boolean",
+ "description": "Record each finished turn in the default memory. On by default."
+ }
+ }
+ },
+ "HarnessMemories": {
+ "type": "object",
+ "required": [
+ "principal",
+ "data"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "harness.memories"
+ },
+ "principal": {
+ "type": "string",
+ "description": "Who this harness's agent is to the access model, `member:<id>`. A grant names it."
+ },
+ "default_memory_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "observe": {
+ "type": "boolean"
+ },
+ "data": {
+ "type": "array",
+ "description": "Every memory the agent holds a grant on, highest in the tree first. Read off the grants.",
+ "items": {
+ "type": "object",
+ "required": [
+ "id",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write",
+ "create",
+ "delete"
+ ]
+ }
+ },
+ "default": {
+ "type": "boolean"
+ }
+ },
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/protocol/schema/build.py b/protocol/schema/build.py
index 6f3944ad..37258c54 100644
--- a/protocol/schema/build.py
+++ b/protocol/schema/build.py
@@ -25,7 +25,7 @@ except ImportError: # pragma: no cover - environment guidance, not logic
sys.exit("PyYAML is required: pip install pyyaml")
HERE = pathlib.Path(__file__).parent
-VERSION = "2026-10-04"
+VERSION = "2026-10-19"
SRC = HERE / f"uhp-{VERSION}.openapi.yaml"
OUT = HERE / f"uhp-{VERSION}.schema.json"
diff --git a/protocol/schema/uhp-2026-10-19.openapi.yaml b/protocol/schema/uhp-2026-10-19.openapi.yaml
new file mode 100644
index 00000000..cfc01153
--- /dev/null
+++ b/protocol/schema/uhp-2026-10-19.openapi.yaml
@@ -0,0 +1,3173 @@
+openapi: 3.1.0
+info:
+ title: Unified Harness Protocol
+ version: '2026-10-19'
+ summary: An open standard for running complete agent harnesses as shared infrastructure.
+ description: |
+ UHP defines how a product drives a complete agent harness — Codex, Claude Code, Hermes, or any
+ other — over HTTP: selecting and configuring a harness, sending work, following progress,
+ continuing a session, cancelling execution, handling errors and files, and receiving results.
+
+ This document is normative for **structure**. The prose specification in `protocol/versions/`
+ is normative for **behaviour**; where they disagree about behaviour, the prose wins, because
+ behaviour is not expressible in OpenAPI.
+
+ Conformance is defined by the suite in `protocol/conformance/`, not by this document.
+
+ This version is additive to 2026-08-11. It adds plugins (packages of tools and skills in the
+ Agent Plugins format, installed into a harness, with stdio MCP servers inside them), the
+ `plugins` capability, and the error codes those need. Every request and object valid under
+ 2026-08-11 is valid here, and no object 2026-08-11 defined changes shape, so a server serves
+ both versions from one code path.
+ license:
+ name: Apache-2.0
+ identifier: Apache-2.0
+ contact:
+ name: UHP maintainers
+ url: https://github.com/HarnessRouter/harnessrouter
+
+servers:
+ - url: https://your-uhp-server
+ description: Any conformant UHP server. The protocol requires no hosted service.
+ - url: http://127.0.0.1:3000/api/harness
+ description: HarnessRouter Community Edition, default local deployment
+
+security:
+ - bearerAuth: []
+
+tags:
+ - name: Discovery
+ description: Protocol version and capability discovery (conformance class Core)
+ - name: Harnesses
+ description: Discovering, selecting and managing configured harnesses
+ - name: Tasks
+ description: Running work and reading results
+ - name: Sessions
+ description: Continuing, inspecting and cancelling sessions
+ - name: Files
+ description: File input and artifact retrieval (conformance class Extended)
+ - name: Plugins
+ description: Packages of tools and skills installed into a harness (optional capability `plugins`).
+ - name: Environments
+ description: A project's files and installed dependencies, built once and read by every session that names it (optional capability `environments`).
+ - name: Memories
+ description: Memory that outlasts a session, as a tree of memories with access granted per node (optional capability `memories`).
+ description: Packages of tools and skills installed into a harness (capability `plugins`)
+
+paths:
+ /v1/uhp:
+ get:
+ tags: [Discovery]
+ operationId: getDiscovery
+ summary: Protocol discovery document
+ description: |
+ Served without authentication: a client must be able to learn whether it is talking to a UHP
+ server, and which versions it speaks, before presenting credentials. The document contains
+ nothing principal-specific.
+ security: []
+ responses:
+ '200':
+ description: The discovery document
+ headers:
+ UHP-Version: { $ref: '#/components/headers/UHPVersion' }
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Discovery' }
+
+ /v1/harnesses:
+ get:
+ tags: [Harnesses]
+ operationId: listHarnesses
+ summary: List configured harnesses
+ responses:
+ '200':
+ description: Harnesses within the caller's scope. May be empty.
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [harnesses]
+ properties:
+ harnesses:
+ type: array
+ items: { $ref: '#/components/schemas/Harness' }
+ '401': { $ref: '#/components/responses/Unauthorized' }
+ post:
+ tags: [Harnesses]
+ operationId: createHarness
+ summary: Create a configured harness
+ description: Conformance class Full. Check the `harness_management` capability first.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessCreate' }
+ responses:
+ '200':
+ description: The created harness
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Harness' }
+ '401': { $ref: '#/components/responses/Unauthorized' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+
+ /v1/harnesses/{harness_id}:
+ parameters:
+ - $ref: '#/components/parameters/HarnessId'
+ get:
+ tags: [Harnesses]
+ operationId: getHarness
+ summary: Get one harness
+ responses:
+ '200':
+ description: The harness
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Harness' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ put:
+ tags: [Harnesses]
+ operationId: updateHarness
+ summary: Update a harness configuration
+ description: |
+ Conformance class Full. `id`, `base` and `createdAt` are immutable — changing the base of an
+ existing harness would silently change the behaviour of every session attached to it.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessCreate' }
+ responses:
+ '200':
+ description: The updated harness
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Harness' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Harnesses]
+ operationId: deleteHarness
+ summary: Delete (retire) a harness
+ description: |
+ A server whose `harness_retirement` capability is `false` keeps the sessions and responses
+ that used the harness. One that reports it `true` retires them with the harness, restorable
+ until `restorableUntil` and removable only after it. See Harnesses §5.3.
+ responses:
+ '200':
+ description: Deleted
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ deleted: { type: boolean }
+ sessions:
+ type: string
+ enum: [kept, retired]
+ description: |
+ What happened to the sessions and responses that used the harness. Absent
+ means `kept`. `retired` requires `restorableUntil`.
+ restorableUntil:
+ type: integer
+ description: |
+ Unix seconds. Until then a restore of the harness brings its sessions and
+ responses back; after it they may be removed for good. Present when
+ `sessions` is `retired`.
+ '404': { $ref: '#/components/responses/NotFound' }
+ '409':
+ description: |
+ `harness_busy`: the harness retires its sessions with it and has a task in progress. A
+ server either cancels the task first or refuses with this; it never retires mid-task.
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+
+ /v1/harnesses/{harness_id}/skills/{skill_name}/files:
+ parameters:
+ - $ref: '#/components/parameters/HarnessId'
+ - $ref: '#/components/parameters/SkillName'
+ get:
+ tags: [Harnesses]
+ operationId: getSkillFiles
+ summary: The complete file list of one skill
+ description: |
+ Conformance class Full. Whether or not the server stores the bundle out of line, this returns
+ every file of the skill folder, byte-for-byte.
+ responses:
+ '200':
+ description: The skill's files
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/FileList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/harnesses/{harness_id}/plugins/{plugin_name}/files:
+ parameters:
+ - $ref: '#/components/parameters/HarnessId'
+ - $ref: '#/components/parameters/PluginName'
+ get:
+ tags: [Plugins]
+ operationId: getPluginFiles
+ summary: The complete package of one installed plugin
+ description: |
+ Conformance class Full, capability `plugins`. Every file of the package, byte-for-byte, whether
+ or not the server stores it out of line. `404` with `plugin_not_found` when the harness has no
+ plugin of that name.
+ responses:
+ '200':
+ description: The plugin's files
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/FileList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/harnesses/{harness_id}/plugin:
+ parameters:
+ - $ref: '#/components/parameters/HarnessId'
+ get:
+ tags: [Plugins]
+ operationId: exportHarnessPlugin
+ summary: The harness's own tools and skills as an Agent Plugins package
+ description: |
+ Conformance class Full, capability `plugins`. Builds a package from the harness's direct
+ `mcpServers` and `skills`: a `plugin.json` whose name derives from the harness name, an
+ `mcp.json` of the enabled servers with `auth` and `headers` omitted (each omission recorded in
+ `skipped`), and each enabled skill folder. Installed plugins, the system prompt, the model,
+ the base and `disabledTools` are not included. The result installs into another harness by
+ passing it to `plugins` unchanged.
+ responses:
+ '200':
+ description: The package
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Plugin' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/environments:
+ get:
+ tags: [Environments]
+ operationId: listEnvironments
+ summary: The caller's environments
+ description: Conformance class Full, capability `environments`. Scoped like harnesses.
+ responses:
+ '200':
+ description: The list
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentList' }
+ post:
+ tags: [Environments]
+ operationId: createEnvironment
+ summary: Create an environment
+ description: |
+ An empty environment with a name; its slug (the path sessions see) derives from the name and
+ cannot change afterwards. `environment_exists` when another environment already occupies
+ that path; `environment_invalid` when the name yields no path segment.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentCreate' }
+ responses:
+ '200':
+ description: The environment
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Environment' }
+ '409': { $ref: '#/components/responses/Conflict' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+
+ /v1/environments/runtimes:
+ get:
+ tags: [Environments]
+ operationId: listEnvironmentRuntimes
+ summary: The runtimes a build can be made with here
+ responses:
+ '200':
+ description: The runtimes
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentRuntimes' }
+
+ /v1/environments/packages/check:
+ get:
+ tags: [Environments]
+ operationId: checkEnvironmentPackage
+ summary: What the manager's registry says about a spec, before any build
+ description: |
+ Optional (a server without it answers 404). Whether the name exists, its latest version,
+ and whether an exact pin is published, so a client can refuse a typo where it is typed.
+ `environment_invalid` for a manager other than pip, npm or apt, or a string that is not a spec.
+ parameters:
+ - { name: manager, in: query, required: true, schema: { type: string, enum: [pip, npm, apt] } }
+ - { name: spec, in: query, required: true, schema: { type: string }, description: "A spec as the build takes it: numpy, numpy==2.3.1, [email protected], ffmpeg" }
+ responses:
+ '200':
+ description: The registry's answer
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentPackageCheck' }
+ '400': { $ref: '#/components/responses/BadRequest' }
+
+ /v1/environments/{environment_id}:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ get:
+ tags: [Environments]
+ operationId: getEnvironment
+ summary: One environment, with its versions and the active build's packages
+ responses:
+ '200':
+ description: The environment
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Environment' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ put:
+ tags: [Environments]
+ operationId: updateEnvironment
+ summary: Rename, or change the description or entry
+ description: The slug stays; a session's instructions name it.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentCreate' }
+ responses:
+ '200':
+ description: The environment
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Environment' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Environments]
+ operationId: deleteEnvironment
+ summary: Delete the environment and every version of it
+ description: |
+ Refused with `environment_busy` while a build runs. Harnesses that named it keep the
+ reference; their next task is refused with `environment_not_found`.
+ responses:
+ '200':
+ description: Deleted
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ deleted: { type: boolean, const: true }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '409': { $ref: '#/components/responses/Conflict' }
+
+ /v1/environments/{environment_id}/files:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ get:
+ tags: [Environments]
+ operationId: listEnvironmentFiles
+ summary: The source tree
+ description: What the owner put in, every file and directory with its size. Not the built layer.
+ responses:
+ '200':
+ description: The tree
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentFileList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/environments/{environment_id}/files/{path}:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ - $ref: '#/components/parameters/EnvironmentPath'
+ get:
+ tags: [Environments]
+ operationId: getEnvironmentFile
+ summary: One file's bytes
+ responses:
+ '200':
+ description: The file, with its content type
+ content:
+ '*/*':
+ schema: { type: string, format: binary }
+ '404': { $ref: '#/components/responses/NotFound' }
+ put:
+ tags: [Environments]
+ operationId: putEnvironmentFile
+ summary: Write one file
+ description: |
+ The body is the file's bytes; the directories on its path are made. A server MUST reject a
+ path that escapes the root with `environment_invalid`, and an oversized file with
+ `file_too_large` rather than truncating it. Writing the source changes nothing a session
+ sees until the next build. An empty directory is made with `POST …/directories`.
+ requestBody:
+ required: true
+ content:
+ '*/*':
+ schema: { type: string, format: binary }
+ responses:
+ '200':
+ description: Written
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ path: { type: string }
+ bytes: { type: integer }
+ dir: { type: boolean }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '413': { $ref: '#/components/responses/PayloadTooLarge' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+ delete:
+ tags: [Environments]
+ operationId: deleteEnvironmentFile
+ summary: Remove a file or a directory tree
+ responses:
+ '200':
+ description: Removed
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ path: { type: string }
+ deleted: { type: boolean }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/environments/{environment_id}/directories:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ post:
+ tags: [Environments]
+ operationId: makeEnvironmentDirectory
+ summary: Make an empty directory
+ description: Its own request rather than a trailing slash on a file path, which a proxy may normalise away.
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [path]
+ properties:
+ path: { type: string, description: Relative to the environment's root. }
+ responses:
+ '200':
+ description: Made
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ path: { type: string }
+ dir: { type: boolean, const: true }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+
+ /v1/environments/{environment_id}/import:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ post:
+ tags: [Environments]
+ operationId: importEnvironment
+ summary: Import a whole project, keeping its tree
+ description: |
+ Either an archive (zip or tar) as the body, or a JSON body naming a git repository. A single
+ directory wrapping everything (the shape of a repository archive) is stripped. Members that
+ must not land (links, paths that escape the root) are dropped and counted in `skipped`, never
+ written. `?replace=1` clears the source first. Dependency directories in the archive
+ (`node_modules`, `.venv`) are not what a build installs: the build installs from the
+ manifests, in the server's own toolchain.
+ parameters:
+ - name: replace
+ in: query
+ schema: { type: integer, enum: [0, 1], default: 0 }
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentImport' }
+ '*/*':
+ schema: { type: string, format: binary }
+ responses:
+ '200':
+ description: What landed
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentImportResult' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '413': { $ref: '#/components/responses/PayloadTooLarge' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+
+ /v1/environments/{environment_id}/build:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ post:
+ tags: [Environments]
+ operationId: buildEnvironment
+ summary: Build a new version from the source
+ description: |
+ Snapshots the source into the next version, installs what its manifests declare
+ (`requirements.txt`, `pyproject.toml`, `package.json`, then `setup.sh` when present), and
+ makes the version the active one when it succeeds. Returns at once; poll the build. One
+ build at a time per environment (`environment_busy`). Sessions started before the build
+ finishes keep reading the version they started with.
+ responses:
+ '200':
+ description: The build started
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentBuild' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '409': { $ref: '#/components/responses/Conflict' }
+
+ /v1/environments/{environment_id}/builds/{version}:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ - $ref: '#/components/parameters/BuildVersion'
+ get:
+ tags: [Environments]
+ operationId: getEnvironmentBuild
+ summary: A build's record, log included
+ responses:
+ '200':
+ description: The build
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/EnvironmentBuild' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/environments/{environment_id}/versions:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ get:
+ tags: [Environments]
+ operationId: listEnvironmentVersions
+ summary: Every build, and which one is active
+ responses:
+ '200':
+ description: The versions
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ active: { type: [integer, 'null'] }
+ versions: { type: array, items: { $ref: '#/components/schemas/EnvironmentVersion' } }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/environments/{environment_id}/versions/{version}/activate:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ - $ref: '#/components/parameters/BuildVersion'
+ post:
+ tags: [Environments]
+ operationId: activateEnvironmentVersion
+ summary: Make an older build the active one
+ description: Rollback by pointer; nothing is rebuilt. Only a finished build can be activated (`environment_not_ready`).
+ responses:
+ '200':
+ description: The environment, with its new active version
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Environment' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '409': { $ref: '#/components/responses/Conflict' }
+
+ /v1/environments/{environment_id}/harnesses:
+ parameters:
+ - $ref: '#/components/parameters/EnvironmentId'
+ get:
+ tags: [Environments]
+ operationId: listEnvironmentHarnesses
+ summary: The harnesses that read this environment
+ responses:
+ '200':
+ description: The harnesses, id, name and base each
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ harnesses:
+ type: array
+ items:
+ type: object
+ properties:
+ id: { type: string }
+ name: { type: string }
+ base: { type: string }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories:
+ get:
+ parameters:
+ - { name: parent, in: query, schema: { type: string } }
+ - { name: ancestor, in: query, schema: { type: string } }
+ - { name: granted, in: query, schema: { type: boolean }, description: 'What the caller was given: every memory it may read whose parent it cannot see, and every memory below those on which its privileges differ from its privileges on the parent, highest in the tree first.' }
+ tags: [Memories]
+ operationId: listMemories
+ summary: "The memories a caller may see, one level at a time"
+ description: "Conformance class Full, capability `memories`. Without `parent`, where the caller enters the tree. A memory the caller holds no privilege on is never listed."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: createMemory
+ summary: "Create a memory"
+ description: "Needs `create` on the parent when one is named."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryCreate' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Memory' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/providers:
+ get:
+ tags: [Memories]
+ operationId: listMemoryProviders
+ summary: "What each connected provider does"
+ description: "The capability documents of the providers this server is connected to."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryProviderList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/types:
+ get:
+ tags: [Memories]
+ operationId: listMemoryTypes
+ summary: "The record types this server understands"
+ description: "The core types, and the extension types its providers register with their operations."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryTypeList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: getMemory
+ summary: "One memory"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Memory' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ put:
+ tags: [Memories]
+ operationId: updateMemory
+ summary: "Rename, describe, restrict or move a memory"
+ description: "Needs `write`; changing `restricted` or `parent_id` needs `delete`."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryUpdate' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Memory' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Memories]
+ operationId: deleteMemory
+ summary: "Delete a memory, its records and its descendants"
+ description: "Needs `delete`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryDeleted' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/grants:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: listMemoryGrants
+ summary: "Who holds what on this memory"
+ description: "Needs `delete`. Each grant names the node it sits on."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryGrantList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: createMemoryGrant
+ summary: "Grant a principal privileges on this memory"
+ description: "Needs `delete`. One grant per principal per node; a second replaces it."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryGrantCreate' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryGrant' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/grants/{grant_id}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: grant_id, in: path, required: true, schema: { type: string } }
+ delete:
+ tags: [Memories]
+ operationId: deleteMemoryGrant
+ summary: "Revoke a grant"
+ description: "Needs `delete`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Deleted' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/observe:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ post:
+ tags: [Memories]
+ operationId: observeMemory
+ summary: "Append episodes; the provider decides what to derive"
+ description: "Needs `write`. Answers `202` with a job when the provider derives after it answers."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryObserve' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordList' }
+ '202':
+ description: Taken; the records are read from the job
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/jobs/{job_id}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: job_id, in: path, required: true, schema: { type: string } }
+ get:
+ tags: [Memories]
+ operationId: getMemoryJob
+ summary: "What an observe that answered 202 has written since"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryJob' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/prime:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: primeMemory
+ summary: "The memory's standing records, newest first, within a token budget"
+ description: "Needs `read`. The memory alone unless `depth` widens it."
+ parameters:
+ - { name: budget, in: query, schema: { type: integer, minimum: 1 } }
+ - { name: depth, in: query, schema: { type: integer, minimum: 0 } }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryPrime' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/records:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ parameters:
+ - { name: type, in: query, schema: { type: string } }
+ - { name: as_of, in: query, schema: { type: string } }
+ - { name: include, in: query, schema: { type: string, enum: [active, all] } }
+ - { name: limit, in: query, schema: { type: integer } }
+ - { name: cursor, in: query, schema: { type: string } }
+ tags: [Memories]
+ operationId: listMemoryRecords
+ summary: "The records of one memory"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: rememberRecord
+ summary: "Write one record as stated"
+ description: "Needs `write`. `written_by` is stamped by the server."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordCreate' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecord' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/records/{record_id}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - $ref: '#/components/parameters/MemoryRecordId'
+ get:
+ parameters:
+ - { name: as_of, in: query, schema: { type: string } }
+ tags: [Memories]
+ operationId: getMemoryRecord
+ summary: "One record"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecord' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ patch:
+ tags: [Memories]
+ operationId: reviseMemoryRecord
+ summary: "Revise a record; the earlier version is kept"
+ description: "Needs `write`."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordRevise' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecord' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Memories]
+ operationId: forgetMemoryRecord
+ summary: "Close a record; its place in the history remains"
+ description: "Needs `write`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecord' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/records/{record_id}/content/{index}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - $ref: '#/components/parameters/MemoryRecordId'
+ - { name: index, in: path, required: true, schema: { type: integer, minimum: 0 } }
+ get:
+ tags: [Memories]
+ operationId: getMemoryRecordFile
+ summary: "The bytes of one file part of a record"
+ description: "Needs `read`. A part that is not a file answers 404."
+ responses:
+ '200':
+ description: The bytes, under the media type of the file
+ content:
+ application/octet-stream:
+ schema: { type: string, format: binary }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/records/{record_id}/history:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - $ref: '#/components/parameters/MemoryRecordId'
+ get:
+ tags: [Memories]
+ operationId: getMemoryRecordHistory
+ summary: "The versions of a record, oldest first"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/records/{record_id}/operations/{name}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - $ref: '#/components/parameters/MemoryRecordId'
+ - { name: name, in: path, required: true, schema: { type: string } }
+ post:
+ tags: [Memories]
+ operationId: operateMemoryRecord
+ summary: "Run an operation a record's type offers"
+ description: "Needs the privilege the operation declares."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/FreeObject' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryOperationResult' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/recall:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ post:
+ tags: [Memories]
+ operationId: recallMemory
+ summary: "Search a memory and what is below it by meaning, words and fields"
+ description: "Needs `read`. Covers this memory and every descendant the caller may read, never an ancestor; each result names the memory it is in, and the answer names the parent and children of the memory asked."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecallRequest' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecall' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/graph:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ post:
+ tags: [Memories]
+ operationId: graphMemory
+ summary: "Records as nodes and their references as edges"
+ description: "Needs `read`. Around one record or for the whole memory. Entities are records of type `entity`; a relationship with something to say is a `fact` that references its `subject` and its `object`. A target the caller may not read is an edge marked unavailable and never a node."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryGraphRequest' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryGraph' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/erase:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ post:
+ tags: [Memories]
+ operationId: eraseMemoryRecords
+ summary: "Remove content for good, and say what could not be reached"
+ description: "Needs `delete`. Never offered to an agent."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryErase' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryErasure' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/queries:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: listMemoryQueries
+ summary: "The named queries of a memory"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryQueryList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/queries/{name}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: name, in: path, required: true, schema: { type: string } }
+ put:
+ tags: [Memories]
+ operationId: defineMemoryQuery
+ summary: "Define or replace a named query in the provider's language"
+ description: "Needs `write`."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryQuery' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryQuery' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: runMemoryQuery
+ summary: "Run a named query"
+ description: "Needs the privilege the query declares."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryQueryRun' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecall' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/query:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ post:
+ tags: [Memories]
+ operationId: freeMemoryQuery
+ summary: "Run a query the caller wrote, inside this memory"
+ description: "Offered only where the provider declares `queries.free`. The provider confines it by a means the statement cannot undo."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryFreeQuery' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecall' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/snapshots:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: listMemorySnapshots
+ summary: "The named instants of a memory"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemorySnapshotList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: createMemorySnapshot
+ summary: "Name the present instant"
+ description: "Needs `write`. Copies nothing."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemorySnapshotCreate' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemorySnapshot' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/consolidations:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ get:
+ tags: [Memories]
+ operationId: listMemoryConsolidations
+ summary: "Consolidation runs, newest first"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryConsolidationList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ post:
+ tags: [Memories]
+ operationId: startMemoryConsolidation
+ summary: "Start a consolidation run now"
+ description: "Needs `write`."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryConsolidationStart' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryConsolidation' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/consolidations/{run_id}:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: run_id, in: path, required: true, schema: { type: string } }
+ get:
+ tags: [Memories]
+ operationId: getMemoryConsolidation
+ summary: "One consolidation run"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryConsolidation' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/consolidations/{run_id}/changes:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: run_id, in: path, required: true, schema: { type: string } }
+ get:
+ tags: [Memories]
+ operationId: listMemoryConsolidationChanges
+ summary: "The records a run wrote, superseded or forgot"
+ description: "Needs `read`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryRecordList' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/memories/{memory_id}/consolidations/{run_id}/revert:
+ parameters:
+ - $ref: '#/components/parameters/MemoryId'
+ - { name: run_id, in: path, required: true, schema: { type: string } }
+ post:
+ tags: [Memories]
+ operationId: revertMemoryConsolidation
+ summary: "Revert a run by appending"
+ description: "Needs `delete`. History keeps the run and its reversal."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/MemoryConsolidation' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/harnesses/{harness_id}/memories:
+ parameters:
+ - { name: harness_id, in: path, required: true, schema: { type: string } }
+ get:
+ tags: [Memories]
+ operationId: listHarnessMemories
+ summary: "What a harness's agent was granted, and the harness's two memory settings"
+ description: "Capability `memories`."
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessMemories' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ put:
+ tags: [Memories]
+ operationId: setHarnessMemories
+ summary: "Set where the agent writes by default and whether its turns are recorded"
+ description: "Access is not set here: an agent is a member and is granted on the memory."
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessMemorySettings' }
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessMemories' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/models:
+ get:
+ tags: [Harnesses]
+ operationId: listModels
+ summary: The model catalogue, by backend
+ responses:
+ '200':
+ description: Models grouped by backend, each with computed availability
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ModelCatalog' }
+ '401': { $ref: '#/components/responses/Unauthorized' }
+
+ /v1/harnesses/{harness_id}/models:
+ parameters:
+ - $ref: '#/components/parameters/HarnessId'
+ get:
+ tags: [Harnesses]
+ operationId: listHarnessModels
+ summary: Models this harness can run
+ responses:
+ '200':
+ description: The harness's allowed models, default and authorized fallback
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/HarnessModels' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/responses:
+ post:
+ tags: [Tasks]
+ operationId: createResponse
+ summary: Run a task
+ description: |
+ The core of the protocol. With `stream: false` the server returns one Response object when
+ the task reaches a terminal state. With `stream: true` it returns `text/event-stream`
+ carrying the events defined in the Streaming chapter.
+
+ Retries MUST carry `Idempotency-Key`: without one, a retry after a timeout runs the task a
+ second time while the first may still be running.
+ parameters:
+ - name: Idempotency-Key
+ in: header
+ required: false
+ schema: { type: string, maxLength: 255 }
+ description: Repeating a key returns the first request's result and does not re-execute.
+ - name: UHP-Version
+ in: header
+ required: false
+ schema: { type: string, examples: ['2026-08-11'] }
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/CreateResponseRequest' }
+ responses:
+ '200':
+ description: |
+ The finished Response (non-streaming), or the event stream (streaming).
+ headers:
+ UHP-Version: { $ref: '#/components/headers/UHPVersion' }
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Response' }
+ text/event-stream:
+ schema:
+ type: string
+ description: SSE; each `data:` line is one Event object.
+ '401': { $ref: '#/components/responses/Unauthorized' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '409': { $ref: '#/components/responses/Conflict' }
+ '422': { $ref: '#/components/responses/UnprocessableEntity' }
+ '429': { $ref: '#/components/responses/RateLimited' }
+
+ /v1/responses/{response_id}:
+ parameters:
+ - $ref: '#/components/parameters/ResponseId'
+ get:
+ tags: [Tasks]
+ operationId: getResponse
+ summary: Read a task back
+ responses:
+ '200':
+ description: The Response
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Response' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Tasks]
+ operationId: deleteResponse
+ summary: Delete a stored response
+ description: Must not cancel a running task — deletion and cancellation are different intentions.
+ responses:
+ '200':
+ description: Deleted
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ deleted: { type: boolean }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/responses/{response_id}/input_items:
+ parameters:
+ - $ref: '#/components/parameters/ResponseId'
+ get:
+ tags: [Tasks]
+ operationId: getResponseInputItems
+ summary: The input the task was created with
+ responses:
+ '200':
+ description: Input items
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ object: { type: string, const: list }
+ data: { type: array, items: { type: object, additionalProperties: true } }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/responses/{response_id}/cancel:
+ parameters:
+ - $ref: '#/components/parameters/ResponseId'
+ post:
+ tags: [Sessions]
+ operationId: cancelResponse
+ summary: Cancel a running task
+ description: |
+ Idempotent. Cancelling an already-terminal task succeeds and changes nothing — a client
+ retrying a cancel after a dropped connection must not be punished for having succeeded.
+ responses:
+ '200':
+ description: The Response, now cancelling or terminal
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Response' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/sessions:
+ get:
+ tags: [Sessions]
+ operationId: listSessions
+ summary: List sessions
+ description: Conformance class Extended.
+ parameters:
+ - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+ - { name: cursor, in: query, schema: { type: string } }
+ - { name: harness, in: query, schema: { type: string }, description: Filter by harness id }
+ responses:
+ '200':
+ description: A page of sessions
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/SessionList' }
+ '401': { $ref: '#/components/responses/Unauthorized' }
+
+ /v1/sessions/{session_id}:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ get:
+ tags: [Sessions]
+ operationId: getSession
+ summary: Get one session
+ responses:
+ '200':
+ description: The session
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/Session' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/sessions/{session_id}/turns:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ get:
+ tags: [Sessions]
+ operationId: getSessionTurns
+ summary: The ordered task history of a session
+ responses:
+ '200':
+ description: Turns, oldest first
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ turns: { type: array, items: { $ref: '#/components/schemas/TurnItem' } }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/sessions/{session_id}/share:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ post:
+ tags: [Sessions]
+ operationId: shareSession
+ summary: Publish a read-only view of the session (Sessions §5, class Full)
+ description: |
+ A body is OPTIONAL; no body means publish. A server MAY accept `{"enabled": bool}` as a
+ toggle. Sharing itself is a MAY; a server that does not implement it answers 404/405/501.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ enabled: { type: boolean, default: true }
+ additionalProperties: true
+ responses:
+ '200':
+ description: The share
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/SessionShare' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ get:
+ tags: [Sessions]
+ operationId: getSessionShare
+ summary: Read the session's share back
+ responses:
+ '200':
+ description: The share, agreeing with what POST published
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/SessionShare' }
+ '404': { $ref: '#/components/responses/NotFound' }
+ delete:
+ tags: [Sessions]
+ operationId: revokeSessionShare
+ summary: Revoke — every link minted for the session stops resolving
+ responses:
+ '200':
+ description: Revoked
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/SessionShare' }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/sessions/{session_id}/cancel:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ post:
+ tags: [Sessions]
+ operationId: cancelSession
+ summary: Cancel whatever is running in a session
+ responses:
+ '200':
+ description: Accepted
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ id: { type: string }
+ status: { type: string }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/files:
+ post:
+ tags: [Files]
+ operationId: uploadFile
+ summary: Upload a file for use as task input
+ description: Conformance class Extended.
+ requestBody:
+ required: true
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ required: [file]
+ properties:
+ file: { type: string, format: binary }
+ purpose: { type: string, default: user_data }
+ responses:
+ '200':
+ description: The stored file
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/File' }
+ '413': { $ref: '#/components/responses/PayloadTooLarge' }
+
+ /v1/sessions/{session_id}/files:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ get:
+ tags: [Files]
+ operationId: listSessionFiles
+ summary: Every artifact of a session
+ description: Must include artifacts from earlier tasks, not only the most recent.
+ responses:
+ '200':
+ description: Artifacts
+ content:
+ application/json:
+ schema:
+ type: object
+ required: [files]
+ properties:
+ files: { type: array, items: { $ref: '#/components/schemas/File' } }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/sessions/{session_id}/files/archive:
+ parameters:
+ - $ref: '#/components/parameters/SessionId'
+ get:
+ tags: [Files]
+ operationId: downloadSessionArchive
+ summary: Every artifact as one archive
+ responses:
+ '200':
+ description: An archive of the session's artifacts
+ content:
+ application/zip:
+ schema: { type: string, format: binary }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/containers/{container_id}/files/{file_id}/content:
+ parameters:
+ - $ref: '#/components/parameters/ContainerId'
+ - $ref: '#/components/parameters/FileId'
+ get:
+ tags: [Files]
+ operationId: downloadFile
+ summary: Download an artifact
+ description: |
+ Returns raw bytes with the file's own media type — never JSON-wrapped. Servers must send
+ `X-Content-Type-Options: nosniff`: artifacts are attacker-influenceable content, and serving
+ them without it turns an artifact into stored XSS against the client's origin.
+ responses:
+ '200':
+ description: The bytes
+ headers:
+ Content-Disposition:
+ schema: { type: string }
+ X-Content-Type-Options:
+ required: true
+ schema: { type: string, const: nosniff }
+ content:
+ '*/*':
+ schema: { type: string, format: binary }
+ '404': { $ref: '#/components/responses/NotFound' }
+
+ /v1/containers/{container_id}/files/{file_id}/pdf:
+ parameters:
+ - $ref: '#/components/parameters/ContainerId'
+ - $ref: '#/components/parameters/FileId'
+ get:
+ tags: [Files]
+ operationId: previewFile
+ summary: A rendered PDF preview of a document artifact
+ responses:
+ '200':
+ description: The rendered PDF
+ content:
+ application/pdf:
+ schema: { type: string, format: binary }
+ '404': { $ref: '#/components/responses/NotFound' }
+ '501':
+ description: This server does not implement preview conversion
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ '502':
+ description: Conversion of this file failed
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+
+components:
+ securitySchemes:
+ bearerAuth:
+ type: http
+ scheme: bearer
+ description: How tokens are issued is out of scope for this protocol.
+
+ headers:
+ UHPVersion:
+ description: The protocol version actually used to serve this response.
+ required: true
+ schema: { type: string, examples: ['2026-08-11'] }
+
+ parameters:
+ MemoryId:
+ name: memory_id
+ in: path
+ required: true
+ schema: { type: string }
+ MemoryRecordId:
+ name: record_id
+ in: path
+ required: true
+ schema: { type: string }
+ EnvironmentId:
+ name: environment_id
+ in: path
+ required: true
+ schema: { type: string, pattern: '^henv_' }
+ EnvironmentPath:
+ name: path
+ in: path
+ required: true
+ description: A path relative to the environment's root. A trailing slash names a directory.
+ schema: { type: string }
+ BuildVersion:
+ name: version
+ in: path
+ required: true
+ schema: { type: integer, minimum: 1 }
+ HarnessId:
+ name: harness_id
+ in: path
+ required: true
+ schema: { type: string, pattern: '^chrn_' }
+ SkillName:
+ name: skill_name
+ in: path
+ required: true
+ schema: { type: string }
+ PluginName:
+ name: plugin_name
+ in: path
+ required: true
+ schema: { type: string }
+ ResponseId:
+ name: response_id
+ in: path
+ required: true
+ schema: { type: string, pattern: '^resp_' }
+ SessionId:
+ name: session_id
+ in: path
+ required: true
+ schema: { type: string }
+ ContainerId:
+ name: container_id
+ in: path
+ required: true
+ schema: { type: string }
+ FileId:
+ name: file_id
+ in: path
+ required: true
+ schema: { type: string }
+
+ responses:
+ Unauthorized:
+ description: Missing, malformed or unknown credential
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ NotFound:
+ description: |
+ No such object in the caller's scope. Servers return 404 rather than 403 for objects outside
+ the caller's scope, so that an id's existence is not disclosed.
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ Conflict:
+ description: '`session_busy` or `harness_mismatch`'
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ UnprocessableEntity:
+ description: '`model_unavailable` or `unsupported_base`'
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ PayloadTooLarge:
+ description: '`file_too_large`'
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+ RateLimited:
+ description: '`rate_limited` or `quota_exhausted`'
+ headers:
+ Retry-After:
+ schema: { type: string }
+ content:
+ application/json:
+ schema: { $ref: '#/components/schemas/ErrorEnvelope' }
+
+ schemas:
+ 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: '#/components/schemas/Capabilities' }
+ plugin_schemas:
+ type: array
+ items: { type: string, format: uri }
+ description: |
+ The Agent Plugins manifest schema identifiers this server installs. Present and non-empty
+ when `capabilities.plugins` is true.
+ 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
+ omitting it, so a client can distinguish "not supported" from "server predates this field".
+ A client treats an absent key as `false`.
+ 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 }
+ harness_retirement:
+ type: boolean
+ description: |
+ Retiring a harness retires its sessions and responses with it, restorable until a time
+ the delete response states (`restorableUntil`) and removed after it. `false`, or absent:
+ they are kept. See Harnesses §5.3.
+ session_sharing: { type: boolean }
+ idempotency: { type: boolean }
+ plugins:
+ type: boolean
+ description: |
+ The server installs Agent Plugins packages into harnesses, serves their files, and exports
+ a harness as a package. Optional at every class.
+ environments:
+ type: boolean
+ description: |
+ The server holds environments: a project's files and installed dependencies, built once,
+ read-only at a fixed path in every session that names one. Optional at every class.
+ memories:
+ type: boolean
+ description: |
+ The server holds memories: a tree of memories with access granted per node, records kept
+ by a connected provider, and tools a harness's agent reaches them with. Optional at every class.
+ 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
+ protocol would need revising every time a harness is released.
+ examples: [codex, claude-code, hermes]
+ baseLabel: { type: string }
+ defaultModel: { type: string }
+ systemPrompt: { type: string }
+ mcpServers: { type: array, items: { $ref: '#/components/schemas/McpServer' } }
+ skills: { type: array, items: { $ref: '#/components/schemas/Skill' } }
+ plugins:
+ type: array
+ items: { $ref: '#/components/schemas/Plugin' }
+ description: |
+ Installed plugins. Their servers and skills join the harness's own for every turn;
+ `mcpServers` and `skills` above report only what was written to them directly.
+ environment:
+ type: string
+ description: |
+ The environment (`henv_`) this harness's tasks read, mounted read-only at its `mount`;
+ empty when none. A task may name another with its own `environment` field.
+ 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
+ disabled entry must not be contacted at all. An unreachable server must not fail the task.
+ Unchanged from 2026-08-11: a process (stdio) server is declared inside a plugin, see
+ PluginMcpServer.
+ 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
+ a resolved credential to a client.
+ 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
+ object plus the `stdio` transport: `url` is required for `http` and `sse`, `command` for
+ `stdio`. Placeholders are reported unexpanded; `enabled` is always true, the plugin's own
+ `enabled` governs.
+ 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
+ transport; `stdio` a process the server launches inside the agent's sandbox.
+ 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
+ plugin-relative path beginning with `./`. Never a shell string, never expanded.
+ 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
+ those. Values expand at run time.
+ cwd:
+ type: string
+ description: |
+ Working directory (`stdio`). Defaults to the plugin root; must stay within the plugin
+ root or PLUGIN_DATA.
+ 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
+ can read it — materialising only SKILL.md breaks every skill carrying references, scripts or
+ data. Round-tripping a harness through GET and PUT must not lose skill contents.
+ 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: '#/components/schemas/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
+ back unchanged, and reads the files from the skill files endpoint.
+ 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
+ supported. A server must reject a path that escapes the folder.
+ 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: '#/components/schemas/SkillFile' }
+
+ Plugin:
+ type: object
+ required: [name]
+ description: |
+ An Agent Plugins package installed into a harness: `plugin.json` at the root, MCP servers in
+ `mcp.json`, skills under `skills/`. A client writes `files` (or passes back `blob`) and
+ optionally `name` and `enabled`; the server derives `manifest`, `mcpServers`, `skills` and
+ `skipped` from the package on every write and ignores those fields on input. A refused
+ package leaves the harness unchanged.
+ 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: '#/components/schemas/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
+ and reads the files from the plugin files endpoint.
+ manifest: { $ref: '#/components/schemas/PluginManifest' }
+ mcpServers:
+ type: array
+ items: { $ref: '#/components/schemas/PluginMcpServer' }
+ description: |
+ Derived from `mcp.json`. Placeholders are reported unexpanded; `enabled` is always true,
+ the plugin's own `enabled` governs.
+ skills:
+ type: array
+ items: { $ref: '#/components/schemas/PluginSkill' }
+ description: Derived from `skills/`, one entry per immediate child directory with a SKILL.md.
+ skipped:
+ type: array
+ items: { $ref: '#/components/schemas/PluginSkipped' }
+ description: |
+ What the server found and could not load. Present on every plugin object the server
+ returns, empty when nothing was skipped.
+ additionalProperties: true
+
+ PluginManifest:
+ type: object
+ required: ['$schema', name]
+ description: |
+ `plugin.json`, parsed. Mirrors the Agent Plugins 1.0.0 manifest schema
+ (https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, Apache-2.0) field for field, and
+ permits additional properties because a UHP client ignores fields it does not know. The
+ schema a manifest's own `$schema` names is authoritative; a server validates against that.
+ 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. }
+ 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: '#/components/schemas/McpServer' } }
+ skills: { type: array, items: { $ref: '#/components/schemas/Skill' } }
+ plugins:
+ type: array
+ items: { $ref: '#/components/schemas/Plugin' }
+ description: Requires the `plugins` capability. Each item needs `files` or `blob`.
+ environment: { type: string, description: An environment id of the caller's scope, or empty. Requires the `environments` capability. }
+ 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: '#/components/schemas/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: '#/components/schemas/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
+ now. Listing a model as available and then failing the task is the worst outcome for a
+ client, because a user has already chosen it.
+ 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, the extension point of the Responses surface. `harness_id` selects the
+ configured harness; `environment` names the environment this task reads, overriding the
+ harness's (capability `environments`), refused with `environment_not_found` or
+ `environment_not_ready` before the task starts.
+ properties:
+ harness_id: { type: string }
+ environment: { 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
+ `metadata.ignored_fields` on the response. A UHP harness invokes and executes tools
+ itself and reports them in `output`; there is no input path for a tool result, so the
+ client-executed tool loop this field implies cannot be completed by a conformant server.
+ Configure tools on the harness instead — see Harnesses §4.1. Tasks §1.4.
+ include:
+ type: array
+ items: { type: string }
+ description: |
+ Reserved and ignored. Accepted for wire compatibility, never acted on, and reported in
+ `metadata.ignored_fields` on the response. No values are enumerated, so any string a
+ server recognised would be one it named itself. Tasks §1.4.
+ 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: '#/components/schemas/ResponseStatus' }
+ error:
+ oneOf:
+ - type: 'null'
+ - $ref: '#/components/schemas/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: '#/components/schemas/OutputItem' }
+ store: { type: boolean }
+ usage:
+ oneOf:
+ - type: 'null'
+ - $ref: '#/components/schemas/Usage'
+ description: |
+ null when the server cannot account for usage. A fabricated zero would be worse than an
+ honest absence, because a client cannot tell it from a free task.
+ metadata:
+ type: object
+ properties:
+ session_id: { type: string }
+ environment:
+ type: string
+ description: The environment the task read, when it read one (capability `environments`).
+ 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
+ request carried `tools` or `include`, which are reserved and ignored. A silently
+ ignored field is indistinguishable from an honoured one. Tasks §1.1 and §1.4.
+ 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.
+ `failed` means it could not be done. `cancelled` means the client asked for a stop, and must
+ never be reported as `failed`.
+
+ OutputItem:
+ type: object
+ required: [type]
+ description: |
+ A client must tolerate item types it does not recognise. A client that renders only `message`
+ items and ignores the rest is a valid client.
+ 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: '#/components/schemas/ContentPart' }
+ summary:
+ type: array
+ items: { type: object, additionalProperties: true }
+ call_id: { type: string }
+ name: { type: string }
+ arguments: { type: string, description: JSON, as a string }
+ 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: '#/components/schemas/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
+ against the base URL the caller is already using — a server behind a proxy cannot know its
+ public origin, and a base-relative path survives every fronting. The share's id MUST NOT
+ function as a credential for the rest of the API.
+ 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,
+ which kept every conformance check at "the endpoint answered 200" and made transcript
+ rebuilding an exercise in one implementation's habits.
+ 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
+
+ Environment:
+ type: object
+ required: [id, name, slug, status, mount]
+ properties:
+ id: { type: string, pattern: '^henv_' }
+ object: { type: string, const: environment }
+ name: { type: string }
+ slug:
+ type: string
+ description: The path segment sessions see; derived from the name at creation and fixed after.
+ description: { type: string }
+ entry:
+ type: string
+ description: How the project is run, in the owner's words; repeated to the agent.
+ status:
+ type: string
+ enum: [empty, building, ready, failed]
+ description: |
+ `ready` means a built version is active and tasks may read it. `empty` means nothing
+ was built yet; `building` and `failed` describe the latest build.
+ mount:
+ type: string
+ description: Where a session finds the environment, read-only. `/env/<slug>` on the reference server.
+ version: { type: [integer, 'null'], description: The active build, the one sessions read; null until one is ready. }
+ latestVersion: { type: [integer, 'null'] }
+ files:
+ type: object
+ description: The source's size (what the owner put in, before any build).
+ properties:
+ count: { type: integer, minimum: 0 }
+ bytes: { type: integer, minimum: 0 }
+ packages:
+ type: array
+ description: What the active build installed, as the package managers report it.
+ items: { $ref: '#/components/schemas/EnvironmentPackage' }
+ declared:
+ type: object
+ description: |
+ What the owner declared, per manager, as the build installs it beside the project's own
+ manifests: `pip` (`name==1.0`), `npm` (`[email protected]`), `apt` (`name`). Each entry carries
+ the spec as written and its parsed name and version.
+ properties:
+ pip: { type: array, items: { $ref: '#/components/schemas/DeclaredPackage' } }
+ npm: { type: array, items: { $ref: '#/components/schemas/DeclaredPackage' } }
+ apt: { type: array, items: { $ref: '#/components/schemas/DeclaredPackage' } }
+ runtime:
+ type: object
+ description: The interpreter a build makes the virtual environment with; empty means the server's default.
+ properties:
+ python: { type: string, examples: ['3.12'] }
+ versions:
+ type: array
+ items: { $ref: '#/components/schemas/EnvironmentVersion' }
+ build:
+ description: The latest build's status, or null before the first.
+ oneOf:
+ - type: 'null'
+ - $ref: '#/components/schemas/EnvironmentVersion'
+ createdAt: { type: integer, description: Unix milliseconds }
+ updatedAt: { type: integer, description: Unix milliseconds }
+ additionalProperties: true
+
+ DeclaredPackage:
+ type: object
+ required: [spec]
+ properties:
+ spec: { type: string, description: 'As written: moviepy==2.1.1, [email protected], ffmpeg' }
+ name: { type: string }
+ version: { type: string }
+ additionalProperties: true
+
+ EnvironmentPackageCheck:
+ type: object
+ required: [manager, name, spec, exists]
+ description: What the manager's registry says about a spec, before any build.
+ properties:
+ object: { type: string, const: environment.package }
+ manager: { type: string, enum: [pip, npm, apt] }
+ name: { type: string }
+ spec: { type: string }
+ exists: { type: [boolean, 'null'], description: "null when the registry could not be asked" }
+ latest: { type: string }
+ version: { type: string, description: "The exact pin when it is published; empty otherwise" }
+ error: { type: string, description: "In words: why the spec was refused, or why the registry could not be asked" }
+ additionalProperties: true
+
+ EnvironmentRuntimes:
+ type: object
+ description: What a build can be made with on this server, and nothing that is not there.
+ properties:
+ python: { type: array, items: { type: string }, examples: [['3.12', '3.13']] }
+ node: { type: array, items: { type: string }, examples: [['22']] }
+ os:
+ type: object
+ properties:
+ name: { type: string }
+ version: { type: string }
+ apt: { type: boolean, description: Whether apt packages can be declared here. }
+ additionalProperties: true
+
+ EnvironmentPackage:
+ type: object
+ required: [manager, name]
+ properties:
+ manager: { type: string, examples: [pip, npm] }
+ name: { type: string }
+ version: { type: string }
+ additionalProperties: true
+
+ EnvironmentVersion:
+ type: object
+ required: [version, status]
+ properties:
+ version: { type: integer, minimum: 1 }
+ status: { type: string, enum: [building, ready, failed, unknown] }
+ started_at: { type: [integer, 'null'] }
+ finished_at: { type: [integer, 'null'] }
+ error: { type: string }
+ files: { type: integer }
+ bytes: { type: integer }
+ packages: { type: integer, description: How many packages the build installed. }
+ additionalProperties: true
+
+ EnvironmentBuild:
+ type: object
+ required: [id, version, status]
+ description: A build's record; the log is the installers' own output, capped by the server.
+ properties:
+ id: { type: string }
+ object: { type: string, const: environment.build }
+ version: { type: integer }
+ status: { type: string, enum: [building, ready, failed] }
+ started_at: { type: [integer, 'null'] }
+ finished_at: { type: [integer, 'null'] }
+ error: { type: string }
+ stage: { type: string, description: "The step a running build is on; empty once it ended" }
+ log: { type: string }
+ packages: { type: array, items: { $ref: '#/components/schemas/EnvironmentPackage' } }
+ files: { type: integer }
+ bytes: { type: integer }
+ additionalProperties: true
+
+ EnvironmentCreate:
+ type: object
+ required: [name]
+ properties:
+ name: { type: string, description: Must start with a letter or digit; the slug derives from it. }
+ description: { type: string }
+ entry: { type: string }
+ packages:
+ type: object
+ description: Declared packages per manager, as spec strings; omitted on update means unchanged.
+ properties:
+ pip: { type: array, items: { type: string } }
+ npm: { type: array, items: { type: string } }
+ apt: { type: array, items: { type: string } }
+ runtime:
+ type: object
+ properties:
+ python: { type: string }
+ additionalProperties: true
+
+ EnvironmentList:
+ type: object
+ required: [environments]
+ properties:
+ environments: { type: array, items: { $ref: '#/components/schemas/Environment' } }
+ additionalProperties: true
+
+ EnvironmentFileEntry:
+ type: object
+ required: [path, dir]
+ properties:
+ path: { type: string, description: Relative to the environment's root. }
+ dir: { type: boolean }
+ bytes: { type: integer, minimum: 0 }
+ mtime: { type: integer, description: Unix seconds. }
+ additionalProperties: true
+
+ EnvironmentFileList:
+ type: object
+ required: [entries]
+ properties:
+ entries: { type: array, items: { $ref: '#/components/schemas/EnvironmentFileEntry' } }
+ count: { type: integer, description: Files, not directories. }
+ bytes: { type: integer }
+ additionalProperties: true
+
+ EnvironmentImport:
+ type: object
+ description: |
+ The JSON form of an import: a git repository. The other form is the archive itself as the
+ request body (a zip or a tar, any content type but `application/json`).
+ properties:
+ git:
+ type: object
+ required: [url]
+ properties:
+ url: { type: string }
+ ref: { type: string, description: A branch or tag; the default branch when omitted. }
+ replace: { type: boolean, default: false, description: Clear the source before importing. }
+ additionalProperties: true
+
+ EnvironmentImportResult:
+ type: object
+ properties:
+ written: { type: integer }
+ skipped: { type: integer, description: Members that must not land (links, escapes) and were dropped. }
+ count: { type: integer }
+ bytes: { type: integer }
+ additionalProperties: true
+
+ Session:
+ type: object
+ required: [id]
+ properties:
+ id: { type: string }
+ object: { type: string, const: session }
+ harness_id: { type: string }
+ environment: { type: string, description: The environment the session's turns read, when one did. }
+ 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: '#/components/schemas/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
+ items than requested — that heuristic is wrong whenever a page is exactly full.
+ 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: '#/components/schemas/Error' }
+ detail:
+ type: string
+ deprecated: true
+ description: |
+ A human-readable alias of `error.message`, retained for clients written against
+ implementations that predate this envelope. Carries no information not in `error`.
+ 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
+ specification does not cover, and must namespace them with a vendor prefix so a future
+ version cannot collide with them.
+ 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
+ - harness_busy
+ - plugin_conflict
+ - file_too_large
+ - model_unavailable
+ - model_not_available
+ - unsupported_base
+ - plugin_invalid
+ - unsupported_plugin_schema
+ - environment_not_found
+ - environment_not_ready
+ - environment_busy
+ - environment_exists
+ - environment_invalid
+ - environment_unavailable
+ - 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
+ paths, or stack traces.
+ 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
+ client can detect a dropped event rather than silently rendering a gap.
+ 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: '#/components/schemas/Response' }
+ item: { $ref: '#/components/schemas/OutputItem' }
+ part: { $ref: '#/components/schemas/ContentPart' }
+ annotation: { $ref: '#/components/schemas/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
+
+ Memory:
+ type: object
+ required: [id, name, privileges]
+ properties:
+ id: { type: string, description: 'Opaque to a client. A server that maps a tree it already has keeps that tree''s own ids.' }
+ object: { type: string, const: memory }
+ name: { type: string }
+ description: { type: string, description: What this memory holds; an agent reads it to decide whether to look inside. }
+ parent_id: { type: [string, 'null'] }
+ ancestors: { type: array, items: { type: string }, description: 'Ids from the root down to the parent, as far up as the caller may see.' }
+ restricted: { type: boolean, description: 'When true, grants on ancestors stop here.' }
+ provider: { type: string }
+ privileges: { type: array, items: { $ref: '#/components/schemas/MemoryPrivilege' }, description: The effective privileges of the caller on this memory. }
+ records: { type: object, properties: { count: { type: [integer, 'null'] } } }
+ children: { type: object, properties: { count: { type: integer } } }
+ createdAt: { type: integer }
+ updatedAt: { type: integer }
+ additionalProperties: true
+ MemoryPrivilege: { type: string, enum: [read, write, create, delete] }
+ MemoryCreate:
+ type: object
+ required: [name]
+ properties:
+ name: { type: string }
+ description: { type: string }
+ parent_id: { type: [string, 'null'] }
+ restricted: { type: boolean }
+ provider: { type: string, description: A connected provider; inherited from the parent when omitted. }
+ MemoryUpdate:
+ type: object
+ properties:
+ name: { type: string }
+ description: { type: string }
+ restricted: { type: boolean }
+ parent_id: { type: [string, 'null'] }
+ MemoryList:
+ type: object
+ properties:
+ object: { type: string, const: list }
+ data: { type: array, items: { $ref: '#/components/schemas/Memory' } }
+ MemoryDeleted:
+ type: object
+ properties:
+ id: { type: string }
+ deleted: { type: boolean }
+ memories: { type: array, items: { type: string }, description: 'Every memory removed: the named one and its descendants.' }
+ Deleted:
+ type: object
+ properties:
+ id: { type: string }
+ deleted: { type: boolean }
+ additionalProperties: true
+ FreeObject: { type: object, additionalProperties: true }
+ MemoryNeighbour:
+ type: object
+ properties:
+ id: { type: string }
+ name: { type: string }
+ description: { type: string }
+ records: { type: object }
+ children: { type: object }
+ privileges: { type: array, items: { $ref: '#/components/schemas/MemoryPrivilege' } }
+ MemoryGrant:
+ type: object
+ required: [id, memory_id, principal, privileges]
+ properties:
+ id: { type: string }
+ object: { type: string, const: memory.grant }
+ memory_id: { type: string }
+ principal: { type: string, pattern: '^(member|group|x\.[a-z0-9_.-]+):.+', description: 'Who holds the grant, `<kind>:<id>`: a `member` (a person or an agent), a `group`, or a kind of the server''s own, `x.`-prefixed.' }
+ privileges: { type: array, items: { $ref: '#/components/schemas/MemoryPrivilege' } }
+ inherited: { type: boolean, description: True when the grant sits on an ancestor. }
+ MemoryGrantCreate:
+ type: object
+ required: [principal, privileges]
+ properties:
+ principal: { type: string }
+ privileges: { type: array, items: { $ref: '#/components/schemas/MemoryPrivilege' } }
+ MemoryGrantList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryGrant' } }
+ MemoryReference:
+ type: object
+ required: [record_id]
+ properties:
+ rel: { type: string }
+ memory_id: { type: string }
+ record_id: { type: string }
+ available: { type: boolean, description: False when the reader may not read the target; nothing else of it is returned. }
+ MemoryRecord:
+ type: object
+ required: [id, memory_id, type, trust]
+ properties:
+ id: { type: string, description: Assigned by the provider and opaque to a client. }
+ object: { type: string, const: memory.record }
+ memory_id: { type: string }
+ type: { type: string, description: 'episode, fact, note, procedure, link, entity, or an extension type.' }
+ title: { type: string, maxLength: 300, description: 'One line that names the record. Optional; a search matches it with the content.' }
+ content: { type: array, items: { $ref: '#/components/schemas/MemoryContentPart' }, description: An ordered list of parts. Always a list on a read. }
+ attributes: { type: object, additionalProperties: true }
+ version: { type: integer }
+ status: { type: string, enum: [active, superseded, forgotten] }
+ supersedes: { type: [integer, 'null'], description: 'The number of the version this one replaced; null on the first.' }
+ time:
+ type: object
+ properties:
+ valid_from: { type: [string, 'null'] }
+ valid_to: { type: [string, 'null'] }
+ written_at: { type: [string, 'null'] }
+ invalidated_at: { type: [string, 'null'] }
+ written_by: { $ref: '#/components/schemas/MemoryWriter' }
+ references: { type: array, items: { $ref: '#/components/schemas/MemoryReference' } }
+ follows:
+ type: object
+ description: 'Present only on a record the server derives from a source it keeps outside the memory (a section of a document). Such a record is not revised or forgotten through the memory.'
+ properties:
+ kind: { type: string, description: 'What the source is, in a word: `document`.' }
+ id: { type: string }
+ name: { type: string, description: 'What a person calls the source.' }
+ additionalProperties: true
+ trust: { type: string, const: untrusted }
+ closed: { type: array, items: { type: string }, description: 'Only on the answer to remembering a fact whose `holds` is `one`: the records it ended. Never stored.' }
+ conflicts: { type: array, items: { type: string }, description: 'Only on the answer to remembering a fact whose `holds` is `one`: the records it was linked to with `contradicts`. Never stored.' }
+ additionalProperties: true
+ MemoryContentPart:
+ type: object
+ required: [type]
+ description: 'One part of the content of a record. `text` and `file` are defined; any other kind is `x.`-prefixed and carried unchanged.'
+ properties:
+ type: { type: string }
+ text: { type: string, description: 'The words of a text part, or the words that stand for a file.' }
+ text_source: { type: string, enum: [stated, derived] }
+ role: { type: string, enum: [user, assistant, system, tool] }
+ name: { type: string, description: 'Who said it, when the role alone does not: two people in one conversation are both `user`.' }
+ file:
+ type: object
+ required: [id]
+ properties:
+ id: { type: string }
+ name: { type: string }
+ media_type: { type: string }
+ bytes: { type: integer }
+ version: { type: string }
+ additionalProperties: true
+ MemoryRecordCreate:
+ type: object
+ required: [content]
+ properties:
+ type: { type: string }
+ content: { oneOf: [ { type: string, description: Shorthand for one text part. }, { type: array, items: { $ref: '#/components/schemas/MemoryContentPart' } } ] }
+ attributes: { type: object, additionalProperties: true }
+ references: { type: array, items: { $ref: '#/components/schemas/MemoryReference' } }
+ time: { type: object, additionalProperties: true }
+ MemoryRecordRevise:
+ type: object
+ properties:
+ content: { oneOf: [ { type: string, description: Shorthand for one text part. }, { type: array, items: { $ref: '#/components/schemas/MemoryContentPart' } } ] }
+ attributes: { type: object, additionalProperties: true }
+ references: { type: array, items: { $ref: '#/components/schemas/MemoryReference' } }
+ time: { type: object, additionalProperties: true }
+ MemoryRecordList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryRecord' } }
+ next: { type: [string, 'null'] }
+ job: { $ref: '#/components/schemas/MemoryJob' }
+ parent: { $ref: '#/components/schemas/MemoryNeighbour' }
+ children: { type: array, items: { $ref: '#/components/schemas/MemoryNeighbour' } }
+ MemoryObserve:
+ type: object
+ required: [episodes]
+ properties:
+ episodes:
+ type: array
+ minItems: 1
+ items:
+ type: object
+ required: [content]
+ properties:
+ content: { oneOf: [ { type: string, description: Shorthand for one text part. }, { type: array, items: { $ref: '#/components/schemas/MemoryContentPart' } } ] }
+ time:
+ type: object
+ properties:
+ valid_from: { type: [string, 'null'], description: 'When it happened. Left out, now.' }
+ additionalProperties: true
+ attributes: { type: object, additionalProperties: true }
+ MemoryJob:
+ type: object
+ required: [id, status]
+ properties:
+ object: { type: string, const: memory.job }
+ id: { type: string }
+ memory_id: { type: string }
+ status: { type: string, enum: [queued, running, pending, completed, failed], description: '`pending` when the provider cannot tell queued from running.' }
+ error: { type: string }
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryRecord' }, description: The records the job wrote. }
+ closed: { type: array, items: { type: string }, description: 'Records ended by a `one` fact the job wrote.' }
+ conflicts: { type: array, items: { type: string }, description: 'Records linked with `contradicts` by a `one` fact the job wrote.' }
+ usage: { type: object, additionalProperties: true, description: 'Tokens, when a model did the work: `input_tokens`, `output_tokens`.' }
+ created_at: { type: integer }
+ started_at: { type: [integer, 'null'] }
+ finished_at: { type: [integer, 'null'] }
+ MemoryWriter:
+ type: object
+ description: 'Who wrote a record, stamped by the server from the authenticated caller. `kind` and `id` joined by a colon are the principal a grant would name.'
+ required: [kind, id]
+ properties:
+ kind: { type: string, pattern: '^(member|provider|x\.[a-z0-9_.-]+)$' }
+ id: { type: string }
+ type: { type: string, enum: [human, agent], description: 'For a member: a person or an agent. No rule depends on it.' }
+ on_behalf_of: { type: string, description: 'When the provider wrote it: the principal whose observation it was derived from.' }
+ consolidation_id: { type: string, description: 'When the provider wrote it: the consolidation run that concluded it.' }
+ additionalProperties: true
+ MemoryFilter:
+ type: object
+ description: 'One of `{field, op, value}`, `{and: [...]}` or `{or: [...]}`.'
+ additionalProperties: true
+ MemoryPrime:
+ type: object
+ required: [records, tokens, truncated]
+ properties:
+ records: { type: array, items: { $ref: '#/components/schemas/MemoryRecord' } }
+ tokens: { type: integer, description: The provider's own estimate of what the records cost. }
+ truncated: { type: boolean, description: True when a standing record was left out. }
+ MemoryRecallRequest:
+ type: object
+ properties:
+ query: { type: string, description: Meaning. }
+ text: { type: string, description: Words. }
+ filters: { $ref: '#/components/schemas/MemoryFilter' }
+ types: { type: array, items: { type: string } }
+ as_of: { type: [string, 'null'] }
+ include: { type: string, enum: [active, all] }
+ depth: { type: [integer, 'null'], minimum: 0, description: 'Levels below to search: 0 is this memory alone. Left out, the whole readable subtree.' }
+ limit: { type: integer, minimum: 1, maximum: 100 }
+ MemoryRecall:
+ type: object
+ required: [results, degraded, abstain]
+ properties:
+ results:
+ type: array
+ items:
+ type: object
+ required: [record, memory]
+ properties:
+ record: { $ref: '#/components/schemas/MemoryRecord' }
+ memory:
+ type: object
+ description: The memory this result is in, the one asked or one below it.
+ required: [id]
+ properties:
+ id: { type: string }
+ name: { type: string }
+ score: { type: [number, 'null'] }
+ why: { type: array, items: { type: string } }
+ parent: { $ref: '#/components/schemas/MemoryNeighbour' }
+ children: { type: array, items: { $ref: '#/components/schemas/MemoryNeighbour' } }
+ degraded: { type: array, items: { type: string }, description: What the request asked for and was not done. }
+ abstain: { type: boolean, description: True when the provider judges that nothing it returned answers the question. }
+ additionalProperties: true
+ MemoryGraphRequest:
+ type: object
+ properties:
+ around: { type: string, description: 'A record to start from. Left out, every record of this memory.' }
+ hops: { type: integer, minimum: 0, maximum: 3, description: 'References away from the start, in either direction. Default 1.' }
+ types: { type: array, items: { type: string } }
+ limit: { type: integer, minimum: 1 }
+ MemoryRecordRef:
+ type: object
+ description: 'A record by where it is. `memory_id` is absent on the far end of an edge the caller may not follow.'
+ required: [record_id]
+ properties:
+ memory_id: { type: string }
+ record_id: { type: string }
+ MemoryGraph:
+ type: object
+ required: [nodes, edges, truncated]
+ properties:
+ object: { type: string, const: memory.graph }
+ nodes:
+ type: array
+ items:
+ type: object
+ required: [record, memory]
+ properties:
+ record: { $ref: '#/components/schemas/MemoryRecord' }
+ memory:
+ type: object
+ required: [id]
+ properties:
+ id: { type: string }
+ name: { type: string }
+ edges:
+ type: array
+ items:
+ type: object
+ required: [from, to, available]
+ properties:
+ from: { $ref: '#/components/schemas/MemoryRecordRef' }
+ to: { $ref: '#/components/schemas/MemoryRecordRef' }
+ rel: { type: string, description: 'What the reference means. Absent when the target is not readable by the caller.' }
+ available: { type: boolean }
+ truncated: { type: boolean }
+ degraded: { type: array, items: { type: string } }
+ additionalProperties: true
+ MemoryErase:
+ type: object
+ required: [record_ids]
+ properties:
+ record_ids: { type: array, minItems: 1, items: { type: string } }
+ MemoryErasure:
+ type: object
+ required: [erased, unreachable]
+ properties:
+ erased: { type: array, items: { type: string } }
+ unreachable: { type: array, items: { type: string }, description: Content the provider could not remove. Empty is a guarantee. }
+ MemoryQuery:
+ type: object
+ required: [body]
+ properties:
+ name: { type: string }
+ description: { type: string }
+ params: { type: object, additionalProperties: true, description: A JSON Schema for the parameters. }
+ requires: { type: string, enum: [read, write] }
+ language: { type: string, description: Opaque to the protocol. }
+ body: { type: string, description: Opaque to the protocol. }
+ additionalProperties: true
+ MemoryQueryList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryQuery' } }
+ MemoryQueryRun:
+ type: object
+ properties:
+ params: { type: object, additionalProperties: true }
+ MemoryFreeQuery:
+ type: object
+ required: [statement]
+ properties:
+ language: { type: string }
+ statement: { type: string }
+ params: { type: object, additionalProperties: true }
+ write: { type: boolean }
+ MemoryOperationResult:
+ type: object
+ properties:
+ name: { type: string }
+ result: {}
+ MemorySnapshot:
+ type: object
+ required: [id, name, at]
+ properties:
+ id: { type: string }
+ object: { type: string, const: memory.snapshot }
+ memory_id: { type: string }
+ name: { type: string }
+ message: { type: string }
+ at: { type: string }
+ MemorySnapshotCreate:
+ type: object
+ required: [name]
+ properties:
+ name: { type: string }
+ message: { type: string }
+ MemorySnapshotList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemorySnapshot' } }
+ MemoryConsolidation:
+ type: object
+ required: [id, status]
+ properties:
+ id: { type: string }
+ object: { type: string, const: memory.consolidation }
+ memory_id: { type: string }
+ status: { type: string, enum: [queued, running, completed, stopped, failed] }
+ trigger: { type: string }
+ started_at: { type: [integer, 'null'] }
+ finished_at: { type: [integer, 'null'] }
+ read: { type: object, additionalProperties: true }
+ changes: { type: object, additionalProperties: true }
+ usage: { type: object, additionalProperties: true }
+ budget: { type: object, additionalProperties: true }
+ written_by: { $ref: '#/components/schemas/MemoryWriter' }
+ error: { type: string }
+ additionalProperties: true
+ MemoryConsolidationStart:
+ type: object
+ properties:
+ budget: { type: object, additionalProperties: true }
+ MemoryConsolidationList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryConsolidation' } }
+ MemoryProvider:
+ type: object
+ required: [id, isolation]
+ properties:
+ id: { type: string }
+ isolation: { type: string, enum: [container, enforced_filter] }
+ derivation: { type: string, enum: [write_time, background, agent, none] }
+ prime: { type: boolean, description: 'Whether the provider answers the prime read with its standing records.' }
+ holds: { type: boolean, description: 'Whether the provider ends and links facts by `attributes.holds`.' }
+ observe: { type: object, additionalProperties: true }
+ recall: { type: object, additionalProperties: true }
+ history: { type: object, additionalProperties: true }
+ erase: { type: object, additionalProperties: true }
+ queries: { type: object, additionalProperties: true }
+ graph:
+ type: object
+ properties:
+ entities: { type: string, enum: [derived, stated, none], description: 'Where a memory''s entities come from on this provider.' }
+ additionalProperties: true
+ content:
+ type: object
+ description: What the content of a record may carry on this provider.
+ properties:
+ media: { type: array, items: { type: string }, description: 'Media types kept, as patterns such as `text/*` or `image/*`.' }
+ bytes: { type: string, enum: [kept, referenced] }
+ describes: { type: array, items: { type: string } }
+ additionalProperties: true
+ MemoryProviderList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryProvider' } }
+ MemoryType:
+ type: object
+ required: [type]
+ properties:
+ type: { type: string }
+ core: { type: boolean }
+ description: { type: string }
+ schema: { type: object, additionalProperties: true }
+ text: { type: string }
+ operations:
+ type: array
+ items:
+ type: object
+ required: [name, requires]
+ properties:
+ name: { type: string }
+ description: { type: string }
+ input: { type: object, additionalProperties: true }
+ requires: { $ref: '#/components/schemas/MemoryPrivilege' }
+ additionalProperties: true
+ MemoryTypeList:
+ type: object
+ properties:
+ data: { type: array, items: { $ref: '#/components/schemas/MemoryType' } }
+ HarnessMemorySettings:
+ type: object
+ properties:
+ default_memory_id: { type: [string, 'null'], description: 'Where an unaddressed remember goes and where turns are recorded. A memory the agent may write.' }
+ observe: { type: boolean, description: 'Record each finished turn in the default memory. On by default.' }
+ HarnessMemories:
+ type: object
+ required: [principal, data]
+ properties:
+ object: { type: string, const: harness.memories }
+ principal: { type: string, description: 'Who this harness''s agent is to the access model, `member:<id>`. A grant names it.' }
+ default_memory_id: { type: [string, 'null'] }
+ observe: { type: boolean }
+ data:
+ type: array
+ description: Every memory the agent holds a grant on, highest in the tree first. Read off the grants.
+ items:
+ type: object
+ required: [id, privileges]
+ properties:
+ id: { type: string }
+ name: { type: string }
+ privileges: { type: array, items: { type: string, enum: [read, write, create, delete] } }
+ default: { type: boolean }
+ additionalProperties: true
diff --git a/protocol/schema/uhp-2026-10-19.schema.json b/protocol/schema/uhp-2026-10-19.schema.json
new file mode 100644
index 00000000..ea25de01
--- /dev/null
+++ b/protocol/schema/uhp-2026-10-19.schema.json
@@ -0,0 +1,3491 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://unifiedharnessprotocol.org/schema/uhp-2026-10-19.schema.json",
+ "title": "Unified Harness Protocol",
+ "description": "Object definitions for UHP 2026-10-19. Generated from uhp-2026-10-19.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"
+ },
+ "harness_retirement": {
+ "type": "boolean",
+ "description": "Retiring a harness retires its sessions and responses with it, restorable until a time\nthe delete response states (`restorableUntil`) and removed after it. `false`, or absent:\nthey are kept. See Harnesses §5.3.\n"
+ },
+ "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"
+ },
+ "environments": {
+ "type": "boolean",
+ "description": "The server holds environments: a project's files and installed dependencies, built once,\nread-only at a fixed path in every session that names one. Optional at every class.\n"
+ },
+ "memories": {
+ "type": "boolean",
+ "description": "The server holds memories: a tree of memories with access granted per node, records kept\nby a connected provider, and tools a harness's agent reaches them with. 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"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment (`henv_`) this harness's tasks read, mounted read-only at its `mount`;\nempty when none. A task may name another with its own `environment` field.\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`."
+ },
+ "environment": {
+ "type": "string",
+ "description": "An environment id of the caller's scope",
+ "or empty. Requires the `environments` capability.": null
+ },
+ "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, the extension point of the Responses surface. `harness_id` selects the\nconfigured harness; `environment` names the environment this task reads, overriding the\nharness's (capability `environments`), refused with `environment_not_found` or\n`environment_not_ready` before the task starts.\n",
+ "properties": {
+ "harness_id": {
+ "type": "string"
+ },
+ "environment": {
+ "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"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment the task read, when it read one (capability `environments`)."
+ },
+ "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
+ },
+ "Environment": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "slug",
+ "status",
+ "mount"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "pattern": "^henv_"
+ },
+ "object": {
+ "type": "string",
+ "const": "environment"
+ },
+ "name": {
+ "type": "string"
+ },
+ "slug": {
+ "type": "string",
+ "description": "The path segment sessions see; derived from the name at creation and fixed after."
+ },
+ "description": {
+ "type": "string"
+ },
+ "entry": {
+ "type": "string",
+ "description": "How the project is run, in the owner's words; repeated to the agent."
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "empty",
+ "building",
+ "ready",
+ "failed"
+ ],
+ "description": "`ready` means a built version is active and tasks may read it. `empty` means nothing\nwas built yet; `building` and `failed` describe the latest build.\n"
+ },
+ "mount": {
+ "type": "string",
+ "description": "Where a session finds the environment, read-only. `/env/<slug>` on the reference server."
+ },
+ "version": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "description": "The active build",
+ "the one sessions read; null until one is ready.": null
+ },
+ "latestVersion": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "files": {
+ "type": "object",
+ "description": "The source's size (what the owner put in, before any build).",
+ "properties": {
+ "count": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ }
+ }
+ },
+ "packages": {
+ "type": "array",
+ "description": "What the active build installed, as the package managers report it.",
+ "items": {
+ "$ref": "#/$defs/EnvironmentPackage"
+ }
+ },
+ "declared": {
+ "type": "object",
+ "description": "What the owner declared, per manager, as the build installs it beside the project's own\nmanifests: `pip` (`name==1.0`), `npm` (`[email protected]`), `apt` (`name`). Each entry carries\nthe spec as written and its parsed name and version.\n",
+ "properties": {
+ "pip": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ },
+ "npm": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ },
+ "apt": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/DeclaredPackage"
+ }
+ }
+ }
+ },
+ "runtime": {
+ "type": "object",
+ "description": "The interpreter a build makes the virtual environment with; empty means the server's default.",
+ "properties": {
+ "python": {
+ "type": "string",
+ "examples": [
+ "3.12"
+ ]
+ }
+ }
+ },
+ "versions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentVersion"
+ }
+ },
+ "build": {
+ "description": "The latest build's status, or null before the first.",
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/$defs/EnvironmentVersion"
+ }
+ ]
+ },
+ "createdAt": {
+ "type": "integer",
+ "description": "Unix milliseconds"
+ },
+ "updatedAt": {
+ "type": "integer",
+ "description": "Unix milliseconds"
+ }
+ },
+ "additionalProperties": true
+ },
+ "DeclaredPackage": {
+ "type": "object",
+ "required": [
+ "spec"
+ ],
+ "properties": {
+ "spec": {
+ "type": "string",
+ "description": "As written: moviepy==2.1.1, [email protected], ffmpeg"
+ },
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentPackageCheck": {
+ "type": "object",
+ "required": [
+ "manager",
+ "name",
+ "spec",
+ "exists"
+ ],
+ "description": "What the manager's registry says about a spec, before any build.",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "environment.package"
+ },
+ "manager": {
+ "type": "string",
+ "enum": [
+ "pip",
+ "npm",
+ "apt"
+ ]
+ },
+ "name": {
+ "type": "string"
+ },
+ "spec": {
+ "type": "string"
+ },
+ "exists": {
+ "type": [
+ "boolean",
+ "null"
+ ],
+ "description": "null when the registry could not be asked"
+ },
+ "latest": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string",
+ "description": "The exact pin when it is published; empty otherwise"
+ },
+ "error": {
+ "type": "string",
+ "description": "In words: why the spec was refused, or why the registry could not be asked"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentRuntimes": {
+ "type": "object",
+ "description": "What a build can be made with on this server, and nothing that is not there.",
+ "properties": {
+ "python": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "examples": [
+ [
+ "3.12",
+ "3.13"
+ ]
+ ]
+ },
+ "node": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "examples": [
+ [
+ "22"
+ ]
+ ]
+ },
+ "os": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ }
+ },
+ "apt": {
+ "type": "boolean",
+ "description": "Whether apt packages can be declared here."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentPackage": {
+ "type": "object",
+ "required": [
+ "manager",
+ "name"
+ ],
+ "properties": {
+ "manager": {
+ "type": "string",
+ "examples": [
+ "pip",
+ "npm"
+ ]
+ },
+ "name": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentVersion": {
+ "type": "object",
+ "required": [
+ "version",
+ "status"
+ ],
+ "properties": {
+ "version": {
+ "type": "integer",
+ "minimum": 1
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "building",
+ "ready",
+ "failed",
+ "unknown"
+ ]
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "files": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ },
+ "packages": {
+ "type": "integer",
+ "description": "How many packages the build installed."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentBuild": {
+ "type": "object",
+ "required": [
+ "id",
+ "version",
+ "status"
+ ],
+ "description": "A build's record; the log is the installers' own output, capped by the server.",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "environment.build"
+ },
+ "version": {
+ "type": "integer"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "building",
+ "ready",
+ "failed"
+ ]
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "stage": {
+ "type": "string",
+ "description": "The step a running build is on; empty once it ended"
+ },
+ "log": {
+ "type": "string"
+ },
+ "packages": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentPackage"
+ }
+ },
+ "files": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Must start with a letter or digit; the slug derives from it."
+ },
+ "description": {
+ "type": "string"
+ },
+ "entry": {
+ "type": "string"
+ },
+ "packages": {
+ "type": "object",
+ "description": "Declared packages per manager, as spec strings; omitted on update means unchanged.",
+ "properties": {
+ "pip": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "npm": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "apt": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "runtime": {
+ "type": "object",
+ "properties": {
+ "python": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentList": {
+ "type": "object",
+ "required": [
+ "environments"
+ ],
+ "properties": {
+ "environments": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/Environment"
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentFileEntry": {
+ "type": "object",
+ "required": [
+ "path",
+ "dir"
+ ],
+ "properties": {
+ "path": {
+ "type": "string",
+ "description": "Relative to the environment's root."
+ },
+ "dir": {
+ "type": "boolean"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "mtime": {
+ "type": "integer",
+ "description": "Unix seconds."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentFileList": {
+ "type": "object",
+ "required": [
+ "entries"
+ ],
+ "properties": {
+ "entries": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/EnvironmentFileEntry"
+ }
+ },
+ "count": {
+ "type": "integer",
+ "description": "Files",
+ "not directories.": null
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentImport": {
+ "type": "object",
+ "description": "The JSON form of an import: a git repository. The other form is the archive itself as the\nrequest body (a zip or a tar, any content type but `application/json`).\n",
+ "properties": {
+ "git": {
+ "type": "object",
+ "required": [
+ "url"
+ ],
+ "properties": {
+ "url": {
+ "type": "string"
+ },
+ "ref": {
+ "type": "string",
+ "description": "A branch or tag; the default branch when omitted."
+ }
+ }
+ },
+ "replace": {
+ "type": "boolean",
+ "default": false,
+ "description": "Clear the source before importing."
+ }
+ },
+ "additionalProperties": true
+ },
+ "EnvironmentImportResult": {
+ "type": "object",
+ "properties": {
+ "written": {
+ "type": "integer"
+ },
+ "skipped": {
+ "type": "integer",
+ "description": "Members that must not land (links",
+ "escapes) and were dropped.": null
+ },
+ "count": {
+ "type": "integer"
+ },
+ "bytes": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "Session": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "session"
+ },
+ "harness_id": {
+ "type": "string"
+ },
+ "environment": {
+ "type": "string",
+ "description": "The environment the session's turns read",
+ "when one did.": null
+ },
+ "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",
+ "harness_busy",
+ "plugin_conflict",
+ "file_too_large",
+ "model_unavailable",
+ "model_not_available",
+ "unsupported_base",
+ "plugin_invalid",
+ "unsupported_plugin_schema",
+ "environment_not_found",
+ "environment_not_ready",
+ "environment_busy",
+ "environment_exists",
+ "environment_invalid",
+ "environment_unavailable",
+ "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
+ },
+ "Memory": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Opaque to a client. A server that maps a tree it already has keeps that tree's own ids."
+ },
+ "object": {
+ "type": "string",
+ "const": "memory"
+ },
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string",
+ "description": "What this memory holds; an agent reads it to decide whether to look inside."
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "ancestors": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Ids from the root down to the parent, as far up as the caller may see."
+ },
+ "restricted": {
+ "type": "boolean",
+ "description": "When true, grants on ancestors stop here."
+ },
+ "provider": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ },
+ "description": "The effective privileges of the caller on this memory."
+ },
+ "records": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ }
+ },
+ "children": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": "integer"
+ }
+ }
+ },
+ "createdAt": {
+ "type": "integer"
+ },
+ "updatedAt": {
+ "type": "integer"
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryPrivilege": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write",
+ "create",
+ "delete"
+ ]
+ },
+ "MemoryCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "restricted": {
+ "type": "boolean"
+ },
+ "provider": {
+ "type": "string",
+ "description": "A connected provider; inherited from the parent when omitted."
+ }
+ }
+ },
+ "MemoryUpdate": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "restricted": {
+ "type": "boolean"
+ },
+ "parent_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ }
+ },
+ "MemoryList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/Memory"
+ }
+ }
+ }
+ },
+ "MemoryDeleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "deleted": {
+ "type": "boolean"
+ },
+ "memories": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Every memory removed: the named one and its descendants."
+ }
+ }
+ },
+ "Deleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "deleted": {
+ "type": "boolean"
+ }
+ },
+ "additionalProperties": true
+ },
+ "FreeObject": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "MemoryNeighbour": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "records": {
+ "type": "object"
+ },
+ "children": {
+ "type": "object"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ },
+ "MemoryGrant": {
+ "type": "object",
+ "required": [
+ "id",
+ "memory_id",
+ "principal",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.grant"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "principal": {
+ "type": "string",
+ "pattern": "^(member|group|x\\.[a-z0-9_.-]+):.+",
+ "description": "Who holds the grant, `<kind>:<id>`: a `member` (a person or an agent), a `group`, or a kind of the server's own, `x.`-prefixed."
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ },
+ "inherited": {
+ "type": "boolean",
+ "description": "True when the grant sits on an ancestor."
+ }
+ }
+ },
+ "MemoryGrantCreate": {
+ "type": "object",
+ "required": [
+ "principal",
+ "privileges"
+ ],
+ "properties": {
+ "principal": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ },
+ "MemoryGrantList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryGrant"
+ }
+ }
+ }
+ },
+ "MemoryReference": {
+ "type": "object",
+ "required": [
+ "record_id"
+ ],
+ "properties": {
+ "rel": {
+ "type": "string"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "record_id": {
+ "type": "string"
+ },
+ "available": {
+ "type": "boolean",
+ "description": "False when the reader may not read the target; nothing else of it is returned."
+ }
+ }
+ },
+ "MemoryRecord": {
+ "type": "object",
+ "required": [
+ "id",
+ "memory_id",
+ "type",
+ "trust"
+ ],
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Assigned by the provider and opaque to a client."
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.record"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string",
+ "description": "episode, fact, note, procedure, link, entity, or an extension type."
+ },
+ "title": {
+ "type": "string",
+ "maxLength": 300,
+ "description": "One line that names the record. Optional; a search matches it with the content."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ },
+ "description": "An ordered list of parts. Always a list on a read."
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "version": {
+ "type": "integer"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "active",
+ "superseded",
+ "forgotten"
+ ]
+ },
+ "supersedes": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "description": "The number of the version this one replaced; null on the first."
+ },
+ "time": {
+ "type": "object",
+ "properties": {
+ "valid_from": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "valid_to": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "written_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "invalidated_at": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ }
+ },
+ "written_by": {
+ "$ref": "#/$defs/MemoryWriter"
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "follows": {
+ "type": "object",
+ "description": "Present only on a record the server derives from a source it keeps outside the memory (a section of a document). Such a record is not revised or forgotten through the memory.",
+ "properties": {
+ "kind": {
+ "type": "string",
+ "description": "What the source is, in a word: `document`."
+ },
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string",
+ "description": "What a person calls the source."
+ }
+ },
+ "additionalProperties": true
+ },
+ "trust": {
+ "type": "string",
+ "const": "untrusted"
+ },
+ "closed": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only on the answer to remembering a fact whose `holds` is `one`: the records it ended. Never stored."
+ },
+ "conflicts": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Only on the answer to remembering a fact whose `holds` is `one`: the records it was linked to with `contradicts`. Never stored."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryContentPart": {
+ "type": "object",
+ "required": [
+ "type"
+ ],
+ "description": "One part of the content of a record. `text` and `file` are defined; any other kind is `x.`-prefixed and carried unchanged.",
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "text": {
+ "type": "string",
+ "description": "The words of a text part, or the words that stand for a file."
+ },
+ "text_source": {
+ "type": "string",
+ "enum": [
+ "stated",
+ "derived"
+ ]
+ },
+ "role": {
+ "type": "string",
+ "enum": [
+ "user",
+ "assistant",
+ "system",
+ "tool"
+ ]
+ },
+ "name": {
+ "type": "string",
+ "description": "Who said it, when the role alone does not: two people in one conversation are both `user`."
+ },
+ "file": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "media_type": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer"
+ },
+ "version": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryRecordCreate": {
+ "type": "object",
+ "required": [
+ "content"
+ ],
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "time": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryRecordRevise": {
+ "type": "object",
+ "properties": {
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "references": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryReference"
+ }
+ },
+ "time": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryRecordList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ }
+ },
+ "next": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "job": {
+ "$ref": "#/$defs/MemoryJob"
+ },
+ "parent": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ },
+ "children": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ }
+ }
+ }
+ },
+ "MemoryObserve": {
+ "type": "object",
+ "required": [
+ "episodes"
+ ],
+ "properties": {
+ "episodes": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "object",
+ "required": [
+ "content"
+ ],
+ "properties": {
+ "content": {
+ "oneOf": [
+ {
+ "type": "string",
+ "description": "Shorthand for one text part."
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryContentPart"
+ }
+ }
+ ]
+ },
+ "time": {
+ "type": "object",
+ "properties": {
+ "valid_from": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "When it happened. Left out, now."
+ }
+ },
+ "additionalProperties": true
+ },
+ "attributes": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ }
+ },
+ "MemoryJob": {
+ "type": "object",
+ "required": [
+ "id",
+ "status"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "memory.job"
+ },
+ "id": {
+ "type": "string"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "queued",
+ "running",
+ "pending",
+ "completed",
+ "failed"
+ ],
+ "description": "`pending` when the provider cannot tell queued from running."
+ },
+ "error": {
+ "type": "string"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "description": "The records the job wrote."
+ },
+ "closed": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Records ended by a `one` fact the job wrote."
+ },
+ "conflicts": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Records linked with `contradicts` by a `one` fact the job wrote."
+ },
+ "usage": {
+ "type": "object",
+ "additionalProperties": true,
+ "description": "Tokens, when a model did the work: `input_tokens`, `output_tokens`."
+ },
+ "created_at": {
+ "type": "integer"
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ }
+ },
+ "MemoryWriter": {
+ "type": "object",
+ "description": "Who wrote a record, stamped by the server from the authenticated caller. `kind` and `id` joined by a colon are the principal a grant would name.",
+ "required": [
+ "kind",
+ "id"
+ ],
+ "properties": {
+ "kind": {
+ "type": "string",
+ "pattern": "^(member|provider|x\\.[a-z0-9_.-]+)$"
+ },
+ "id": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "human",
+ "agent"
+ ],
+ "description": "For a member: a person or an agent. No rule depends on it."
+ },
+ "on_behalf_of": {
+ "type": "string",
+ "description": "When the provider wrote it: the principal whose observation it was derived from."
+ },
+ "consolidation_id": {
+ "type": "string",
+ "description": "When the provider wrote it: the consolidation run that concluded it."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryFilter": {
+ "type": "object",
+ "description": "One of `{field, op, value}`, `{and: [...]}` or `{or: [...]}`.",
+ "additionalProperties": true
+ },
+ "MemoryPrime": {
+ "type": "object",
+ "required": [
+ "records",
+ "tokens",
+ "truncated"
+ ],
+ "properties": {
+ "records": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryRecord"
+ }
+ },
+ "tokens": {
+ "type": "integer",
+ "description": "The provider's own estimate of what the records cost."
+ },
+ "truncated": {
+ "type": "boolean",
+ "description": "True when a standing record was left out."
+ }
+ }
+ },
+ "MemoryRecallRequest": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Meaning."
+ },
+ "text": {
+ "type": "string",
+ "description": "Words."
+ },
+ "filters": {
+ "$ref": "#/$defs/MemoryFilter"
+ },
+ "types": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "as_of": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "include": {
+ "type": "string",
+ "enum": [
+ "active",
+ "all"
+ ]
+ },
+ "depth": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "minimum": 0,
+ "description": "Levels below to search: 0 is this memory alone. Left out, the whole readable subtree."
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100
+ }
+ }
+ },
+ "MemoryRecall": {
+ "type": "object",
+ "required": [
+ "results",
+ "degraded",
+ "abstain"
+ ],
+ "properties": {
+ "results": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "record",
+ "memory"
+ ],
+ "properties": {
+ "record": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "memory": {
+ "type": "object",
+ "description": "The memory this result is in, the one asked or one below it.",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "score": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "why": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "parent": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ },
+ "children": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryNeighbour"
+ }
+ },
+ "degraded": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "What the request asked for and was not done."
+ },
+ "abstain": {
+ "type": "boolean",
+ "description": "True when the provider judges that nothing it returned answers the question."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryGraphRequest": {
+ "type": "object",
+ "properties": {
+ "around": {
+ "type": "string",
+ "description": "A record to start from. Left out, every record of this memory."
+ },
+ "hops": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 3,
+ "description": "References away from the start, in either direction. Default 1."
+ },
+ "types": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1
+ }
+ }
+ },
+ "MemoryRecordRef": {
+ "type": "object",
+ "description": "A record by where it is. `memory_id` is absent on the far end of an edge the caller may not follow.",
+ "required": [
+ "record_id"
+ ],
+ "properties": {
+ "memory_id": {
+ "type": "string"
+ },
+ "record_id": {
+ "type": "string"
+ }
+ }
+ },
+ "MemoryGraph": {
+ "type": "object",
+ "required": [
+ "nodes",
+ "edges",
+ "truncated"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "memory.graph"
+ },
+ "nodes": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "record",
+ "memory"
+ ],
+ "properties": {
+ "record": {
+ "$ref": "#/$defs/MemoryRecord"
+ },
+ "memory": {
+ "type": "object",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "from",
+ "to",
+ "available"
+ ],
+ "properties": {
+ "from": {
+ "$ref": "#/$defs/MemoryRecordRef"
+ },
+ "to": {
+ "$ref": "#/$defs/MemoryRecordRef"
+ },
+ "rel": {
+ "type": "string",
+ "description": "What the reference means. Absent when the target is not readable by the caller."
+ },
+ "available": {
+ "type": "boolean"
+ }
+ }
+ }
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "degraded": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryErase": {
+ "type": "object",
+ "required": [
+ "record_ids"
+ ],
+ "properties": {
+ "record_ids": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "MemoryErasure": {
+ "type": "object",
+ "required": [
+ "erased",
+ "unreachable"
+ ],
+ "properties": {
+ "erased": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "unreachable": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Content the provider could not remove. Empty is a guarantee."
+ }
+ }
+ },
+ "MemoryQuery": {
+ "type": "object",
+ "required": [
+ "body"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "params": {
+ "type": "object",
+ "additionalProperties": true,
+ "description": "A JSON Schema for the parameters."
+ },
+ "requires": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write"
+ ]
+ },
+ "language": {
+ "type": "string",
+ "description": "Opaque to the protocol."
+ },
+ "body": {
+ "type": "string",
+ "description": "Opaque to the protocol."
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryQueryList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryQuery"
+ }
+ }
+ }
+ },
+ "MemoryQueryRun": {
+ "type": "object",
+ "properties": {
+ "params": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryFreeQuery": {
+ "type": "object",
+ "required": [
+ "statement"
+ ],
+ "properties": {
+ "language": {
+ "type": "string"
+ },
+ "statement": {
+ "type": "string"
+ },
+ "params": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "write": {
+ "type": "boolean"
+ }
+ }
+ },
+ "MemoryOperationResult": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "result": {}
+ }
+ },
+ "MemorySnapshot": {
+ "type": "object",
+ "required": [
+ "id",
+ "name",
+ "at"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.snapshot"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ },
+ "at": {
+ "type": "string"
+ }
+ }
+ },
+ "MemorySnapshotCreate": {
+ "type": "object",
+ "required": [
+ "name"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
+ "MemorySnapshotList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemorySnapshot"
+ }
+ }
+ }
+ },
+ "MemoryConsolidation": {
+ "type": "object",
+ "required": [
+ "id",
+ "status"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "memory.consolidation"
+ },
+ "memory_id": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "queued",
+ "running",
+ "completed",
+ "stopped",
+ "failed"
+ ]
+ },
+ "trigger": {
+ "type": "string"
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "finished_at": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "read": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "changes": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "usage": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "budget": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "written_by": {
+ "$ref": "#/$defs/MemoryWriter"
+ },
+ "error": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryConsolidationStart": {
+ "type": "object",
+ "properties": {
+ "budget": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ },
+ "MemoryConsolidationList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryConsolidation"
+ }
+ }
+ }
+ },
+ "MemoryProvider": {
+ "type": "object",
+ "required": [
+ "id",
+ "isolation"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "isolation": {
+ "type": "string",
+ "enum": [
+ "container",
+ "enforced_filter"
+ ]
+ },
+ "derivation": {
+ "type": "string",
+ "enum": [
+ "write_time",
+ "background",
+ "agent",
+ "none"
+ ]
+ },
+ "prime": {
+ "type": "boolean",
+ "description": "Whether the provider answers the prime read with its standing records."
+ },
+ "holds": {
+ "type": "boolean",
+ "description": "Whether the provider ends and links facts by `attributes.holds`."
+ },
+ "observe": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "recall": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "history": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "erase": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "queries": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "graph": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "string",
+ "enum": [
+ "derived",
+ "stated",
+ "none"
+ ],
+ "description": "Where a memory's entities come from on this provider."
+ }
+ },
+ "additionalProperties": true
+ },
+ "content": {
+ "type": "object",
+ "description": "What the content of a record may carry on this provider.",
+ "properties": {
+ "media": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "description": "Media types kept, as patterns such as `text/*` or `image/*`."
+ },
+ "bytes": {
+ "type": "string",
+ "enum": [
+ "kept",
+ "referenced"
+ ]
+ },
+ "describes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryProviderList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryProvider"
+ }
+ }
+ }
+ },
+ "MemoryType": {
+ "type": "object",
+ "required": [
+ "type"
+ ],
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "core": {
+ "type": "boolean"
+ },
+ "description": {
+ "type": "string"
+ },
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "text": {
+ "type": "string"
+ },
+ "operations": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "required": [
+ "name",
+ "requires"
+ ],
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "input": {
+ "type": "object",
+ "additionalProperties": true
+ },
+ "requires": {
+ "$ref": "#/$defs/MemoryPrivilege"
+ }
+ }
+ }
+ }
+ },
+ "additionalProperties": true
+ },
+ "MemoryTypeList": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/MemoryType"
+ }
+ }
+ }
+ },
+ "HarnessMemorySettings": {
+ "type": "object",
+ "properties": {
+ "default_memory_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Where an unaddressed remember goes and where turns are recorded. A memory the agent may write."
+ },
+ "observe": {
+ "type": "boolean",
+ "description": "Record each finished turn in the default memory. On by default."
+ }
+ }
+ },
+ "HarnessMemories": {
+ "type": "object",
+ "required": [
+ "principal",
+ "data"
+ ],
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "harness.memories"
+ },
+ "principal": {
+ "type": "string",
+ "description": "Who this harness's agent is to the access model, `member:<id>`. A grant names it."
+ },
+ "default_memory_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "observe": {
+ "type": "boolean"
+ },
+ "data": {
+ "type": "array",
+ "description": "Every memory the agent holds a grant on, highest in the tree first. Read off the grants.",
+ "items": {
+ "type": "object",
+ "required": [
+ "id",
+ "privileges"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "privileges": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "read",
+ "write",
+ "create",
+ "delete"
+ ]
+ }
+ },
+ "default": {
+ "type": "boolean"
+ }
+ },
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/protocol/site/build.py b/protocol/site/build.py
index be27a2bb..e6515a07 100644
--- a/protocol/site/build.py
+++ b/protocol/site/build.py
@@ -29,14 +29,14 @@ except ImportError: # pragma: no cover
HERE = pathlib.Path(__file__).parent
ROOT = HERE.parent # protocol/
DIST = HERE / "dist"
-VERSION = "2026-10-04"
+VERSION = "2026-10-19"
# Published specification versions, latest first. The spec is served under a per-version path
# (/spec/<date>/…, mirroring MCP's /specification/<date>/…) so every version keeps a permanent
# address: a citation to the 2026-08-11 architecture never silently becomes a later version. Only
# the specification is versioned this way; conformance, governance and versioning are living docs.
# Every version listed is built from its own frozen tree under protocol/versions/<date>/; the latest
# is the one in the sidebar, the rest are served at their dated addresses with a notice.
-VERSIONS = ["2026-10-04", "2026-09-28", "2026-09-12", "2026-08-11"]
+VERSIONS = ["2026-10-19", "2026-10-04", "2026-09-28", "2026-09-12", "2026-08-11"]
SITE = "unifiedharnessprotocol.org"
# The specification's chapters, in reading order. NAV builds their per-version paths from this so
diff --git a/protocol/vercel.json b/protocol/vercel.json
index b472d114..bf2b7b4a 100644
--- a/protocol/vercel.json
+++ b/protocol/vercel.json
@@ -6,9 +6,9 @@
"cleanUrls": true,
"trailingSlash": false,
"redirects": [
- { "source": "/spec", "destination": "/spec/2026-10-04", "permanent": false },
- { "source": "/spec/index", "destination": "/spec/2026-10-04", "permanent": false },
- { "source": "/spec/:chapter(architecture|lifecycle|harnesses|plugins|environments|memories|tasks|streaming|sessions|files|errors|security|schema)", "destination": "/spec/2026-10-04/:chapter", "permanent": false }
+ { "source": "/spec", "destination": "/spec/2026-10-19", "permanent": false },
+ { "source": "/spec/index", "destination": "/spec/2026-10-19", "permanent": false },
+ { "source": "/spec/:chapter(architecture|lifecycle|harnesses|plugins|environments|memories|tasks|streaming|sessions|files|errors|security|schema)", "destination": "/spec/2026-10-19/:chapter", "permanent": false }
],
"headers": [
{
diff --git a/protocol/versions/2026-10-19/architecture.md b/protocol/versions/2026-10-19/architecture.md
new file mode 100644
index 00000000..24ec5957
--- /dev/null
+++ b/protocol/versions/2026-10-19/architecture.md
@@ -0,0 +1,150 @@
+# Architecture
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and
+OPTIONAL in this specification are to be interpreted as described in [RFC 2119][rfc2119] and
+[RFC 8174][rfc8174] when, and only when, they appear in all capitals.
+
+[rfc2119]: https://www.rfc-editor.org/rfc/rfc2119
+[rfc8174]: https://www.rfc-editor.org/rfc/rfc8174
+
+## 1. Roles
+
+```
+┌──────────┐ UHP over HTTP ┌──────────┐ implementation-defined ┌──────────┐
+│ Client │ ────────────────▶ │ Server │ ─────────────────────────▶ │ Harness │
+└──────────┘ └──────────┘ └──────────┘
+```
+
+**Client** — an application that wants work done: a product backend, a CLI, a CI job, another agent.
+A client speaks only UHP. It MUST NOT be required to know which harness implementation runs behind
+the server, nor how the server executes it.
+
+**Server** — implements this specification. It accepts tasks, drives one or more harnesses, and
+reports progress and results in the vocabulary defined here. Everything about *how* it runs a
+harness — containers, subprocesses, queues, remote workers — is out of scope for this specification
+and MUST NOT leak into the wire format.
+
+**Harness** — a complete agent runtime with its own loop, tools and session state. UHP does not
+specify the harness itself; it specifies how a client drives one through a server. Harnesses are
+identified by a **base**: a stable string such as `codex`, `claude-code` or `hermes`.
+
+A **configured harness** is a base plus configuration — default model, system prompt, tool
+restrictions, skills, MCP servers, step and time budgets. It is the unit a client selects when it
+sends work, and it is addressed by a server-assigned id.
+
+> **Why a configured harness, and not just a base?**
+> The same base behaves very differently with a different system prompt, a different model, or a
+> different tool set. Making the configuration a first-class, addressable object means a product can
+> change how its agent behaves without redeploying its backend, and means two products can share a
+> server without sharing behaviour.
+
+## 2. Conformance classes
+
+A server declares which class it implements. Each class is cumulative: **Extended** includes
+**Core**, **Full** includes **Extended**.
+
+| Class | A server at this class MUST implement |
+|---|---|
+| **Core** | Capability discovery, harness discovery, non-streaming and streaming task execution, session continuation, cancellation, and the error model. |
+| **Extended** | Core, plus file input, artifact retrieval, and session listing/inspection. |
+| **Full** | Extended, plus harness lifecycle management (create, update, delete) and session sharing. |
+
+A client MUST NOT assume any capability above **Core** without checking capability discovery
+(see [Lifecycle §2](lifecycle.md)). A server MUST NOT advertise a capability it does not implement —
+advertising is a promise, and a client that trusts it and receives a `404` has been lied to in a way
+it cannot recover from.
+
+The [conformance suite](../../conformance/) tests each class separately and reports per class. A
+server that passes at a class MAY describe itself as "UHP <version> conformant (<class>)", naming
+the version its discovery document serves as `default_version`, which the suite reports. No
+other use of the term "conformant" is meaningful.
+
+## 3. Object model
+
+Seven object types. Every one carries an `object` field naming its type, and an `id` with a
+type-distinguishing prefix so an identifier is never ambiguous about what it points at.
+
+| Object | `object` value | Id prefix | Lifetime |
+|---|---|---|---|
+| Harness | `harness` | `chrn_` | Until deleted |
+| Response | `response` | `resp_` | Retained per server policy |
+| Session | `session` | `hsess` | Until deleted |
+| File | `file` | `file_` | With its container |
+| Container | `container` | `cntr_` | With its session |
+| Environment | `environment` | `henv_` | Until deleted; optional, see [Environments](environments.md) |
+| Memory | `memory` | `hmem_`, or the id of the tree a server maps | Until deleted; optional, see [Memories](memories.md) |
+| Event | *(none — events carry `type`)* | — | Streamed, and replayable |
+
+Their relationships:
+
+```
+Harness ──┐
+ ├──▶ Session ──┬──▶ Response ──▶ Response ──▶ … (one per task, chained)
+Model ───┘ └──▶ Container ──▶ File, File, … (artifacts)
+```
+
+- A **response** is one task: one request in, one result out. It is the atomic unit of work.
+- A **session** is a chain of responses that share conversational context and a working directory.
+ A session is created implicitly by the first task and extended by `previous_response_id`.
+- A **container** is the file namespace of a session. Files the agent writes become artifacts in it.
+- An **environment** is a project's files and installed dependencies, built once and mounted read-only
+ into every session that names it; a harness names one as the default for its tasks. It is never
+ part of a container: artifacts come from the working directory, the environment is what the
+ working directory reads ([Environments](environments.md)).
+- A **memory** is a place that outlasts every session: a node in a tree, holding records, with access
+ granted per node and inherited downward. An agent is granted memories as a person is; a memory is
+ never part of a session or a container ([Memories](memories.md)).
+
+> **Why is the session implicit?**
+> Requiring `POST /sessions` before any work could be done would add a round trip, a failure mode,
+> and an object to clean up — for a concept most first tasks never need. A client that only ever
+> sends one-shot tasks never learns the word "session"; a client that needs continuity gets it by
+> quoting the id it already has.
+
+## 4. Transport
+
+- All requests MUST be HTTP/1.1 or later over TLS, except for loopback development where a server
+ MAY accept plaintext.
+- Request and response bodies are `application/json; charset=utf-8`, except file upload
+ (`multipart/form-data`) and file download (the file's own media type).
+- Streaming uses Server-Sent Events (`text/event-stream`) as described in
+ [Streaming](streaming.md).
+- Servers MUST accept requests with an absent `Accept` header and default to JSON.
+
+## 5. Authentication
+
+A client authenticates with a bearer token:
+
+```http
+Authorization: Bearer <token>
+```
+
+How tokens are issued is out of scope. A server MUST reject an absent, malformed, or unknown token
+with `401` and the error model in [Errors](errors.md), and MUST NOT distinguish "no such token"
+from "token not permitted here" in a way that lets a caller enumerate valid tokens.
+
+A server MUST scope every object to the principal that created it. A client MUST NOT be able to
+read, continue, cancel or delete another principal's response, session, or file — including by
+guessing an id. Servers MUST return `404`, not `403`, for objects outside the caller's scope, so
+that an id's existence is not disclosed.
+
+## 6. Design principles
+
+These are the rules the specification holds itself to. They are included because they explain the
+shape of what follows, and because a future change that violates one is probably a mistake.
+
+1. **The client should not be able to tell which harness ran the work** — except by asking. Every
+ difference between harnesses that a client can observe is a leak, and each leak is a place where
+ swapping harnesses breaks a product.
+2. **Progress is a stream of facts, not a rendering.** Events describe what happened — text, a tool
+ call, a file — never how to display it.
+3. **A field means one thing.** Where UHP extends a borrowed surface, it adds fields; it never
+ redefines one.
+4. **Absent is not empty, and empty is not zero.** A server that does not know a value omits it. It
+ MUST NOT invent a placeholder, an estimate, or a zero.
+5. **Failure is a first-class result.** Every failure is reportable in the same envelope as success,
+ with a machine-readable code. A client should never have to parse prose to find out what to do.
+6. **The specification, the reference implementation and the conformance suite move together.** A
+ sentence here that no test enforces is a wish, not a standard.
diff --git a/protocol/versions/2026-10-19/environments.md b/protocol/versions/2026-10-19/environments.md
new file mode 100644
index 00000000..1b7bc6da
--- /dev/null
+++ b/protocol/versions/2026-10-19/environments.md
@@ -0,0 +1,298 @@
+# Environments
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A session's working directory ([Architecture §3](architecture.md#3-object-model)) is made for one
+conversation: it is created empty, kept across turns, and everything the agent needs is put there
+again for every session that needs it. That is the right shape for a task's own files and the wrong
+shape for a project: a content pipeline with its scripts, assets, templates and a hundred installed
+packages, opened by many people, many times a day. Installed into a working directory it is
+installed once per session, uploaded once per session, and a session's checkpoint carries none of
+it forward.
+
+An **environment** is that project as one object: its files and its installed dependencies, built
+once, and read by every session that names it. A session sees it at a fixed path, read-only, beside
+its own working directory, which stays writable, private, and the only place artifacts come from.
+
+This chapter is the Environments sub-protocol. It is optional: a server advertises it with the
+`environments` capability, and a server that does not implement it is conformant at every class.
+
+## 1. What an environment is
+
+```
+/env/content-studio the environment: complete, read-only, shared (this chapter)
+ scripts/ assets/ data/ the project's files, as the owner put them in
+ .venv/ node_modules/ its dependencies, installed once when it was built
+<working directory> the session's own: writable, private, checkpointed (Files chapter)
+```
+
+Three rules make it one thing rather than a shared folder:
+
+- **It is built, not copied.** The owner puts files in ([§3](#3-files)); a build ([§4](#4-builds-and-versions))
+ snapshots them into a version and installs what the project's manifests declare, in the server's
+ own toolchain. Dependency directories that arrive with the files are not what a session gets;
+ what the build installed is. A virtualenv made on a laptop does not run in a container, and the
+ build is what makes the promise "no reinstall" true.
+- **A session reads the active version and cannot write it.** Two sessions on one environment share
+ every byte of it and none of each other's working directory. A server MUST refuse writes into the
+ environment from a session: the path is read-only, not merely described as such.
+- **The path is fixed.** The server tells the client where the environment is mounted (`mount`) and
+ tells the agent the same, so a project's scripts can be run by absolute path from any working
+ directory, and their outputs land where the user sees them.
+
+> **Why not let the session start inside the project?**
+> A working directory that *is* the project, copy-on-write, reads well until two facts collide:
+> artifacts and project files are then the same directory, so the server can no longer say which
+> files a task produced, and every write must be layered by a mechanism (overlay filesystems,
+> per-session copies) that not every sandbox has. Two paths, one of them read-only, keeps both
+> answers simple: what the task produced is in the working directory, what the project is stays in
+> the environment.
+
+## 2. The environment object
+
+```json
+{
+ "id": "henv_2f1c9d4e8a7b4c3d9e6f5a4b3c2d1e0f",
+ "object": "environment",
+ "name": "Content Studio",
+ "slug": "content-studio",
+ "description": "The teaser pipeline: episodes in, teasers and thumbnails out.",
+ "entry": "python3 run.py --episode <id>",
+ "status": "ready",
+ "mount": "/env/content-studio",
+ "version": 3,
+ "latestVersion": 3,
+ "files": { "count": 16, "bytes": 48213 },
+ "packages": [ { "manager": "pip", "name": "moviepy", "version": "2.1.1" },
+ { "manager": "npm", "name": "sharp", "version": "0.33.5" } ],
+ "versions": [ { "version": 3, "status": "ready", "started_at": 1790570000, "finished_at": 1790570094, "packages": 10 } ],
+ "build": { "version": 3, "status": "ready", "started_at": 1790570000, "finished_at": 1790570094, "error": "" },
+ "createdAt": 1790560000000,
+ "updatedAt": 1790570094000
+}
+```
+
+| Field | Type | Written by | Meaning |
+|---|---|---|---|
+| `id` | string | server | `henv_`-prefixed ([Architecture §3](architecture.md#3-object-model)) |
+| `name` | string | client | Human-readable; must begin with a letter or digit |
+| `slug` | string | server | The path segment sessions see, derived from the name at creation. It never changes: a session's instructions name it |
+| `description` | string | client | |
+| `entry` | string | client | How the project is run, in the owner's words. Repeated to the agent verbatim ([§6](#6-what-a-session-sees)) |
+| `status` | string | server | `empty` (nothing built), `building` (a build is running, whichever version is active: a task keeps reading the active one), `ready` (a version is active), `failed` (the latest build failed and none is active) |
+| `mount` | string | server | Where a session finds it, read-only. `/env/<slug>` on the reference server; a server MAY choose another root, and MUST keep it constant for the environment's lifetime |
+| `version` | integer or null | server | The active build, the one sessions read |
+| `latestVersion` | integer or null | server | The newest build, active or not |
+| `files` | object | server | The source's size: what the owner put in, before any build |
+| `packages` | array | server | What the active build installed, as the package managers report it: `manager`, `name`, `version` |
+| `declared` | object | client | What the owner declared, per manager, as spec strings the build installs beside the project's manifests: `pip` (`moviepy==2.1.1`), `npm` (`[email protected]`), `apt` (`ffmpeg`); read back with each spec's `name` and `version` |
+| `runtime` | object | client | `python`: the interpreter a build makes the virtual environment with, one of `GET /v1/environments/runtimes`; empty for the server's default |
+| `versions` | array | server | Every build: `version`, `status`, times, `error`, size |
+| `build` | object or null | server | The latest build's status, and its `stage` while it runs |
+
+Environments are scoped like harnesses: a caller sees the environments of its own scope
+([Architecture §5](architecture.md#5-authentication)), and a harness may name only an environment
+of the same scope.
+
+```http
+POST /v1/environments create (name, description, entry)
+GET /v1/environments list
+GET /v1/environments/{id} one, with its versions
+PUT /v1/environments/{id} rename; description; entry
+DELETE /v1/environments/{id} delete every version
+```
+
+`POST` refuses a name that yields no path segment with `environment_invalid`, and a slug another
+environment already occupies with `environment_exists`: the mount path is a place, and two
+environments cannot be in it. `DELETE` refuses while a build runs (`environment_busy`). A harness
+that named a deleted environment keeps the reference; its next task is refused with
+`environment_not_found` ([§5](#5-attaching-an-environment)).
+
+## 3. Files
+
+The source is edited by path, the way a plugin's package is ([Plugins §2.1](plugins.md#21-files)),
+but one file per request, because a project is larger than a package:
+
+```http
+GET /v1/environments/{id}/files the tree: every file and directory, with sizes
+GET /v1/environments/{id}/files/{path} one file's bytes, with its content type
+PUT /v1/environments/{id}/files/{path} write one file (the body is its bytes; its directories are made)
+POST /v1/environments/{id}/directories make an empty directory: {"path": "assets/brand"}
+DELETE /v1/environments/{id}/files/{path} remove a file or a directory tree
+POST /v1/environments/{id}/import a whole project at once
+```
+
+- `path` is relative to the environment's root. A server MUST refuse a path that escapes the root,
+ or names anything other than a regular file or directory, with `environment_invalid`.
+- A server MUST preserve bytes as sent, and MUST refuse an oversized file with `file_too_large`
+ (`detail.max_bytes` states the limit) rather than truncating it.
+- Writing the source changes nothing a session sees until the next build ([§4](#4-builds-and-versions)).
+
+### 3.1 Import
+
+A project arrives as one thing. `POST /v1/environments/{id}/import` takes either an archive (a zip
+or a tar, as the request body with any content type but `application/json`) or a JSON body naming
+a git repository:
+
+```json
+{ "git": { "url": "https://github.com/example/content-studio", "ref": "main" }, "replace": true }
+```
+
+The tree is kept as it is in the archive or repository. A single directory wrapping everything (the
+shape of a repository archive) is stripped, so the project's root is the environment's root.
+Members that must not land, links and paths that escape the root, are dropped and counted in
+`skipped`, never written. `replace` clears the source first; without it the import lands over what
+is there. Dependency directories in an archive (`node_modules`, `.venv`) are not copied into a
+build; the build installs from the manifests ([§4](#4-builds-and-versions)).
+
+## 4. Builds and versions
+
+```http
+GET /v1/environments/runtimes what a build can be made with here: Python minors, Node major, the OS
+GET /v1/environments/packages/check?manager=&spec= what the manager's registry says about a spec, before any build (MAY)
+POST /v1/environments/{id}/build start a build: the next version
+GET /v1/environments/{id}/builds/{version} its record: status, log, packages, size
+GET /v1/environments/{id}/versions every build, and which one is active
+POST /v1/environments/{id}/versions/{version}/activate make a finished build the active one
+```
+
+A build snapshots the source into a new version and installs what the project declares:
+
+| Manifest at the root | What the build runs |
+|---|---|
+| declared `pip` | the same virtual environment (made with `runtime.python` when the server has it), then `pip install` of each spec |
+| declared `npm` | `npm install` of each spec into `node_modules` |
+| declared `apt` | the named packages and the dependencies the image lacks, downloaded by apt and unpacked with dpkg under `apt/` in the version, which a session gets on `PATH` and `LD_LIBRARY_PATH`; nothing is installed into the server |
+| `requirements.txt` | a Python virtual environment at `.venv`, then `pip install -r requirements.txt` |
+| `pyproject.toml` | the same virtual environment, then `pip install .` |
+| `package.json` | `npm ci` when a lockfile is present, else `npm install`, into `node_modules` |
+| `setup.sh` | run last, in the version's directory, for what the manifests cannot say |
+
+A server MAY support other manifests and MUST document which it runs. Installs happen in the
+server's own toolchain, the one sessions run in, so what the build installed runs where the
+session runs. Nothing else is written into the version after the build: the layer is made
+read-only and stays so.
+
+`POST …/build` returns at once with the version number; the record at `…/builds/{version}` says
+`building`, then `ready` or `failed`, with the installers' own output as `log` and the failure's
+reason as `error`. While it builds, the record says which step is running as `stage` (on the
+reference server: `copying files`, `python packages`, `node packages`, `system packages`,
+`setup.sh`, `finishing`) and carries the log so far, so a client can show progress rather than a
+spinner; a server MUST write the record as steps end, not only at the end of the build. The
+environment's `status` is `building` meanwhile, even when a version is active, and a task on it
+keeps reading the active version. One build runs at a time per environment (`environment_busy`).
+When a build
+succeeds it becomes the active version: the next session to start reads it. A session that started
+earlier keeps the version it started with for the rest of its turn; a server SHOULD let it keep
+that version for later turns too, and MUST say which version a turn read ([§6](#6-what-a-session-sees)).
+
+A failed build changes nothing: the previous active version stays active, and `status` says
+`failed` only when no version is active at all. Rolling back is `POST …/versions/{n}/activate` on
+an earlier finished build; nothing is rebuilt, and a version that never finished cannot be
+activated (`environment_not_ready`).
+
+A server MAY answer `GET /v1/environments/packages/check?manager=&spec=` with what the manager's
+registry says about a spec before any build: whether the name exists, its latest version, and
+whether an exact pin is published (`EnvironmentPackageCheck`: `manager`, `name`, `spec`, `exists`
+true, false, or null when the registry could not be asked, `latest`, `version` for a published
+pin, `error` in words). A client that offers it refuses a typo where it is typed instead of
+failing a build minutes later; a client MUST NOT require it, and a server without it answers
+`404`. The reference server asks PyPI, the npm registry, and its own apt lists.
+
+> **Why versions rather than a rebuild in place?**
+> A rebuild in place would change a layer that sessions are reading at that moment, and a
+> failed one would leave them nothing. Versions make a build atomic from the session's side:
+> the old layer is whole until the new one is, and the switch is one pointer.
+
+## 5. Attaching an environment
+
+A harness names the environment its tasks read, and a task may name a different one:
+
+```json
+{ "name": "Teaser cutter", "base": "codex", "environment": "henv_2f1c9d4e8a7b4c3d9e6f5a4b3c2d1e0f" }
+```
+
+```json
+{ "input": "Render the teaser for episode 12.",
+ "metadata": { "harness_id": "chrn_…", "environment": "henv_2f1c9d4e8a7b4c3d9e6f5a4b3c2d1e0f" } }
+```
+
+- `environment` on a harness ([Harnesses §2](harnesses.md#2-the-harness-object)) is the default
+ for every task of that harness; `metadata.environment` on a task overrides it for that task.
+ The response reports the environment the task read as `metadata.environment`, beside
+ `metadata.session_id`.
+
+> **Why is the task's environment in `metadata` rather than a top-level field?**
+> For the reason the harness is ([Tasks §1.2](tasks.md#12-selecting-the-harness)): the task surface
+> is a Responses request, and `metadata` is the extension point that surface defines for
+> caller-supplied context. A harness and a session are this protocol's own objects, so on them
+> `environment` is an ordinary field; a task request is not, so on it the environment travels
+> where the harness does. Every Responses SDK can send it today.
+- A server MUST refuse a harness write that names an environment outside the caller's scope, or
+ none at all, with `environment_not_found`.
+- A server MUST refuse a task whose environment is not `ready` **before the task starts**:
+ `environment_not_found` for one that is not there, `environment_not_ready` for one with nothing
+ built. A task that fails minutes later for want of its project is the outcome this rule exists
+ to prevent.
+- `GET /v1/environments/{id}/harnesses` lists the harnesses that name it, so an owner sees what a
+ rebuild will reach.
+
+## 6. What a session sees
+
+For a task that runs with an environment, a server MUST:
+
+1. mount the active version at `mount`, read-only, before the agent starts;
+2. keep the session's working directory as it was: writable, private to the session, the source of
+ its artifacts ([Files §2](files.md#2-getting-artifacts-out)), and unchanged in how it is
+ checkpointed. The environment is never part of a checkpoint;
+3. make the environment's installed dependencies the ones the agent's shell runs: on the reference
+ server `PATH` begins with the version's `.venv/bin` and `node_modules/.bin`, `PYTHONPATH` and
+ `NODE_PATH` begin with the environment, `PROJECT_ROOT` names `mount`;
+4. tell the agent, in its instructions, where the project is, that it is read-only and shared, that
+ its dependencies are installed, where to write, and the `entry` when the owner gave one;
+5. record which environment and version the turn read: the response carries
+ `metadata.environment`, the session object carries `environment`
+ ([Sessions §3](sessions.md#3-inspecting-a-session)), and the turn's record the version.
+
+Two sessions on one environment MUST NOT be able to read each other's working directory or write
+the environment. A session MUST NOT be able to read an environment its task did not name, nor to
+enumerate the environments a server holds. How a server enforces that is its own business: a
+per-session container with a read-only mount, a per-session user and a per-environment group
+without write permission on a shared directory, or a copy made read-only. What a client may rely
+on is the outcome.
+
+## 7. Discovery
+
+```json
+{ "capabilities": { "environments": true } }
+```
+
+A server that reports `environments: true` implements every endpoint in this chapter. One that
+does not implement the chapter reports `false` or omits it, and MUST answer the endpoints with
+`404`, never with a partial implementation.
+
+## 8. Errors
+
+| Code | Status | When |
+|---|---|---|
+| `environment_not_found` | 404 | No such environment in the caller's scope; on a harness write or a task, the referenced one |
+| `environment_not_ready` | 409 | A task on an environment with no active version; activating a version that never finished |
+| `environment_busy` | 409 | A build is running: a second build, or a delete |
+| `environment_exists` | 409 | The name's slug is another environment's mount |
+| `environment_invalid` | 422 | A name that is no path segment; a file path that escapes the root; an import that is neither archive nor repository |
+| `environment_unavailable` | 502 or 503 | The server's build or storage backend did not answer |
+| `file_too_large` | 413 | A file or an import over the server's limit ([Files §1](files.md#1-sending-files-in)) |
+
+## 9. Security
+
+- The build runs the project's own manifests and `setup.sh` with the server's toolchain and network.
+ A server MUST run it with no more privilege than a task gets, and MUST NOT let it read another
+ environment or any session. On a single-tenant self-hosted server the owner is the only author;
+ a multi-tenant server treats a build as a task of the tenant that owns the environment.
+- Read-only is enforced, not described ([§6](#6-what-a-session-sees)). An agent told not to write
+ will still try; the write must fail.
+- A file path is confined to the environment's root at every endpoint ([§3](#3-files)), and an
+ imported archive's members are confined the same way: links out of the root and absolute paths
+ are dropped, never followed.
+- Environments are scoped with the harnesses that use them; a harness cannot name an environment
+ of another scope ([§5](#5-attaching-an-environment)).
diff --git a/protocol/versions/2026-10-19/errors.md b/protocol/versions/2026-10-19/errors.md
new file mode 100644
index 00000000..f394a548
--- /dev/null
+++ b/protocol/versions/2026-10-19/errors.md
@@ -0,0 +1,145 @@
+# Errors
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A client's error handling is only as good as the server's error reporting. This chapter defines one
+envelope, a closed set of codes, and which failures are worth retrying.
+
+## 1. The error envelope
+
+Every non-2xx response MUST have this body:
+
+```json
+{
+ "error": {
+ "type": "invalid_request_error",
+ "code": "harness_not_found",
+ "message": "No harness with id 'chrn_deadbeef'.",
+ "param": "metadata.harness_id",
+ "detail": null
+ }
+}
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `type` | string | yes | Broad class; see §2 |
+| `code` | string | yes | Specific, machine-readable reason; see §3 |
+| `message` | string | yes | Human-readable, one sentence, no stack trace |
+| `param` | string \| null | yes | Dotted path to the offending field, when there is one |
+| `detail` | object \| null | yes | Structured extra context, or `null` |
+
+Rules:
+
+- `message` MUST be safe to show a user. It MUST NOT contain credentials, internal hostnames, file
+ paths, or stack traces.
+- `code` MUST come from §3 where one applies. A server MAY define additional codes for conditions
+ this specification does not cover, and MUST namespace them with a vendor prefix (`acme_…`) so a
+ future version of this specification cannot collide with them.
+- A server MUST NOT return `200` with an error inside. The failure of a *task* is reported as a
+ response with `status: "failed"` and HTTP `200`, because the request succeeded; the failure of a
+ *request* is a non-2xx with this envelope. Those are different events and MUST NOT be conflated.
+
+> **Compatibility note.** A server MAY additionally include a top-level `detail` string alongside
+> `error`, for clients written against implementations that predate this envelope. That field is
+> deprecated, carries no information not in `error.message`, and will be removed in a future version.
+
+## 2. Error types
+
+| `type` | HTTP | Meaning |
+|---|---|---|
+| `invalid_request_error` | 400, 404, 409, 413, 422 | The request was wrong. Retrying it unchanged will fail again. |
+| `authentication_error` | 401 | The credential is missing, malformed or unknown. |
+| `permission_error` | 403 | Authenticated, but not allowed to do this. |
+| `rate_limit_error` | 429 | Too many requests, or a quota is exhausted. |
+| `harness_error` | 200 (in a failed response) | The harness ran and failed. |
+| `server_error` | 500, 502, 503, 504 | The server failed. Retrying MAY succeed. |
+
+## 3. Error codes
+
+### 3.1 Request and routing
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `unsupported_protocol_version` | 400 | `UHP-Version` names a version this server cannot serve. `detail.supported` lists what it can. |
+| `invalid_input` | 400 | The body could not be parsed, or a field has the wrong type. |
+| `harness_not_found` | 404 | No such harness in the caller's scope. |
+| `response_not_found` | 404 | No such response in the caller's scope. |
+| `session_not_found` | 404 | No such session in the caller's scope. |
+| `plugin_not_found` | 404 | The harness has no plugin of that name. |
+| `file_not_found` | 404 | No such file in the caller's scope. |
+| `session_expired` | 404 | The session existed but is past its retention. |
+| `harness_mismatch` | 409 | The task named a different harness than the session it continues. |
+| `session_busy` | 409 | A task is already running in this session. |
+| `harness_busy` | 409 | A harness that retires its sessions with it has a task in progress; it is not retired mid-task ([Harnesses §5.3](harnesses.md#53-delete)). |
+| `plugin_conflict` | 409 | Two plugins share a name, or a component name collides across the harness and its plugins. `detail.component`, `detail.name` and `detail.between` say which. |
+| `file_too_large` | 413 | The upload exceeds the server's limit. `detail.max_bytes` states it. |
+| `model_unavailable` | 422 | The requested model cannot be served for this harness. |
+| `model_not_available` | 422 | A harness create or update named a `default_model` its base does not run ([Harnesses §5.1](harnesses.md#51-create)). |
+| `unsupported_base` | 422 | The requested harness base is not supported by this server. |
+| `environment_not_found` | 404 | No such environment in the caller's scope, on a read, a harness write or a task ([Environments §8](environments.md#8-errors)). |
+| `environment_not_ready` | 409 | A task on an environment with no active version, or activating an unfinished build. |
+| `environment_busy` | 409 | A build is running: a second build or a delete must wait. |
+| `environment_exists` | 409 | The name's slug is already another environment's mount path. |
+| `environment_invalid` | 422 | A name that is no path segment, a file path that escapes the root, or an import that is neither archive nor repository. |
+| `environment_unavailable` | 502 | The server's build or storage backend did not answer. |
+| `memory_not_found` | 404 | No such memory, or one the caller holds no privilege on: the two are one answer ([Memories §12](memories.md#12-errors)). |
+| `memory_forbidden` | 403 | The caller sees the memory and lacks the privilege the operation needs. |
+| `memory_record_not_found` | 404 | No such record in this memory. |
+| `memories_not_attached` | 404 | The agent holds no memory: nothing was granted to it. |
+| `memory_invalid` | 422 | A parent that would make a cycle, two default entries, a record with no content, a query whose parameters do not match. |
+| `memory_unsupported` | 422 | An operation the memory's provider does not implement at all. A partial answer is reported in `degraded`, not as this. |
+| `memory_busy` | 409 | A move or a delete while a consolidation runs. |
+| `memory_unavailable` | 502 or 503 | The memory's provider did not answer, or is not connected. |
+| `plugin_invalid` | 422 | The package is not a valid Agent Plugins package: no manifest, a fatal manifest error, a path that escapes the root, or a `name` that contradicts the manifest. `detail.path` and `detail.reason` say where. |
+| `unsupported_plugin_schema` | 422 | The manifest's `$schema` names an Agent Plugins version this server does not install. `detail.supported` lists what it does. |
+| `unsupported_transport` | 422 | A plugin declares an MCP server whose transport cannot be run for this harness base. `detail.transport` and `detail.base` say which. |
+
+### 3.2 Authentication and limits
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `missing_credential` | 401 | No bearer token. |
+| `invalid_credential` | 401 | The token is malformed, unknown, or revoked. |
+| `insufficient_scope` | 403 | The credential cannot perform this operation. |
+| `rate_limited` | 429 | Slow down. `Retry-After` SHOULD be set. |
+| `quota_exhausted` | 429 | A budget is spent; retrying now will not help. |
+
+### 3.3 Execution
+
+| Code | Where | Meaning |
+|---|---|---|
+| `harness_error` | failed response | The harness ran and could not complete the work. |
+| `harness_unavailable` | 503 | No capacity to run this harness right now. |
+| `provider_error` | failed response | The upstream model provider refused or failed. |
+| `timeout` | failed response | The task exceeded its wall-clock budget. |
+| `cancelled` | cancelled response | The client cancelled it. |
+| `preview_unavailable` | 501 | This server does not render previews. |
+| `preview_failed` | 502 | Conversion of this file failed. |
+
+## 4. Retrying
+
+| Situation | Retry? |
+|---|---|
+| `server_error` (500, 502, 503, 504) | Yes, with exponential backoff and jitter |
+| `rate_limited` | Yes, after `Retry-After` |
+| `quota_exhausted` | No — nothing will change until the quota does |
+| `session_busy` | Yes, once the in-flight task is terminal |
+| Any `invalid_request_error` | No — fix the request |
+| `authentication_error` | No — fix the credential |
+| A task that reached `failed` | Only with the client's own judgment; it consumed real resources |
+
+**Retries of `POST /v1/responses` MUST carry an `Idempotency-Key`.** Without one, a retry after a
+timeout runs the task a second time — and the first may still be running, editing the same files.
+This is the single most damaging mistake a UHP client can make; see [Tasks §6](tasks.md).
+
+## 5. Timeouts
+
+A client SHOULD set generous timeouts. Agent tasks routinely run for minutes; a 30-second HTTP
+timeout will cancel healthy work.
+
+- Streaming: no total timeout. Use an inactivity timeout instead — a server SHOULD emit a comment
+ line (`: keep-alive`) at least every 30 seconds so the client can distinguish a working agent from
+ a dead connection.
+- Non-streaming: at least the task's `timeout_seconds`, plus margin.
+- A client that gives up MUST NOT assume the task stopped. It has not. Cancel it explicitly.
diff --git a/protocol/versions/2026-10-19/files.md b/protocol/versions/2026-10-19/files.md
new file mode 100644
index 00000000..5b905be9
--- /dev/null
+++ b/protocol/versions/2026-10-19/files.md
@@ -0,0 +1,137 @@
+# Files
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+An agent that can only return text is a chatbot. A harness edits files, writes reports, produces
+diagrams. This chapter defines getting files in and artifacts out.
+
+Conformance class **Extended**.
+
+## 1. Sending files in
+
+### 1.1 Inline
+
+For small files, inline the bytes as a data URL:
+
+```json
+{
+ "input": [
+ { "role": "user", "content": [
+ { "type": "input_text", "text": "Summarise this." },
+ { "type": "input_file", "filename": "q3.pdf",
+ "file_data": "data:application/pdf;base64,JVBERi0xLjQK…" }
+ ]}
+ ]
+}
+```
+
+### 1.2 By upload
+
+For anything larger, upload once and reference by id:
+
+```http
+POST /v1/files
+Content-Type: multipart/form-data
+```
+
+```json
+{ "id": "file_abc123", "object": "file", "filename": "q3.pdf", "bytes": 184320, "created_at": 1786400000 }
+```
+
+```json
+{ "type": "input_file", "file_id": "file_abc123" }
+```
+
+A server MUST accept both forms. Inline avoids a round trip for a 4 KB file; upload avoids
+base64-inflating a 40 MB one through every retry. A server MUST document its size limit and MUST
+reject an oversized upload with `413` and `code: "file_too_large"` rather than truncating — a
+silently truncated input produces a confident, wrong answer.
+
+## 2. Getting artifacts out
+
+Files an agent produces become artifacts of the session's container. They are reported in two
+places.
+
+### 2.1 On the response
+
+Artifacts appear as annotations on the assistant message:
+
+```json
+{
+ "type": "message",
+ "content": [
+ { "type": "output_text", "text": "I've written the report.",
+ "annotations": [
+ { "type": "container_file_citation",
+ "container_id": "cntr_…",
+ "file_id": "file_…",
+ "filename": "report.md",
+ "download_url": "https://server/v1/containers/cntr_…/files/file_…/content",
+ "start_index": 0, "end_index": 24 }
+ ]
+ }
+ ]
+}
+```
+
+A client that renders only text still shows a correct answer; a client that reads annotations can
+offer the file. That is the intended layering — artifacts are additive to the message, never a
+replacement for it.
+
+### 2.2 By listing the session
+
+```http
+GET /v1/sessions/{session_id}/files
+```
+
+```json
+{ "files": [ { "id": "file_…", "container_id": "cntr_…", "filename": "report.md",
+ "bytes": 2048, "created_at": 1786400240 } ] }
+```
+
+A server MUST list every artifact of the session, including files from earlier tasks. Restricting the
+list to the most recent task would make a multi-step session's earlier outputs unreachable.
+
+## 3. Downloading
+
+```http
+GET /v1/containers/{container_id}/files/{file_id}/content
+```
+
+Returns the raw bytes with the file's own `Content-Type`. A server MUST NOT wrap the bytes in JSON.
+
+A server SHOULD send `Content-Disposition` with the original filename, and MUST set
+`X-Content-Type-Options: nosniff`. Artifacts are attacker-influenced content — an agent can be
+persuaded to write a file — so serving them without those headers turns an artifact into stored
+XSS against the client's own origin.
+
+### 3.1 Preview rendering
+
+A server MAY offer a rendered preview of a document format:
+
+```http
+GET /v1/containers/{container_id}/files/{file_id}/pdf
+```
+
+If a server does not implement conversion it MUST return `501` with
+`code: "preview_unavailable"`, not a broken or empty PDF. If conversion fails it MUST return `502`
+with `code: "preview_failed"`. A client can then tell "this server never previews" from "this file
+would not convert", and only the second is worth retrying.
+
+## 4. Bulk download
+
+```http
+GET /v1/sessions/{session_id}/files/archive
+```
+
+Returns every artifact of the session as a single archive. A server SHOULD implement this: a session
+that produced forty files should not require forty requests.
+
+## 5. Retention and scope
+
+- Artifacts live with their session. Deleting a session MUST make its artifacts unreachable.
+- A server MUST scope file access to the owning principal. A `file_id` from another principal MUST
+ return `404`, never the bytes.
+- A server MUST NOT let a `container_id` / `file_id` pair traverse outside its container. Path
+ traversal through artifact ids is the most likely serious vulnerability in a UHP implementation,
+ and the conformance suite probes for it.
diff --git a/protocol/versions/2026-10-19/harnesses.md b/protocol/versions/2026-10-19/harnesses.md
new file mode 100644
index 00000000..99028e3d
--- /dev/null
+++ b/protocol/versions/2026-10-19/harnesses.md
@@ -0,0 +1,314 @@
+# Harnesses
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+Before a client can send work it needs to know what can run it, and with which models. This chapter
+defines discovery, the harness object, and — at conformance class **Full** — how harnesses are
+created and changed.
+
+## 1. Discovering harnesses
+
+```http
+GET /v1/harnesses
+```
+
+```json
+{
+ "harnesses": [
+ {
+ "id": "chrn_08dae611630d467ab3e67ed792570ae5",
+ "object": "harness",
+ "name": "Research agent",
+ "base": "claude-code",
+ "baseLabel": "Claude Code",
+ "defaultModel": "claude-sonnet-4.6",
+ "systemPrompt": "",
+ "mcpServers": [],
+ "skills": [],
+ "plugins": [],
+ "disabledTools": [],
+ "maxStep": null,
+ "timeoutSeconds": null,
+ "createdAt": 1786403298205
+ }
+ ]
+}
+```
+
+A server MUST return only harnesses within the caller's scope. The list MAY be empty — a server with
+no configured harnesses is valid, and a client MUST handle that rather than assuming index `0`
+exists.
+
+```http
+GET /v1/harnesses/{harness_id}
+```
+
+Returns one harness object, or `404` with `code: "harness_not_found"`.
+
+## 2. The harness object
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `id` | string | yes | `chrn_`-prefixed |
+| `object` | string | yes | Always `harness` |
+| `name` | string | yes | Human-readable label; not an identifier |
+| `base` | string | yes | Which harness runtime: `codex`, `claude-code`, `hermes`, … |
+| `baseLabel` | string | no | Display name for `base` |
+| `defaultModel` | string | no | Model used when a task omits `model` |
+| `systemPrompt` | string | no | Additional standing instructions |
+| `mcpServers` | array | no | MCP servers attached to this harness |
+| `skills` | array | no | Skills available to this harness |
+| `plugins` | array | no | Installed plugins, each a package of tools and skills; see [Plugins](plugins.md) |
+| `environment` | string | no | The environment this harness's tasks read, mounted read-only; requires the `environments` capability. See [Environments](environments.md) |
+| `disabledTools` | string[] | no | Tools withheld from the agent |
+| `maxStep` | integer \| null | no | Default step budget |
+| `timeoutSeconds` | integer \| null | no | Default wall-clock budget |
+| `createdAt` | integer | yes | Unix milliseconds |
+
+The memories a harness's agent reaches are not a field of this object. The agent is a member and
+is granted on the memory, like a person; `/v1/harnesses/{id}/memories` reads what it was granted
+and keeps two settings ([Memories §9](memories.md#9-an-agent-and-its-memories)).
+
+`base` values are not enumerated by this specification. A server MAY support bases this document has
+never heard of, and a client MUST treat `base` as an opaque string — anything else means the
+protocol has to be revised every time a harness is released, which is exactly the coupling UHP
+exists to remove.
+
+## 3. Models
+
+```http
+GET /v1/models
+```
+
+```json
+{
+ "backends": {
+ "claude": {
+ "default": "claude-sonnet-4.6",
+ "models": [
+ { "id": "claude-sonnet-4.6", "label": "claude-sonnet-4.6", "backend": "claude",
+ "available": true, "default": true }
+ ]
+ }
+ }
+}
+```
+
+```http
+GET /v1/harnesses/{harness_id}/models
+```
+
+```json
+{
+ "harness_id": "chrn_…",
+ "backend": "claude",
+ "default": "claude-sonnet-4.6",
+ "fallback": "claude-sonnet-4.6",
+ "models": [ { "id": "claude-opus-5", "available": true, "default": false } ]
+}
+```
+
+### 3.1 `available` is a promise
+
+`available: true` means the server can serve that model for that harness **right now** — a
+credential exists and the provider can reach it. `available: false` means a request for it will not
+run as asked.
+
+A server MUST compute `available`, not assert it. Listing a model as available and then failing the
+task is the worst outcome for a client: it presents a choice to a user, the user picks it, and the
+work fails after they have committed to it.
+
+A client SHOULD present unavailable models as disabled rather than hiding them, so a user can see
+that a model exists and is not configured, rather than wondering why it is missing.
+
+## 4. Tools and skills
+
+A configured harness carries three things that decide what its agent can do. All three are part of
+the harness object and are set the same way it is.
+
+### 4.1 MCP servers
+
+```json
+{ "mcpServers": [
+ { "name": "vault", "url": "https://mcp.example.com/mcp", "transport": "http", "enabled": true }
+] }
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | Identifies the server to the agent; sanitised to a CLI-safe identifier |
+| `url` | yes | Endpoint |
+| `transport` | no | `http` (Streamable HTTP, default) or `sse` |
+| `enabled` | no | Absent or `true` means enabled |
+| `headers` | no | Extra request headers |
+| `auth` | no | Bearer token, or a server-side reference the server resolves |
+
+This list carries remote servers only, exactly as it did in the previous version. An MCP server that
+runs as a process (`stdio`) is declared inside a plugin, which is what gives it a root to run from
+and a directory to keep state in ([Plugins §2.2](plugins.md#22-what-the-server-derives)).
+
+A server MUST connect only the **enabled** entries for a turn. A disabled entry MUST NOT be
+contacted at all — not connected and then hidden, which would still leak the turn's existence to
+whoever operates that endpoint.
+
+An MCP server that cannot be reached MUST NOT fail the task. The turn MUST proceed without those
+tools, because a third-party endpoint being down is not a reason to lose the user's work. A server
+SHOULD make the degradation visible in the run rather than silent.
+
+> A server MUST NOT advertise MCP support it cannot deliver. If the harness runtime behind it cannot
+> speak the configured transport, that is a broken installation, and reporting it only in a log file
+> inside the workspace is indistinguishable — to the user — from the model refusing to use the tool.
+
+### 4.2 Skills
+
+A skill is a **folder**, not a file:
+
+```json
+{ "skills": [
+ { "name": "vault-manual", "enabled": true, "files": [
+ { "path": "SKILL.md", "content": "---\nname: vault-manual\n---\n…" },
+ { "path": "references/codes.md", "content": "…" },
+ { "path": "scripts/helper.sh", "content": "#!/bin/sh\n…" },
+ { "path": "assets/logo.png", "content_b64": "iVBORw0KGgo…" }
+ ]}
+] }
+```
+
+- `files[].path` is relative to the skill's own folder and MUST support nested directories. A server
+ MUST reject a path that escapes the folder.
+- Text is carried in `content`; binary in `content_b64`. A server MUST preserve both byte-for-byte.
+- A bundle MUST contain a `SKILL.md`; a server MUST reject one that does not, at configuration time
+ rather than at run time.
+- A server MUST materialise the **whole folder** where the agent can read it. Materialising only
+ `SKILL.md` breaks every skill that carries references, scripts or data — which is most non-trivial
+ skills.
+- `enabled: false` suppresses a skill, including one inherited from the base.
+
+A server MAY store large bundles out of line, and MUST return the complete file list from:
+
+```http
+GET /v1/harnesses/{harness_id}/skills/{skill_id}/files
+```
+
+Round-tripping a harness through `GET` and `PUT` MUST NOT lose skill contents. This is the failure
+worth designing against: an unrelated edit — renaming the harness — silently emptying a skill folder
+that the user cannot tell is gone until an agent behaves oddly weeks later.
+
+### 4.3 Disabled tools
+
+```json
+{ "disabledTools": ["WebSearch"] }
+```
+
+Names come from the harness base's own tool catalogue. Enforcement differs by runtime and a server
+MUST NOT overstate it:
+
+- Where the runtime supports per-tool restriction, the server MUST enforce it as a hard block.
+- Where it does not, the server MUST still convey the restriction to the agent — as a standing
+ instruction — and MUST NOT silently drop it. Dropping it is the worst outcome: the operator
+ believes a tool is off, and it is not.
+
+A client that requires a guaranteed block SHOULD confirm the harness base supports one rather than
+assuming `disabledTools` is always hard.
+
+### 4.4 Plugins
+
+```json
+{ "plugins": [ { "name": "contract-review", "enabled": true, "blob": "plg_…" } ] }
+```
+
+A plugin is an [Agent Plugins](https://agent-plugins.org/specification) package: `plugin.json`,
+`mcp.json` and `skills/`, carried as one folder and installed whole. Its servers and skills join the
+harness's own for every turn; the harness's own `mcpServers` and `skills` report only what was
+written to them and never absorb a plugin's. The object, the composition rule, the export of a
+harness as a package, and what a hosted server owes a running plugin are in the
+[Plugins chapter](plugins.md). The capability is `plugins`; a server without it is conformant at
+every class.
+
+## 5. Managing harnesses
+
+Conformance class **Full** only. A client MUST check the `harness_management` capability first.
+
+### 5.1 Create
+
+```http
+POST /v1/harnesses
+```
+
+```json
+{ "name": "Research agent", "base": "claude-code", "default_model": "claude-sonnet-4.6" }
+```
+
+Returns the created harness object. `base` is REQUIRED and MUST be one the server supports;
+otherwise `422` with `code: "unsupported_base"`.
+
+A server MUST refuse, rather than store as nothing, what it cannot keep:
+
+- a field the harness object does not have: `422`, naming the field and, when one is close, the
+ field it was probably meant to be;
+- a `default_model` its base does not run: `422` with `code: "model_not_available"`.
+
+What the harness object comes back with and cannot be written (`id`, `object`, `createdAt` and the
+server's own read-only fields) MUST be accepted and ignored, so that a harness read and sent back
+saves. Both refusals hold for an update as well.
+
+### 5.2 Update
+
+```http
+PUT /v1/harnesses/{harness_id}
+```
+
+Replaces the mutable configuration. A server MUST NOT change `id`, `base`, or `createdAt`. Changing
+the base of an existing harness would silently change the behaviour of every session already
+attached to it; a client that wants a different base MUST create a different harness.
+
+### 5.3 Delete
+
+```http
+DELETE /v1/harnesses/{harness_id}
+```
+
+Deleting a harness retires it. What happens to the sessions and responses that used it is the
+server's to choose, between two rules, and the server MUST say which one it follows:
+
+**Sessions are kept (the default).** A server that reports the `harness_retirement` capability
+`false` MUST NOT delete the sessions or responses that used the harness. They stay readable and
+deletable on their own. History that disappears when configuration changes cannot be audited, so
+this is what a client may assume of a server that says nothing.
+
+**Sessions are retired with the harness, under a restore window.** A server that reports
+`harness_retirement` `true` MAY remove the harness's sessions and responses with it, and only under
+these rules:
+
+- **The window is stated when the harness is retired.** The delete response MUST carry
+ `sessions: "retired"` and `restorableUntil`, the time (Unix seconds) until which a restore is
+ possible. A server's own interface MUST tell the person the length of the window before they
+ confirm, and a client that retires a harness for a person MUST pass `restorableUntil` on to them.
+- **Within the window, a restore brings both back.** Restoring the harness (however the server
+ offers it) MUST bring back its sessions and responses with it, as they were. A server MAY
+ withhold them from lists and reads until then; a read of one MAY answer `404`.
+- **After the window, removal is permanent.** The server MAY then remove the harness, its sessions
+ and its responses for good. It MUST NOT remove them earlier, with one exception: a person's own
+ request to erase their data MAY remove the retired sessions that are theirs before the window
+ ends.
+- **Never mid-turn.** A harness with a task in progress is not retired while it runs. The server
+ either cancels the task first, as `POST /v1/sessions/{session_id}/cancel` would, and then retires
+ the harness, or refuses the delete with `409` and `code: "harness_busy"`, saying why.
+
+A server MUST NOT remove a harness's sessions or responses when the harness is retired without a
+window it stated. A server that keeps them MAY say so with `sessions: "kept"` in the delete
+response; an absent `sessions` means kept.
+
+## 6. Choosing a harness
+
+Non-normative, but the question every client faces:
+
+| If the task is… | Consider |
+|---|---|
+| Code editing in a repository | A coding-specialised base (`codex`, `claude-code`) |
+| Long-horizon multi-tool work | A base with an explicit step budget and strong tool use |
+| Cheap, high-volume classification | The smallest model on any base |
+
+The point of UHP is that this choice stays reversible. A product that speaks UHP can change base or
+model with a configuration edit, and can A/B two harnesses against the same input without a second
+integration.
diff --git a/protocol/versions/2026-10-19/index.md b/protocol/versions/2026-10-19/index.md
new file mode 100644
index 00000000..ec24f674
--- /dev/null
+++ b/protocol/versions/2026-10-19/index.md
@@ -0,0 +1,147 @@
+# Unified Harness Protocol — specification `2026-10-19`
+
+An open standard for running complete agent harnesses as shared infrastructure.
+
+This is the normative specification. For an introduction to what UHP is and why it exists, start at
+the [protocol README](../../README.md).
+
+## Chapters
+
+| # | Chapter | Defines |
+|---|---|---|
+| 1 | [Architecture](architecture.md) | Roles, conformance classes, object model, transport, authentication, design principles |
+| 2 | [Lifecycle](lifecycle.md) | Version negotiation, capability discovery, task and session states, concurrency |
+| 3 | [Harnesses](harnesses.md) | Discovering, selecting, configuring and managing harnesses; models and availability |
+| 4 | [Plugins](plugins.md) | Packages of tools and skills, in the Agent Plugins format, installed into a harness; composition; export |
+| 5 | [Environments](environments.md) | A project's files and installed dependencies, built once, read-only in every session that names it; builds, versions, attachment |
+| 6 | [Memories](memories.md) | Memory that outlasts a session: a tree of memories with access granted per node, records, recall, providers, and when a harness reaches them |
+| 7 | [Tasks](tasks.md) | Running work, the response object, model substitution, idempotency |
+| 8 | [Streaming](streaming.md) | The event vocabulary, ordering guarantees, reconnection |
+| 9 | [Sessions](sessions.md) | Continuing, inspecting, cancelling, sharing, deleting |
+| 10 | [Files](files.md) | File input, artifacts, download, retention and scope |
+| 11 | [Errors](errors.md) | The error envelope, codes, retry rules, timeouts |
+| 12 | [Security](security.md) | Credentials, object scope, artifacts, injection, exhaustion, plugins, environments, memories, error hygiene |
+| 13 | [Schema](schema.md) | Machine-readable definitions and how to generate from them |
+
+## Endpoint summary
+
+| Method | Path | Class | Chapter |
+|---|---|---|---|
+| `GET` | `/v1/uhp` | Core | [Lifecycle](lifecycle.md) |
+| `GET` | `/v1/harnesses` | Core | [Harnesses](harnesses.md) |
+| `GET` | `/v1/harnesses/{id}` | Core | [Harnesses](harnesses.md) |
+| `GET` | `/v1/models` | Core | [Harnesses](harnesses.md) |
+| `GET` | `/v1/harnesses/{id}/models` | Core | [Harnesses](harnesses.md) |
+| `POST` | `/v1/responses` | Core | [Tasks](tasks.md) |
+| `GET` | `/v1/responses/{id}` | Core | [Tasks](tasks.md) |
+| `GET` | `/v1/responses/{id}/input_items` | Core | [Tasks](tasks.md) |
+| `POST` | `/v1/responses/{id}/cancel` | Core | [Sessions](sessions.md) |
+| `DELETE` | `/v1/responses/{id}` | Core | [Tasks](tasks.md) |
+| `POST` | `/v1/sessions/{id}/cancel` | Core | [Sessions](sessions.md) |
+| `GET` | `/v1/sessions` | Extended | [Sessions](sessions.md) |
+| `GET` | `/v1/sessions/{id}` | Extended | [Sessions](sessions.md) |
+| `GET` | `/v1/sessions/{id}/turns` | Extended | [Sessions](sessions.md) |
+| `POST` | `/v1/files` | Extended | [Files](files.md) |
+| `GET` | `/v1/sessions/{id}/files` | Extended | [Files](files.md) |
+| `GET` | `/v1/sessions/{id}/files/archive` | Extended | [Files](files.md) |
+| `GET` | `/v1/containers/{cid}/files/{fid}/content` | Extended | [Files](files.md) |
+| `GET` | `/v1/containers/{cid}/files/{fid}/pdf` | Extended | [Files](files.md) |
+| `POST` | `/v1/harnesses` | Full | [Harnesses](harnesses.md) |
+| `PUT` | `/v1/harnesses/{id}` | Full | [Harnesses](harnesses.md) |
+| `DELETE` | `/v1/harnesses/{id}` | Full | [Harnesses](harnesses.md) |
+| `GET` | `/v1/harnesses/{id}/skills/{name}/files` | Full | [Harnesses](harnesses.md) |
+| `GET` | `/v1/harnesses/{id}/plugins/{name}/files` | Full, `plugins` | [Plugins](plugins.md) |
+| `GET` | `/v1/harnesses/{id}/plugin` | Full, `plugins` | [Plugins](plugins.md) |
+| `POST` | `/v1/sessions/{id}/share` | Full | [Sessions](sessions.md) |
+| `GET` | `/v1/sessions/{id}/share` | Full | [Sessions](sessions.md) |
+| `DELETE` | `/v1/sessions/{id}` | Full | [Sessions](sessions.md) |
+| `DELETE` | `/v1/traces/{id}` | Full | [Sessions](sessions.md) (older path, same operation) |
+| `GET` | `/v1/environments` | Full, capability `environments` | [Environments](environments.md) |
+| `POST` | `/v1/environments` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` `PUT` `DELETE` | `/v1/environments/{id}` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` | `/v1/environments/{id}/files` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` `PUT` `DELETE` | `/v1/environments/{id}/files/{path}` | Full, capability `environments` | [Environments](environments.md) |
+| `POST` | `/v1/environments/{id}/directories` | Full, capability `environments` | [Environments](environments.md) |
+| `POST` | `/v1/environments/{id}/import` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` | `/v1/environments/runtimes` | Full, capability `environments` | [Environments](environments.md) |
+| `POST` | `/v1/environments/{id}/build` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` | `/v1/environments/{id}/builds/{version}` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` | `/v1/environments/{id}/versions` | Full, capability `environments` | [Environments](environments.md) |
+| `POST` | `/v1/environments/{id}/versions/{version}/activate` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` | `/v1/environments/{id}/harnesses` | Full, capability `environments` | [Environments](environments.md) |
+| `GET` `POST` | `/v1/memories` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `PUT` `DELETE` | `/v1/memories/{id}` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `POST` | `/v1/memories/{id}/grants` | Full, capability `memories` | [Memories](memories.md) |
+| `DELETE` | `/v1/memories/{id}/grants/{grant_id}` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/observe` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/jobs/{job}` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `POST` | `/v1/memories/{id}/records` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `PATCH` `DELETE` | `/v1/memories/{id}/records/{rid}` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/records/{rid}/history` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/records/{rid}/content/{index}` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/records/{rid}/operations/{name}` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/recall` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/graph` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/erase` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/queries` | Full, capability `memories` | [Memories](memories.md) |
+| `PUT` `POST` | `/v1/memories/{id}/queries/{name}` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/query` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `POST` | `/v1/memories/{id}/snapshots` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `POST` | `/v1/memories/{id}/consolidations` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/consolidations/{run}` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/{id}/consolidations/{run}/changes` | Full, capability `memories` | [Memories](memories.md) |
+| `POST` | `/v1/memories/{id}/consolidations/{run}/revert` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/providers` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` | `/v1/memories/types` | Full, capability `memories` | [Memories](memories.md) |
+| `GET` `PUT` | `/v1/harnesses/{id}/memories` | Full, capability `memories` | [Memories](memories.md) |
+
+The `plugins` column entries are served only by a server whose discovery document reports the
+`plugins` capability; the capability is optional at every class.
+
+The `memories` entries are served only by a server that reports the `memories` capability, which is
+optional at every class as well; within it, named and free queries, types, the media a record may carry, snapshots,
+consolidation runs and erase are declared per provider ([Memories §10.2](memories.md#102-the-capability-document)).
+
+## What changed in this version
+
+Against `2026-10-04`, one rule changes and the rest is additive.
+
+- **Retiring a harness may retire its sessions with it, under a stated restore window**
+ ([Harnesses §5.3](harnesses.md#53-delete)). A server that reports the new `harness_retirement`
+ capability may remove a harness's sessions and responses with it once a restore window it stated
+ when the harness was retired has passed; within the window a restore brings them back. It never
+ retires a harness mid-task (`harness_busy`), and only a person's own erasure request removes
+ their sessions sooner. A server
+ that reports it `false`, or says nothing, keeps them, as every earlier version required. The
+ delete response gains `sessions` and `restorableUntil`. This is the one change that is not
+ additive: a client that relies on a retired harness's sessions staying readable checks the
+ capability.
+- **Harness writes refuse what they cannot store** ([Harnesses §5.1](harnesses.md#51-create)): a field
+ the harness does not have, and a `default_model` its base does not run, are `422`. Both maintained
+ servers have done this since 2026-10-10, inside `2026-10-04`; this version states it.
+
+The [changelog](../../CHANGELOG.md) has the details.
+
+## Conformance
+
+A server is conformant at a class when it passes the [conformance suite](../../conformance/) at that
+class. Nothing else is a conformance claim — not a self-assessment, not an implementation of the
+endpoints, not passing "most" tests.
+
+```bash
+pip install -e protocol/conformance
+uhp-conformance --base-url https://your-server --api-key "$KEY" --class extended
+```
+
+The suite is part of this specification. If the suite and this prose disagree, that is a bug in one
+of them and MUST be resolved by changing whichever is wrong — never by leaving them inconsistent.
+
+## Conventions
+
+- MUST / SHOULD / MAY are used as defined in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and
+ [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174).
+- JSON examples are illustrative; the [schema](../../schema/) is authoritative for structure.
+- Field names are `snake_case` on the task surface (inherited from the Responses-compatible shape)
+ and `camelCase` on the harness object. This inconsistency is real, is called out here rather than
+ hidden, and is retained because changing either would break existing clients for cosmetic gain.
+ A future major version SHOULD unify them.
diff --git a/protocol/versions/2026-10-19/lifecycle.md b/protocol/versions/2026-10-19/lifecycle.md
new file mode 100644
index 00000000..207ca31d
--- /dev/null
+++ b/protocol/versions/2026-10-19/lifecycle.md
@@ -0,0 +1,156 @@
+# Lifecycle
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+This chapter defines how a client and server agree on a protocol version, how a client learns what
+a server can do, and the states a task moves through from submission to result.
+
+## 1. Version negotiation
+
+UHP versions are dates: `YYYY-MM-DD`, the day the version was published. Dates sort, do not imply a
+compatibility promise that semantic versioning would imply and not keep, and make the age of an
+implementation obvious. See [VERSIONING.md](../../VERSIONING.md) for the compatibility rules.
+
+A client MAY declare the version it was written against:
+
+```http
+UHP-Version: 2026-10-19
+```
+
+- If the header is absent, the server MUST assume its own default version and MUST state that
+ version in the response header. A client that omits the header is asking for the server's choice,
+ and gets it.
+- If the header names a version the server supports, the server MUST honour it for that request.
+- If the header names a version the server does not support, the server MUST fail the request with
+ `400` and `code: "unsupported_protocol_version"`, and the error `detail` MUST list the versions it
+ does support. It MUST NOT silently serve a different version — a client that asked for a version
+ it can parse should not receive one it cannot.
+
+Every response, including errors, MUST carry the version actually used:
+
+```http
+UHP-Version: 2026-10-19
+```
+
+## 2. Capability discovery
+
+```http
+GET /v1/uhp
+```
+
+Unauthenticated or authenticated — a server MUST serve this endpoint without a bearer token, because
+a client needs to know whether it is talking to a UHP server *before* it can sensibly present
+credentials. The document MUST NOT contain anything principal-specific.
+
+```json
+{
+ "object": "uhp.discovery",
+ "protocol": "uhp",
+ "versions": ["2026-10-19", "2026-10-04", "2026-09-28", "2026-09-12", "2026-08-11"],
+ "default_version": "2026-10-19",
+ "conformance_class": "full",
+ "capabilities": {
+ "streaming": true,
+ "sessions": true,
+ "cancellation": true,
+ "files_input": true,
+ "files_output": true,
+ "session_listing": true,
+ "harness_management": true,
+ "harness_retirement": false,
+ "session_sharing": true,
+ "idempotency": true,
+ "plugins": true,
+ "environments": true,
+ "memories": true
+ },
+ "plugin_schemas": ["https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"],
+ "implementation": { "name": "HarnessRouter Community Edition", "version": "0.3.0" }
+}
+```
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `object` | string | yes | Always `uhp.discovery` |
+| `protocol` | string | yes | Always `uhp` — lets a client distinguish UHP from a lookalike |
+| `versions` | string[] | yes | Every version this server can serve; MUST be non-empty |
+| `default_version` | string | yes | Used when the client sends no `UHP-Version`; MUST appear in `versions` |
+| `conformance_class` | string | yes | `core`, `extended` or `full` |
+| `capabilities` | object | yes | Named booleans; see below |
+| `plugin_schemas` | string[] | when `plugins` is true | The Agent Plugins manifest schemas the server installs; see [Plugins §7](plugins.md#7-discovery) |
+| `implementation` | object | no | Free-form identification, for debugging and bug reports |
+
+A server MUST report `false` for a capability it does not implement, rather than omitting it, so
+that a client can tell "not supported" from "server is older than this field". A client MUST treat
+an absent capability key as `false`.
+
+`conformance_class` MUST be consistent with `capabilities`: a server claiming `extended` MUST report
+`files_input`, `files_output` and `session_listing` as `true`. The conformance suite checks this,
+because a class claim that contradicts the capability list tells a client two different things.
+
+## 3. Task lifecycle
+
+A task moves through these states. `status` on the response object carries the current one.
+
+```
+ ┌──────────────┐
+ POST /responses │ │
+ ────────────────▶│ in_progress │
+ │ │
+ └──────┬───────┘
+ │
+ ┌──────────────────┼──────────────────┬───────────────────┐
+ ▼ ▼ ▼ ▼
+ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────────┐
+ │completed │ │ failed │ │ incomplete │ │ cancelled │
+ └──────────┘ └──────────┘ └────────────┘ └───────────┘
+```
+
+| Status | Meaning | Terminal |
+|---|---|---|
+| `in_progress` | Accepted and running | no |
+| `completed` | The harness finished the work and produced a result | yes |
+| `failed` | The task could not be completed; `error` explains why | yes |
+| `incomplete` | The harness stopped at a budget — step limit or time limit — with partial output | yes |
+| `cancelled` | The client cancelled it; partial output MAY be present | yes |
+
+Rules:
+
+- A server MUST NOT transition out of a terminal state. Once a client has seen `completed`, later
+ reads of that response MUST return `completed`.
+- `incomplete` MUST be used when a budget stopped the work, and MUST NOT be used for errors. The
+ distinction matters to a client: `incomplete` is usually worth continuing, `failed` usually is not.
+- A `cancelled` task MUST report `cancelled`, not `failed`. A client that asked for a stop did not
+ experience an error.
+- Terminal responses MUST retain whatever output was produced before they became terminal. Discarding
+ partial work because a task later failed destroys the only evidence of what went wrong.
+
+## 4. Session lifecycle
+
+```
+first task ──▶ session created implicitly ──▶ session active ──▶ deleted (client) or expired (server policy)
+ ▲ │
+ └────┘
+ each continued task extends it
+```
+
+- A session is created by the server when the first task of a chain runs. Its id MUST be reported in
+ the response's `metadata.session_id`.
+- A session MUST preserve, across tasks in the chain: conversational context, the working directory
+ and its files, and the configured harness.
+- A session MUST NOT be extended by a task that names a different configured harness. A server MUST
+ fail such a request with `409` and `code: "harness_mismatch"` rather than silently starting a new
+ session — continuing a conversation with a different agent is a different conversation, and doing
+ it quietly loses work the client believed it had.
+- Session expiry is server policy. A server that expires sessions MUST report `404` with
+ `code: "session_expired"` on continuation, distinguishable from `session_not_found`.
+
+## 5. Concurrency
+
+- A server MUST accept concurrent tasks in *different* sessions.
+- A server MUST NOT run two tasks concurrently in the *same* session: a session has one working
+ directory and one conversation, and two agents writing to both is not a defined state. A second
+ task for a busy session MUST fail with `409` and `code: "session_busy"`.
+- A client that receives `session_busy` SHOULD wait for the in-flight task to reach a terminal state
+ and retry. Servers SHOULD include `retry_after_ms` in the error `detail` when they can estimate it,
+ and MUST omit it when they cannot rather than guessing.
diff --git a/protocol/versions/2026-10-19/memories.md b/protocol/versions/2026-10-19/memories.md
new file mode 100644
index 00000000..a20348c8
--- /dev/null
+++ b/protocol/versions/2026-10-19/memories.md
@@ -0,0 +1,993 @@
+# Memories
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+An agent forgets. A session's conversation ends when the session ends ([Sessions](sessions.md)),
+and a harness's instructions are written once by its owner and do not change as the agent works.
+So whatever an agent learns along the way is lost: that a customer prefers email, what the team
+decided last week, which procedure worked last time.
+
+Until this version the protocol had nowhere to keep those things. A product that wanted memory
+attached a memory service to one harness, through that service's own API, with that service's own
+idea of whose memory it was, and with no way to say who may read what.
+
+A **memory** is where they are kept. It is a named container of **records**: a fact, a note, a
+procedure, a person or a company the others are about. Records point at one another, and those
+pointers are the only graph there is: what was concluded from what, who a fact is about.
+
+Memories are arranged in a tree, the way folders are, so one memory can hold what a whole company
+knows and another, beneath it, what is known about one customer. Access is granted per memory, and
+a memory's children inherit it.
+
+People and agents stand the same before it. Both are members, both are granted access the same way,
+and neither reaches what it was not granted. During a task an agent searches its memories and adds
+to them with tools. A search covers a memory and everything below it and says where each answer is
+kept, so the agent knows where to look next.
+
+This chapter is the Harness Memories sub-protocol. It is optional: a server advertises it with the
+`memories` capability, and a server that does not implement it is conformant at every class.
+
+## 1. What a memory is
+
+UHP does not define how memory is derived. Extraction, ranking, consolidation and storage belong to
+the system behind the memory, the **provider**: a vendor's memory service, a graph database, a
+folder of files. This chapter defines the three things a harness and a provider must agree on, and
+nothing else:
+
+```
+the provider its own store and intelligence how memory is derived and kept
+UHP Memories this chapter what a memory is, who may reach
+ it, when a harness calls it
+MCP the tools an agent holds how an agent calls it in a turn
+```
+
+- **The object.** A memory is a node in a tree. It holds **records**, which reference one another,
+ and may have child memories.
+- **The access.** A grant gives a principal privileges on a node; the node's descendants inherit it.
+- **The seam.** A harness reaches memory at four moments of a session's life ([§9.1](#91-what-a-session-does)),
+ and only two of them are the agent's choice.
+
+> **Why a tree and not a fixed set of scopes?**
+> Memory products each name their own levels (user, agent, run, app, team, project) and none of the
+> lists agree. A level is a meaning an implementation gives to a place in a tree: the protocol
+> carries the tree and the inheritance, and a server is free to say that one node is an
+> organization and the one under it a customer. A node exists where access differs, and nowhere
+> else: a session's memory needs no node of its own when it is read by exactly the principals that
+> read its parent.
+
+## 2. The memory object
+
+```json
+{
+ "id": "hmem_7c1e4b9a2d3f4e5a8b6c7d8e9f0a1b2c",
+ "object": "memory",
+ "name": "Sales",
+ "description": "What the sales team knows: accounts and pricing decisions.",
+ "parent_id": "hmem_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
+ "ancestors": ["hmem_0a1b2c3d4e5f60718293a4b5c6d7e8f9"],
+ "restricted": false,
+ "provider": "example",
+ "privileges": ["read", "write"],
+ "records": { "count": 412 },
+ "children": { "count": 3 },
+ "createdAt": 1790560000000,
+ "updatedAt": 1790570094000
+}
+```
+
+| Field | Type | Written by | Meaning |
+|---|---|---|---|
+| `id` | string | server | Opaque to a client. A server that mints its own uses the `hmem_` prefix ([Architecture §3](architecture.md#3-object-model)); a server whose memories are a tree it already has keeps that tree's ids |
+| `name` | string | client | Human-readable |
+| `description` | string | client | What this memory holds, in a sentence or two. An agent reads it to decide whether to look inside ([§6.1](#61-search-finds-the-place-then-the-agent-walks)), so it is content, not decoration |
+| `parent_id` | string or null | client | The containing memory; `null` on a root |
+| `ancestors` | array | server | The ids from the root down to the parent, as far up as the caller may see. Placement only: reading a memory never reads an ancestor's records |
+| `restricted` | boolean | client | When `true`, grants on ancestors stop here ([§3.2](#32-the-cutoff)) |
+| `provider` | string | client | Which provider keeps this memory's records ([§10](#10-providers)). Set at creation, inherited from the parent when omitted; a server MAY refuse to change it |
+| `privileges` | array | server | The caller's effective privileges on this node |
+| `records`, `children` | object | server | Counts, for a caller deciding where to look |
+
+| Request | What it does |
+|---|---|
+| `POST /v1/memories` | Create a memory: `name`, `description`, `parent_id`, `restricted`, `provider` |
+| `GET /v1/memories?parent={id}` | The direct children of a memory, paginated. Without `parent`: where the caller enters the tree |
+| `GET /v1/memories?granted=true` | What the caller was given: where it was let in, and where below that it may do something else |
+| `GET /v1/memories/{id}` | One memory |
+| `PUT /v1/memories/{id}` | Rename it, describe it, restrict it, or move it by giving a new `parent_id` |
+| `DELETE /v1/memories/{id}` | Delete the memory, its records and its descendants |
+
+A listing is one level. Without `parent` it answers where the caller enters the tree: every memory
+it holds a privilege on whose parent it cannot see, so a caller granted one branch enters at that
+branch. A client that wants a subtree asks level by level, or passes `ancestor={id}` for every
+descendant it may read. A server MUST NOT return a memory on which the
+caller has no effective privilege, and MUST NOT reveal that one exists.
+
+Where a caller enters and what it was given are two questions. A caller that reads a memory and
+writes one of its children enters at the parent, and the listing does not show the child: it is
+one level. `granted=true` answers the second question in one request: every memory the caller may
+read whose parent it cannot see, and every memory below those on which what it may do differs from
+what it may do on the parent, each with the caller's privileges there, highest in the tree first.
+It is stated in what the caller may do and never in how a server keeps access, so the answer is
+the same whether the caller was let in by a grant of its own, through a group, or by a role. A
+client reads from it where the caller may write without walking the tree, and an agent's tools
+are built from it ([§9](#9-an-agent-and-its-memories)).
+
+## 3. Access
+
+### Who acts on a memory
+
+One vocabulary names everyone who can act on a memory. It is used in two places: a grant names who
+may act, and a record's `written_by` names who did.
+
+| Kind | Who | Holds grants | Writes records |
+|---|---|---|---|
+| `member` | Anyone who acts: a person or an agent | yes | yes |
+| `group` | A set of members the server resolves: a team, a workspace | yes | no, its members do |
+| `provider` | The memory's provider itself: what it derived from an observation, what a consolidation run concluded | no | yes |
+
+**A person and an agent are the same kind.** Both are members, granted the same way, checked the
+same way, and able to belong to the same groups. Which of the two a member is, is a property of
+the member, `type`: `human` or `agent`. It is carried for a reader who wants to know, and no rule
+of this chapter depends on it. A server treats an agent's membership of a group exactly as it treats a person's: whatever puts a
+new person in a group puts a new agent there, and nothing else does.
+
+A kind of a server's own is `x.`-prefixed (`x.team`). A server MUST NOT use another unprefixed
+kind, and refuses a grant that names one.
+
+The two places write the same identity two ways. In a grant, a **principal** is the string
+`<kind>:<id>`. On a record, the writer is `{ "kind": …, "id": …, "type": … }`. They name the same thing:
+`written_by.kind` and `written_by.id`, joined by a colon, are the principal a grant would name.
+The `id` is the server's own and opaque to a client.
+
+A credential is not a kind, and neither is a harness. A request made with an API key acts as the
+member the key belongs to. A harness is a configuration; its agent is a member, and a server says
+which one ([§9](#9-an-agent-and-its-memories)).
+
+### 3.1 Grants and inheritance
+
+A **grant** gives one principal a set of privileges on one memory. A principal's effective
+privileges on a memory are the union of its grants on that memory and on every ancestor. Access is
+additive: there is no deny, and no grant means no access. Whoever creates a memory holds all four
+privileges on it, an implicit grant that flows down like any other.
+
+| Privilege | Permits |
+|---|---|
+| `read` | `recall`, `get`, `list`, `history`, running a named query marked `read` |
+| `write` | `observe`, `remember`, `revise`, `forget`, defining a named query |
+| `create` | Creating a child memory |
+| `delete` | `erase`, deleting the memory, changing its grants |
+
+| Request | What it does |
+|---|---|
+| `GET /v1/memories/{id}/grants` | Who holds what on this memory, and on which node each grant sits |
+| `POST /v1/memories/{id}/grants` | Grant a principal privileges: `{ principal, privileges }`, the principal as `<kind>:<id>` |
+| `DELETE /v1/memories/{id}/grants/{grant_id}` | Revoke one grant |
+
+### 3.2 The cutoff
+
+A memory with `restricted: true` stops inheritance: grants on its ancestors do not reach it or its
+descendants, and its own grants flow down as usual. It is the only override. A server SHOULD create
+a memory that holds one person's private records as restricted.
+
+### 3.3 Enforcement
+
+Access is enforced by the server on every operation and cannot be chosen, widened or bypassed by a
+model. A provider isolates memories either by keeping each in a container of its own or by a
+condition the server adds to every read and write; it declares which ([§10.2](#102-the-capability-document)).
+A filter applied by the agent, or one a query the agent wrote could omit, is not enforcement.
+
+## 4. Records
+
+A record is one thing a memory holds. Its `id` is the provider's and opaque to a client.
+
+```json
+{
+ "id": "hrec_3b9f2a71c4d84e0f9a6b5c4d3e2f1a0b",
+ "object": "memory.record",
+ "memory_id": "hmem_7c1e4b9a2d3f4e5a8b6c7d8e9f0a1b2c",
+ "type": "fact",
+ "title": "Acme renews in March and wants its discount kept",
+ "content": [
+ { "type": "text", "text": "Acme renews in March and wants its discount kept." }
+ ],
+ "attributes": { "account": "acme" },
+ "version": 2,
+ "status": "active",
+ "supersedes": 1,
+ "time": {
+ "valid_from": "2026-09-30T00:00:00Z", "valid_to": null,
+ "written_at": "2026-10-01T17:02:11Z", "invalidated_at": null
+ },
+ "written_by": { "kind": "member", "id": "chrn_41c0", "type": "agent" },
+ "references": [
+ { "rel": "derived_from", "memory_id": "hmem_…", "record_id": "hrec_…" }
+ ],
+ "trust": "untrusted"
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `type` | What kind of record ([§4.1](#41-types)) |
+| `title` | One line that names the record: a document's heading, an entity's name, a fact's statement. Optional, at most 300 characters. A search matches it with the content. A record without one is named by how its content begins |
+| `content` | What the record says: an ordered list of parts, text and files ([§4.3](#43-content)). MAY be empty when the record has a title: a fact is often one sentence |
+| `attributes` | Structured fields. Free-form for core types; the type's schema for extension types ([§8](#8-types)) |
+| `version`, `status`, `supersedes` | A change appends a version and closes the one before it ([§5.3](#53-nothing-is-overwritten)). `version` counts from 1 and `supersedes` is the number of the version this one replaced, null on the first; a record keeps its `id` across versions. `status` is `active`, `superseded` or `forgotten` |
+| `time` | When it was true in the world (`valid_*`) and when the memory held it (`written_at`, `invalidated_at`). A provider without validity leaves `valid_*` null |
+| `written_by` | Who wrote it, `{ kind, id }` in the vocabulary of [§3](#who-acts-on-a-memory), stamped by the server from the authenticated caller; a client cannot supply it. When the provider wrote it, two more fields say why: `on_behalf_of`, the principal whose observation it was derived from, and `consolidation_id`, the run that concluded it ([§9.2](#92-consolidation-runs)) |
+| `references` | Other records this one points at ([§4.2](#42-references)) |
+| `follows` | Present only on a record the server derives from a source it keeps outside the memory: `{ kind, id, name }` of that source. Such a record is not revised or forgotten through the memory ([§5.4](#54-records-that-follow-a-source)) |
+| `trust` | Always `untrusted` on a read: what a memory returns is data, never instructions ([§13](#13-security)) |
+
+### 4.1 Types
+
+The core types every server understands:
+
+| `type` | What it is |
+|---|---|
+| `episode` | Raw experience as it arrived: a turn, a transcript, an action and its result, a document. Append-only |
+| `fact` | One thing worth remembering, as it was said |
+| `note` | A document an agent or a person wrote and maintains |
+| `procedure` | A how-to with the situation it applies to |
+| `link` | A pointer to something kept elsewhere: an address and a description, no content of its own |
+| `entity` | Something records are about: a person, a company, a product, a place. Its `title` is its name; its content is what is known of it |
+
+Any other type is an extension ([§8](#8-types)). A server MUST carry a record of a type it does not
+understand unchanged, and MUST NOT refuse a read because of it.
+
+### 4.2 References
+
+A reference names a record by `memory_id` and `record_id`. The two ends need not be in the same
+memory, or with the same provider.
+
+- A reference is resolved when it is **read**, with the reader's privileges. A reader without `read`
+ on the target memory receives `{ "record_id", "available": false }` and nothing else: not what
+ the reference means, and not the id of the memory it leads into, since naming that memory would
+ say that it exists.
+- A reviser sets the references it can see. One it was shown as unavailable it can neither restate
+ nor remove: a server keeps it as it was through a revision by that caller.
+- Writing a reference does not require `read` on its target. A record promoted from a private
+ memory into a shared one keeps its source, and only those who may read the source can follow it.
+
+**Records and references are the graph.** There is no second structure for entities and
+relationships: a record is a node, and a reference is an edge from the record that holds it to the
+record it names. `rel` says what the edge means. Six names have a defined meaning; any other is
+carried unchanged.
+
+| `rel` | From | To | Meaning |
+|---|---|---|---|
+| `derived_from` | any record | the record it came from | Provenance: this was concluded from that |
+| `part_of` | any record | the record it belongs to | Structure: a section of a document, a turn of a conversation |
+| `about` | any record | an `entity` | This record concerns that entity |
+| `subject` | a `fact` | an `entity` | Who or what the fact says something of |
+| `object` | a `fact` | an `entity` | Who or what it relates the subject to |
+| `contradicts` | a `fact` | a `fact` | The two cannot both be true, and nothing says that one replaced the other ([§4.4](#44-facts-that-change)) |
+
+`contradicts` says the same thing from either end, so a server that keeps it keeps it on both
+records. Neither record is closed by it: a memory that holds a disagreement shows it rather than
+deciding it. Like every reference it runs between records, not versions, and survives a revision of
+either.
+
+A relationship between two entities that has something to say is therefore a **`fact`** with a
+`subject` and an `object`: "Dana is head of procurement at Quillon Freight" is a fact whose subject
+is the entity Dana and whose object is the entity Quillon Freight. Being a record, it has what
+every record has: a writer, a time it was true, a history, a way to be corrected and forgotten, and
+its own `derived_from` to the conversation it came from. A client MAY draw such a fact as one line
+between its two entities, labelled with the fact's text or its `attributes.predicate`. A
+relationship with nothing to say, such as a section belonging to its document, is a bare reference
+and needs no record of its own.
+
+A record names at most one `subject` and at most one `object`. A statement about two subjects is
+two records; a server refuses a record that names a second of either with `memory_invalid`.
+
+A provider keeps the entities and relationships it has and no more
+([§10.2](#102-the-capability-document)). One that keeps none still has a graph: its records and
+the references between them.
+
+### 4.3 Content
+
+A record's `content` is an ordered list of **parts**. Two kinds of part are defined:
+
+```json
+"content": [
+ { "type": "text", "text": "The new logo, final on 1 October." },
+ { "type": "file",
+ "file": { "id": "file_9a2c…", "name": "logo.png",
+ "media_type": "image/png", "bytes": 48213 },
+ "text": "A blue circle with a white letter A.", "text_source": "stated" }
+]
+```
+
+| Part | Carries |
+|---|---|
+| `text` | `text`: words |
+| `file` | `file`: a reference to bytes, with their `media_type`; and optionally `text`, the words that stand for the file |
+
+- **A modality is a media type, not a kind of part.** An image, a recording, a video and a PDF are
+ all `file` parts and differ in `media_type` alone, so a modality this chapter has never heard of
+ needs no change to it. A part of any other kind has an `x.`-prefixed `type`; a server MUST carry
+ it unchanged and MUST NOT refuse a read because of it.
+- **A file may carry the words that stand for it**: a description of an image, a transcript of a
+ recording. That text is what recall by words finds ([§6.2](#62-the-request)) and what a reader
+ that takes only text is given. `text_source` says whether the writer `stated` it or the provider
+ `derived` it.
+- **A record holds a reference to a file, never its bytes.** The bytes are sent first as
+ [Files](files.md) says (`POST /v1/files`), and the part names the file by `id`. The server
+ completes `name`, `media_type` and `bytes` from its own file store; a client's values for them
+ are not read. The bytes of a part are read at their own address, the record's `content/{index}`
+ ([§5](#5-operations)), by whoever may read the record.
+- **A string is shorthand** for one text part on a write. What is read back is always the list,
+ so a client handles one shape.
+- **A part may name who said it**: `role` is `user`, `assistant`, `system` or `tool`, and `name`
+ says who when the role alone does not: two people in one conversation are both `user`. A turn of
+ a conversation is observed ([§5.1](#51-two-ways-to-write)) as it happened, each part under its
+ role, files included, with no shape of its own.
+- **A provider keeps what it says it keeps.** Its capability document lists the media types it
+ keeps in `content.media` ([§10.2](#102-the-capability-document)). A write that carries a file of
+ a media type the provider does not keep is refused with `memory_unsupported`; it is never stored
+ without the file.
+
+### 4.4 Facts that change
+
+What was true changes: a person moves, buys a fourth bike, says the opposite of what they said
+before. A fact's `attributes` may carry these keys, defined here so that every writer and every
+server mean the same thing by them. Any other key is the writer's own.
+
+| Key | Meaning |
+|---|---|
+| `predicate` | What kind of thing the fact says of its subject, as a short phrase: `home_city`, `pets`, `job`. A server MAY compare predicates in a normalized form (case, spacing, a plural), so a writer that reuses the word already held for a subject is understood |
+| `value` | The value, briefly: `Chicago`, `a golden retriever named Max` |
+| `holds` | `one` when the subject has one value of the predicate at a time (a home city, a job); `many` when values add up (pets, trips). Absent, nothing in this section applies |
+| `stated_at` | When the source said it: the time of the turn or the document it came from. It is not `time.valid_from`, which is when it became true |
+| `as_said` | The time as the source put it: "last week" |
+| `precision` | How exact `time.valid_from` is: `instant`, `day`, `week`, `month` or `year` |
+| `standing` | `true` on an instruction or a preference that applies, without being asked for, until it is changed ([§9.1](#91-what-a-session-does)). Any record may carry it |
+
+A fact remembered without `time.valid_from` became true when it was said: a server takes
+`stated_at` for it.
+
+**One value at a time.** A server that declares `holds` ([§10.2](#102-the-capability-document))
+places a fact whose `holds` is `one`, with subject S, predicate P and `valid_from` T, among the
+active facts on S and P whose `holds` is `one`. Each was true from its `valid_from` until its
+`valid_to`, or until now when that is null:
+
+- One that was true **at** T, having become true before it, has ended at T, unless it has the same
+ value and the new fact only says it again. The server writes a new version of it with `valid_to`
+ set to T. That version is the server's own, `written_by` the provider `on_behalf_of` the writer
+ of the new fact; the version before it keeps the world time it had
+ ([§5.3](#53-nothing-is-overwritten)).
+- One that became true **at** T with another value cannot be true with it, and nothing says which
+ replaced which. Both stay, and the server links them with `contradicts`.
+- When one became true **after** T, the new fact is history: it is kept with `valid_to` set to the
+ earliest such `valid_from`.
+
+So a fact that arrives late, about the past, takes its place in the past: it ends what it replaced
+then, and what came after it still comes after it.
+
+The answer to remembering a `one` fact carries `closed`, the ids of the records it ended, and
+`conflicts`, the ids it was linked to with `contradicts`: both lists, empty when nothing happened,
+and neither is stored on the record. A `many` fact ends nothing by being remembered; what stops
+being true (a bike sold) is ended by a `revise` that sets its `valid_to`.
+
+A record's current world time is its head's. Its history shows each version with the world time
+the memory believed when that version was written.
+
+## 5. Operations
+
+| Request | What it does |
+|---|---|
+| `POST /v1/memories/{id}/observe` | **observe**: append episodes; the provider decides what to derive from them |
+| `GET /v1/memories/{id}/jobs/{job}` | What an `observe` that answered `202` has written since |
+| `GET /v1/memories/{id}/prime` | What the memory gives an agent without being asked: its standing records ([§9.1](#91-what-a-session-does)) |
+| `POST /v1/memories/{id}/records` | **remember**: write one record as stated |
+| `POST /v1/memories/{id}/recall` | **recall**: search this memory and what is below it ([§6](#6-recall)) |
+| `POST /v1/memories/{id}/graph` | **graph**: records as nodes and their references as edges, around one record or for the whole memory ([§6.6](#66-the-graph)) |
+| `GET /v1/memories/{id}/records` | List the records, paginated; accepts `type`, `include` and `as_of` |
+| `GET /v1/memories/{id}/records/{rid}` | One record; accepts `as_of` |
+| `GET /v1/memories/{id}/records/{rid}/history` | **history**: every version of a record, oldest first, each with its writer and time |
+| `GET /v1/memories/{id}/records/{rid}/content/{index}` | The bytes of one file part of a record ([§4.3](#43-content)) |
+| `PATCH /v1/memories/{id}/records/{rid}` | **revise**: write a new version; the earlier one is kept |
+| `DELETE /v1/memories/{id}/records/{rid}` | **forget**: close the record and keep its trace |
+| `POST /v1/memories/{id}/erase` | **erase**: remove content for good, and report what could not be reached |
+
+### 5.1 Two ways to write
+
+`observe` and `remember` differ in who decides.
+
+- **`observe`** hands the provider raw episodes and nothing more. Whether a fact is extracted from
+ them, when, and by what, is the provider's business. It is what a server calls after a turn
+ ([§9.1](#91-what-a-session-does)). When the provider derives after it answers, `observe` answers
+ `202` with `job: { id, status }` and no records yet. A provider is not required to keep the
+ episode itself as a record: one that keeps only what it derived says so
+ ([§10.2](#102-the-capability-document)), and a client that needs the raw input later keeps it.
+
+An episode is `{ content, time, attributes }`: its parts as they happened, each under its role and
+name ([§4.3](#43-content)), and `time.valid_from`, when it happened (left out, now). A conversation
+is observed one session to an episode, in the order the sessions happened; a provider MAY keep a
+session as one record and each of its turns as a record `part_of` it. Observing again an episode
+the memory already holds keeps nothing twice and derives nothing again, unless what was derived
+from it failed.
+
+```json
+{ "episodes": [ {
+ "content": [
+ { "type": "text", "role": "user", "name": "Caroline", "text": "I adopted a dog last week." },
+ { "type": "text", "role": "user", "name": "Melanie", "text": "What's its name?" }
+ ],
+ "time": { "valid_from": "2023-05-08T13:56:00Z" },
+ "attributes": { "session": "s2" }
+} ] }
+```
+
+A job, read at its own route, says how the derivation went:
+
+```json
+{ "object": "memory.job", "id": "hjob_41c0…", "memory_id": "hmem_7c1e…",
+ "status": "completed", "error": "",
+ "data": [ { "id": "hrec_…", "type": "fact", "title": "Caroline adopted a dog", … } ],
+ "closed": [], "conflicts": [],
+ "usage": { "input_tokens": 6200, "output_tokens": 900 },
+ "created_at": 1790570000, "started_at": 1790570002, "finished_at": 1790570031 }
+```
+
+- `status` is `queued`, `running`, `completed` or `failed`, as a consolidation run's is
+ ([§9.2](#92-consolidation-runs)). A provider that cannot tell queued from running says
+ `pending`.
+- `data` is the records the job wrote; `closed` and `conflicts` are what writing them did
+ ([§4.4](#44-facts-that-change)); `usage` is present when a model did the work.
+- A failed job says why in `error` and leaves the episodes kept. Observing them again starts a new
+ job.
+- **`remember`** writes the record the caller states, as stated. It is what an agent calls when it
+ decides something is worth keeping.
+
+A provider declares when its derivation runs: `write_time`, `background`, `agent`, or `none`
+([§10.2](#102-the-capability-document)).
+
+Every write accepts an `Idempotency-Key` ([Tasks](tasks.md)).
+
+### 5.2 Two ways to remove
+
+- **`forget`** closes a record: `status` becomes `forgotten`, it leaves every read that does not ask
+ for history, and its place in the version chain remains. It needs `write`.
+- **`erase`** removes content so that it cannot be read again, from the record and from what was
+ derived from it. It needs `delete`, is never offered to an agent as a tool, and answers with the
+ ids erased and an `unreachable` list of derived copies the provider could not remove. An empty
+ `unreachable` is a guarantee; a provider that cannot give one says so.
+
+### 5.3 Nothing is overwritten
+
+A change to a record appends a version and closes the previous one. `history` returns the chain,
+each version with its writer and time. `as_of` on `recall`, `get` and `list` reads the memory as it
+stood at that instant.
+
+A **snapshot** is a name for an instant: `POST /v1/memories/{id}/snapshots { name, message }`. It
+copies nothing; reading `as_of` a snapshot's time is the same read.
+
+A provider declares how much of this it keeps, for content and for structure separately:
+`versions` (every version), `snapshots` (only between named points), or `none`.
+
+### 5.4 Records that follow a source
+
+A server may keep something outside the memory and show it in the memory as records: a document
+people write in an editor, shown as one record for each of its sections. Such a record carries
+`follows`, which names where it comes from:
+
+```json
+"follows": { "kind": "document", "id": "doc_41c0…", "name": "Engineering guide" }
+```
+
+It changes when its source changes, by the server's own hand. It is not revised or forgotten
+through the memory, because the next change of its source would undo that. A server refuses
+`revise` and `forget` on it with `memory_unsupported`, in words that say where the source is
+changed, and a client offers neither on a record that carries `follows`. In every other way it is
+a record like any other: it is read, recalled and referenced, and its versions are kept as the
+provider declares.
+
+A file someone kept is not such a record. Its title and the line that says what the file shows are
+its writer's own statement, so it is revised and forgotten like any record ([§7](#7-files)).
+
+## 6. Recall
+
+### 6.1 Search finds the place, then the agent walks
+
+A question is asked of a memory **and of everything below it that the caller may read**. That is
+what a search is for: the caller does not yet know where the answer is kept, so it asks high in the
+tree and learns where to look.
+
+Each result therefore names the memory it is in. That memory is a starting point: the agent goes
+there and reads around what it found, lists it, asks again inside it, or moves to its parent or its
+children. The response also carries where the caller can go from the memory it asked: the `parent`
+and the direct `children`, each with its `name`, `description` and counts, and only those the
+caller may read.
+
+Four rules bound this:
+
+- **Down, never up.** `recall` searches the memory and its descendants. It never searches an
+ ancestor. An agent that wants to look higher asks the parent, by its own next call.
+- **Only what the caller may read.** Each descendant is judged on its own
+ ([§3](#3-access)): a branch behind a cutoff the caller is not let through is not searched, and a
+ memory inside such a branch that the caller does hold a grant on is. The server decides this
+ before the provider is asked; a provider is never asked to search a memory the caller may not
+ read.
+- **`depth` narrows it.** `depth: 0` searches the memory alone, `1` adds its children, and so on.
+ Left out, the whole subtree is searched.
+- **A server MAY cap how many memories one question covers**, and MUST say so in `degraded` when it
+ did (`"subtree:capped_at_200_memories"`). The caller then asks lower in the tree.
+
+Everything else acts on **one** memory: `list`, `get`, `history`, the named and free queries
+([§6.4](#64-named-queries), [§6.5](#65-free-queries)) read the memory named in the path and nothing
+else. Finding is wide; reading is exact.
+
+### 6.2 The request
+
+```json
+{
+ "query": "what did Acme say about renewal?",
+ "text": "renewal",
+ "filters": { "field": "attributes.account", "op": "eq", "value": "acme" },
+ "types": ["fact", "note"],
+ "as_of": null,
+ "include": "active",
+ "depth": null,
+ "limit": 8
+}
+```
+
+| Field | Signal |
+|---|---|
+| `query` | Meaning: similarity to a question in natural language |
+| `text` | Words: full-text match |
+| `filters` | Fields: equality, range and membership over `type`, `attributes.*` and `time.*` |
+
+Any one may be given alone. Given together, the provider fuses them into one ranking.
+
+### 6.3 The response
+
+```json
+{
+ "results": [
+ { "record": { "id": "hrec_…", "type": "fact", "content": [ … ],
+ "trust": "untrusted" },
+ "memory": { "id": "hmem_…", "name": "Acme" },
+ "score": 0.91, "why": ["query", "filters"] }
+ ],
+ "parent": { "id": "hmem_…", "name": "Company", "description": "…",
+ "records": { "count": 97 } },
+ "children": [
+ { "id": "hmem_…", "name": "Acme", "description": "…",
+ "records": { "count": 58 } }
+ ],
+ "degraded": [],
+ "abstain": false
+}
+```
+
+- `memory` names the memory each result is in: the one asked, or one below it. It is where the
+ caller goes next.
+- `why` names the signals that produced each result.
+- A result whose record has a `contradicts` reference brings the record at its other end, when the
+ caller may read it and it is active: after the ranked results, once however many results name
+ it, with `score` null and `why` `["contradicts"]`, and not counted against `limit`. A reader who
+ finds one side of a disagreement is shown the other.
+- `degraded` lists what the request asked for and was not done (`"text:not_supported"`,
+ `"subtree:capped_at_200_memories"`). A server MUST NOT ignore part of a request silently.
+- `parent` is absent on a root, and equally absent when the caller may not read the parent: the two
+ cases look the same.
+- `abstain` is `true` when the provider judges that nothing it returned answers the question. A
+ memory that cannot say "I do not know" will be believed when it should not be.
+
+### 6.4 Named queries
+
+What the three signals cannot express, the owner of a memory defines once, in the provider's own
+language, as a **named query** with typed parameters:
+
+```json
+{
+ "name": "open_deals_for",
+ "description": "Deals not yet closed for one account.",
+ "params": { "type": "object", "required": ["account"],
+ "properties": { "account": { "type": "string" } } },
+ "requires": "read",
+ "language": "cypher",
+ "body": "…"
+}
+```
+
+| Request | What it does |
+|---|---|
+| `GET /v1/memories/{id}/queries` | The named queries of this memory, with their parameters |
+| `PUT /v1/memories/{id}/queries/{name}` | Define or replace one; needs `write` |
+| `POST /v1/memories/{id}/queries/{name}` | Run it with `params`; the answer has the shape of [§6.3](#63-the-response) |
+
+`language` and `body` are opaque to the protocol. A named query is offered to an agent as a tool
+with `params` as its input schema. The server MUST run it within what the caller may read.
+
+### 6.5 Free queries
+
+A provider MAY also let a caller, an agent included, write a query and run it:
+
+```http
+POST /v1/memories/{id}/query
+
+{ "language": "cypher", "statement": "…", "params": { } }
+```
+
+It is optional and provider-dependent: the provider declares `queries.free` with the languages it
+accepts ([§10.2](#102-the-capability-document)), and an agent is offered it as the tool
+`memory_query`, whose description names the language and the memory's schema. The answer has the
+shape of [§6.3](#63-the-response) where the result is records, and the provider's own rows otherwise.
+
+Freedom over the statement is not freedom over the reach. A statement written by a model can leave
+out the condition that confines it, so the confinement cannot be in the statement:
+
+- The provider MUST run a free query within what the caller may read, by a means the statement
+ cannot undo: a container the query cannot leave, or a scope the provider applies outside the
+ statement. A provider that cannot do this MUST NOT declare `queries.free`.
+- A free query reads. A provider that lets one write declares `queries.free.write`, needs `write`
+ from the caller, and stamps `written_by` as on any other write.
+- The server MAY bound a free query's time and result size and reports a bound it applied in
+ `degraded`.
+
+### 6.6 The graph
+
+One read returns records and the references between them as nodes and edges, for a client that
+draws them or an agent that asks what something is connected to.
+
+```json
+{ "around": "hrec_dana…", "hops": 2, "types": ["entity", "fact"], "limit": 200 }
+```
+
+| Field | Meaning |
+|---|---|
+| `around` | A record to start from. Left out, the start is every record of this memory and of what is below it that the caller may read: the scope a search has |
+| `hops` | How many references away to go, in either direction: `0` to `3`, default `1` |
+| `types` | Return only nodes of these types |
+| `limit` | The most nodes to return |
+
+```json
+{
+ "object": "memory.graph",
+ "nodes": [
+ { "record": { "id": "hrec_dana…", "type": "entity", "content": [ … ] },
+ "memory": { "id": "hmem_55d1…", "name": "Acme" } },
+ { "record": { "id": "hrec_job…", "type": "fact", "content": [ … ] },
+ "memory": { "id": "hmem_55d1…", "name": "Acme" } }
+ ],
+ "edges": [
+ { "from": { "memory_id": "hmem_55d1…", "record_id": "hrec_job…" },
+ "to": { "memory_id": "hmem_55d1…", "record_id": "hrec_dana…" },
+ "rel": "subject", "available": true },
+ { "from": { "memory_id": "hmem_55d1…", "record_id": "hrec_job…" },
+ "to": { "record_id": "hrec_77a1…" },
+ "available": false }
+ ],
+ "truncated": false,
+ "degraded": []
+}
+```
+
+- A node is a record as any read returns it, with the memory it is in. An edge is a reference:
+ `from` the record that holds it, `to` the record it names.
+- Records are looked for in this memory and in what is below it that the caller may read, as a
+ search does. An edge may lead into any memory. Its target is a node only when the caller may
+ read it; otherwise the edge is returned with `"available": false`, without its `rel` and without the
+ memory its target is in, and the
+ target is not a node. This is the rule of [§4.2](#42-references), unchanged.
+- `truncated` is `true` when there were more nodes than `limit`. `degraded` says what was cut
+ short, as a search's does.
+- The graph is the same for every provider because it is made of what every provider has. What
+ differs is how much is in it.
+
+## 7. Files
+
+A file enters a memory as a part of a record's content ([§4.3](#43-content)): uploaded as
+[Files](files.md) says, named in the part by its id, and read back at the part's own address. A
+revision whose content names other files is a new version of the record; the earlier version keeps
+naming the files it had, for as long as the provider keeps history and the server keeps the files.
+
+Forgetting a record that holds a file closes it like any other: the file leaves every read that
+does not ask for history, and is still there for one that does. `erase` removes the bytes too, and
+names a copy it could not remove in `unreachable`.
+
+`content.bytes` in the provider's capability document says where the bytes live: `kept` when the
+provider stores them itself, `referenced` when it keeps the reference and the bytes stay with the
+server's file store, living as long as that file does. `content.describes` lists the media types
+the provider writes a part's `text` for when the writer gave none.
+
+## 8. Types
+
+A provider may hold more than the core types: a calendar, a task board, a table, a workflow. Each is
+a **type** the provider registers and describes.
+
+```http
+GET /v1/memories/types
+```
+
+```json
+{ "data": [ {
+ "type": "x.calendar.event",
+ "description": "A meeting or a block of time.",
+ "schema": { "type": "object",
+ "properties": { "starts_at": { "type": "string" },
+ "attendees": { "type": "array" } } },
+ "text": "title, attendees and time as one line, for recall",
+ "operations": [
+ { "name": "reschedule", "description": "Move to a new time.",
+ "input": { "…": "…" }, "requires": "write" },
+ { "name": "free_slots", "description": "Open time around this event.",
+ "input": { "…": "…" }, "requires": "read" }
+ ] } ] }
+```
+
+A record of an extension type is a record: it has an address, sits under its memory's access, is
+versioned, can be referenced, and is found by `recall` through its text projection. The type adds
+its fields and its **operations**:
+
+```http
+POST /v1/memories/{id}/records/{rid}/operations/{name}
+```
+
+Each operation states the privilege it needs and is offered to an agent as a tool. The protocol sets
+no limit on type names (beyond the `x.` prefix for types it does not define), fields or operations.
+A provider that registers none reports `types: false` and answers the listing with the core types.
+
+## 9. An agent and its memories
+
+An agent is a member ([§3](#who-acts-on-a-memory)). It reaches the memories it was granted, and it
+is granted where everyone is: on the memory, with `POST /v1/memories/{id}/grants`. There is no
+second list of what an agent may use, and nothing on a harness widens or narrows what its agent
+was granted.
+
+A harness adds two settings of its own:
+
+| Request | What it does |
+|---|---|
+| `GET /v1/harnesses/{id}/memories` | The agent's principal, the memories it was granted with its privileges on each, and the two settings |
+| `PUT /v1/harnesses/{id}/memories` | Set `default_memory_id` and `observe` |
+
+```json
+{
+ "object": "harness.memories",
+ "principal": "member:chrn_41c0",
+ "default_memory_id": "hmem_7c1e…",
+ "observe": true,
+ "data": [
+ { "id": "hmem_0a1b…", "name": "Support",
+ "privileges": ["read"], "default": false },
+ { "id": "hmem_7c1e…", "name": "Agent notes",
+ "privileges": ["read", "write"], "default": true }
+ ]
+}
+```
+
+- `principal` is who this harness's agent is to the access model. A grant names it; a record the
+ agent writes is stamped with it.
+- `data` is read off the grants, never stored on the harness: every memory the agent holds a grant
+ on, highest in the tree first. It is where the agent starts. From each it reaches everything
+ below, and nothing above that it was not granted. A server that runs the agent and does not
+ keep its memories asks the server that does, as the agent, with `GET /v1/memories?granted=true`
+ ([§2](#2-the-memory-object)). It MUST NOT build an agent's tools from the plain listing, which
+ names only where the agent enters: an agent that reads a memory and writes one below it would
+ be offered nothing to write with.
+- `default_memory_id` is where an unaddressed `remember` goes and where turns are recorded. It MUST
+ be a memory the agent may write; a server refuses one it may not, with `memory_invalid`.
+- `observe`, on by default, records each finished turn in the default memory as an episode.
+- A task MAY name a memory in `metadata.memory` on the request, where `harness_id` and
+ `environment` already travel ([Tasks §1.2](tasks.md#12-selecting-the-harness)): the memory of
+ the person this task is for, say. It is the default for the session that task starts. It grants
+ nothing: a task naming a memory the agent holds nothing on is refused with `memory_not_found`
+ before it starts. A memory is always named by its id. The server does not derive a node from
+ anything else in a request, and creating a person's memory, and letting the agent into it, is
+ the caller's act, done before the task.
+
+### 9.1 What a session does
+
+| Moment | Called by | What happens |
+|---|---|---|
+| **Prime** | server, at session start and after the conversation is compacted | The server reads the standing records of each memory the agent was granted and places them, with each memory's `name`, `description` and children, in the agent's instructions |
+| **Tools** | agent, during a turn | `memory_list`, `memory_recall`, `memory_graph`, `memory_get`, `memory_remember`, `memory_revise`, `memory_forget`, `memory_run_query` for the named queries a memory lists, `memory_operate` for a type's operations, and `memory_query` where a provider offers free queries. Write tools are offered only to an agent that holds `write` somewhere. The memories it was granted are where the agent starts; from each it may walk to the parent and the children a response names, and on from there, as far as its own privileges reach. The server checks every step |
+| **Observe** | server, when a turn ends | The turn (what was asked, what was answered, which tools ran) is sent to the default memory as episodes. No model is involved on the server's side |
+| **Consolidate** | server, on a schedule or when idle | The server asks the provider to do its background work. What that is belongs to the provider |
+
+A memory's standing records are its instructions and preferences: the active records whose
+`attributes.standing` is `true` ([§4.4](#44-facts-that-change)). They are read at their own route,
+so a server that runs the agent and does not keep its memories asks the server that does:
+
+```http
+GET /v1/memories/{id}/prime?budget=4000
+```
+
+```json
+{ "records": [ { "id": "hrec_…", "type": "procedure",
+ "title": "Format every code snippet with syntax highlighting",
+ "attributes": { "standing": true }, … } ],
+ "tokens": 412, "truncated": false }
+```
+
+- The records are newest first, taken in that order until the next would pass `budget` tokens;
+ the first always fits. `tokens` is what the provider counted, an estimate it states and does not
+ have to meet exactly; `truncated` is true when a standing record was left out.
+- It reads the memory alone. `depth` widens it as it widens `recall`
+ ([§6.2](#62-the-request)), and a server priming an agent reads each memory of the agent's
+ granted listing ([§9](#9-an-agent-and-its-memories)) at depth 0, the budget divided between them:
+ a company's root would otherwise put every team's preferences into every turn.
+- It needs `read`, and returns only what the caller may read.
+
+The server records what it placed, per memory, in tokens, with the turn, so the cost is visible
+even where it is not set by the client.
+
+Priming is not repeated every turn. Instructions that change every turn defeat prompt caching, and
+retrieval during a turn is what the tools are for.
+
+A server MUST tell the person who sets a default memory whose provider is outside the server that
+every turn will be sent to it.
+
+### 9.2 Consolidation runs
+
+Background work that rewrites what a memory holds is visible, bounded and reversible, or it is not
+trusted. A provider that consolidates through the protocol exposes each pass as a **run**:
+
+| Request | What it does |
+|---|---|
+| `POST /v1/memories/{id}/consolidations` | Start a run now; a `budget` is optional |
+| `GET /v1/memories/{id}/consolidations` | The runs, newest first |
+| `GET /v1/memories/{id}/consolidations/{run}` | One run |
+| `GET /v1/memories/{id}/consolidations/{run}/changes` | The records the run wrote, superseded or forgot |
+| `POST /v1/memories/{id}/consolidations/{run}/revert` | Undo the run by appending: history keeps both the run and its reversal |
+
+```json
+{
+ "id": "hcon_5d2e…", "object": "memory.consolidation",
+ "memory_id": "hmem_7c1e…",
+ "status": "completed",
+ "trigger": "schedule",
+ "started_at": 1790570000, "finished_at": 1790570094,
+ "read": { "episodes": 240, "through": "2026-10-03T08:00:00Z" },
+ "changes": { "created": 31, "superseded": 6, "forgotten": 2 },
+ "usage": { "input_tokens": 182000, "output_tokens": 9100 },
+ "budget": { "limit": 250000, "unit": "tokens", "exhausted": false },
+ "written_by": { "kind": "provider", "id": "native" },
+ "error": ""
+}
+```
+
+- `status` is `queued`, `running`, `completed`, `stopped` (the budget ran out; what was done stays
+ done and the next run resumes after `read.through`) or `failed`.
+- Every record a run writes carries the run's `written_by` and the run's id beside it
+ (`"consolidation_id": "hcon_5d2e…"`), so a reader can tell what a person or an agent stated from
+ what consolidation concluded, and which run to revert.
+- `revert` appends: each record the run superseded or forgot becomes current again as a new
+ version, and each record it created is forgotten. History keeps both the run and its reversal.
+- A provider declares `consolidate` as `runs` (this section), `trigger` (it can be started and
+ nothing more is reported), or `false`.
+
+## 10. Providers
+
+### 10.1 The contract
+
+A provider implements the operations of [§5](#5-operations) and [§6](#6-recall) for the memories
+bound to it. Everything above the provider, the tree, the grants, the cutoff, references across
+memories, belongs to the server and is the same whichever provider keeps the records.
+
+A server keeps no memory of its own: a deployment has memories once it is connected to a provider,
+with a credential that belongs to whoever connected it and is held as every other credential is
+([Security](security.md)). How a server is connected to a provider is the server's own surface.
+
+How a provider derives memory is not visible here. A provider that runs an agent of its own to
+decide what to keep is a provider like any other and declares `derivation: agent`.
+
+### 10.2 The capability document
+
+```http
+GET /v1/memories/providers
+```
+
+```json
+{ "data": [ {
+ "id": "example",
+ "isolation": "container",
+ "derivation": "background",
+ "observe": { "keeps_episodes": true, "answers": "records" },
+ "recall": { "signals": ["query", "text", "filters"], "abstain": true },
+ "history": { "content": "versions", "structure": "versions" },
+ "revise": "native", "forget": "native",
+ "erase": { "unreachable": "reported" },
+ "prime": true, "consolidate": "runs", "holds": true,
+ "queries": { "named": true,
+ "free": { "languages": ["cypher"], "write": false } },
+ "types": true,
+ "graph": { "entities": "derived" },
+ "content": { "media": ["text/*", "image/*"], "bytes": "referenced",
+ "describes": ["image/*"] }
+} ] }
+```
+
+- **`isolation`** is `container` or `enforced_filter` ([§3.3](#33-enforcement)); **`derivation`** is
+ when the provider turns episodes into records: `write_time`, `background`, `agent`, or `none`.
+- **Emulation is declared.** An operation the provider lacks and the adapter supplies itself is
+ reported as `emulated`, never as `native`.
+- **A gap is declared.** A provider without full-text reports `signals` without `text`, and a
+ request that names it is answered with `degraded`.
+- **`graph.entities`** says where a memory's entities come from: `derived` (the provider finds
+ them in what it is given and relates them itself), `stated` (it keeps the ones a writer states
+ and finds none of its own) or `none` (it keeps no record of that type). The graph read
+ ([§6.6](#66-the-graph)) works on all three.
+- **`prime`** is true when the provider answers the prime read ([§9.1](#91-what-a-session-does));
+ one that does not answers it with an empty list.
+- **`holds`** is true when the provider ends and links facts by `holds`
+ ([§4.4](#44-facts-that-change)). One that does not keeps the attributes as written, answers
+ neither `closed` nor `conflicts`, and leaves `contradicts` to whoever writes it.
+
+### 10.3 What an adapter owes
+
+An adapter maps this chapter onto one provider's own interface. The capability document is where
+the differences are said, and three rules keep it honest:
+
+- A memory is one unit the provider can keep apart from every other. Where the provider has no
+ such unit, the adapter adds the memory's identity to every read and write itself and checks it
+ on every record fetched by id, and declares `enforced_filter`.
+- What the provider cannot do is answered as [§12](#12-errors) says (`memory_unsupported`) or, for
+ part of a request, in `degraded`. It is never approximated in silence.
+- `erase` reports honestly. A provider that still serves a removed record's history, or whose
+ derived copies cannot be reached, is reported in `unreachable` for every id it applies to.
+
+## 11. Discovery
+
+```json
+{ "capabilities": { "memories": true } }
+```
+
+A server that reports `memories: true` implements [§2](#2-the-memory-object) to [§6.3](#63-the-response)
+and [§9](#9-an-agent-and-its-memories). Named and free queries, types, the media a record's content may carry, snapshots, consolidation runs and erase are
+reported per provider ([§10.2](#102-the-capability-document)). A server that does not implement the
+chapter reports `false` or omits it and answers its endpoints with `404`.
+
+## 12. Errors
+
+| Code | Status | When |
+|---|---|---|
+| `memory_not_found` | 404 | No such memory, or one the caller may not see |
+| `memory_forbidden` | 403 | The caller sees the memory and lacks the privilege the operation needs |
+| `memory_record_not_found` | 404 | No such record in this memory, including a record of another memory asked for through this one |
+| `memories_not_attached` | 404 | The agent holds no memory: nothing was granted to it |
+| `memory_invalid` | 422 | A parent that would make a cycle; a default memory the agent may not write; a query whose params do not match |
+| `memory_unsupported` | 422 | An operation the memory's provider does not implement at all (a partial answer is `degraded`, not this) |
+| `memory_busy` | 409 | A move or a delete while a consolidation runs |
+| `memory_unavailable` | 502 or 503 | The provider did not answer, or is not connected |
+
+## 13. Security
+
+- **What a memory returns is untrusted.** A record written in one session is read in another, by
+ another agent, for another person. A server MUST present recalled content to the agent as data,
+ fenced from instructions, and MUST carry `written_by` with it.
+- **The agent chooses its path, never its reach.** An agent may walk up and down the tree from the
+ memories it was granted, and a search covers what is below the memory it asks. What it can
+ reach either way is every memory it holds a privilege on, no more, checked by the server
+ on every call and for every memory a search covers. An agent that should see one branch and
+ nothing above it is granted that branch and nothing above it.
+- **An agent stands where a person stands.** It reaches what it was granted and what the groups it
+ belongs to were granted, and it joins a group by the same rule a person does. A server that puts
+ every new person in a group puts every new agent there too, and should say so where an agent is
+ created: that agent can read what the group was given from its first turn.
+- **Provenance is stamped, not supplied.** `written_by` and `written_at` come from the authenticated
+ caller and the server's clock.
+- **Unknown is indistinguishable from forbidden** on reads of memories and of reference targets.
+- **A provider's credential is the server's**, held as every other credential is
+ ([Security](security.md)); an agent never holds it.
+- **Erase is a person's act.** It is not a tool.
+
+## 14. Conformance
+
+The suite's `memories` checks (ME-01 onward) run against a server that reports the capability and
+has a provider connected, and drive this chapter through the public surface on that provider: the
+tree and its listing, a stated record and its stamped writer, a question asked of a parent finding a record below it and naming where it is, never one above, each signal against the provider's own capability document (a signal the
+provider lacks must be reported in `degraded`, never ignored), revision and history, a record's id
+refused through a memory it is not in, forgetting and erasing, moving and deleting, and two
+entities and the fact between them read back as one graph. The suite runs
+with one credential, so what one principal may not read of another's is not yet checked by it.
+
+An interface that passes says nothing about whether a memory is any good. That is a separate
+measurement, outside this suite: one harness and one model asking the same long-conversation
+questions of each provider through this chapter's operations. A published result of that kind
+SHOULD report the questions a memory ought to decline alongside the ones it ought to answer, and
+what each answer cost.
diff --git a/protocol/versions/2026-10-19/plugins.md b/protocol/versions/2026-10-19/plugins.md
new file mode 100644
index 00000000..a6e6c57c
--- /dev/null
+++ b/protocol/versions/2026-10-19/plugins.md
@@ -0,0 +1,380 @@
+# Plugins
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A harness carries the tools and skills its agent can use ([Harnesses §4](harnesses.md#4-tools-and-skills)).
+Until this version they could only be attached one at a time, to one harness. An operator who wanted
+the same three MCP servers and two skills on a second harness, or in a different product, entered
+them again. A **plugin** is those same components carried as one named, versioned package that
+installs into any harness on any UHP server, and into any other client that reads the same package
+format.
+
+This chapter is the Harness Plugins sub-protocol. It is optional: a server advertises it with the
+`plugins` capability, and a server that does not implement it is conformant at every class.
+
+## 1. What a plugin is
+
+UHP does not define a package format. A UHP plugin **is** an
+[Agent Plugins](https://agent-plugins.org/specification) package, version 1.0.0: a folder with a
+`plugin.json` manifest at its root, MCP servers declared in `mcp.json`, and skills under `skills/`,
+each skill an [Agent Skills](https://agentskills.io/specification) folder with a `SKILL.md`.
+
+Agent Plugins wraps Agent Skills without redefining them: it says where a skill lives inside the
+package and defers the skill's own format to the Agent Skills specification. This chapter does the
+same one layer up. It says how a package travels over UHP, how it is bound to a harness, and what a
+hosted server owes it. Everything about the package's contents defers to Agent Plugins.
+
+```
+Agent Skills SKILL.md and its folder what one skill is
+Agent Plugins plugin.json + mcp.json + skills/ how skills and tools are packaged
+UHP Plugins this chapter how a package is installed into a hosted harness
+```
+
+A plugin carries three things, and the harness object already had a place for two of them:
+
+| Part | Where in the package | What it becomes in the harness |
+|---|---|---|
+| Meta | `plugin.json` | The plugin's identity: `name`, `version`, `author`, `license`, … |
+| Tools | `mcp.json` | MCP servers of the harness ([Harnesses §4.1](harnesses.md#41-mcp-servers)) |
+| Skills | `skills/<name>/SKILL.md` | Skills of the harness ([Harnesses §4.2](harnesses.md#42-skills)) |
+
+> **Why adopt a format rather than define one?**
+> A package format is worth exactly the number of places it installs. Agent Plugins is maintained
+> by a steering committee drawn from the major agent clients, so a plugin written for one of them
+> installs into a UHP harness unchanged, and a plugin exported from a UHP harness ([§5](#5-exporting-a-harness-as-a-plugin))
+> installs into them. A UHP-specific format would need converting at every boundary, and the
+> conversion is where contents get lost.
+
+## 2. The plugin object
+
+```json
+{
+ "name": "contract-review",
+ "enabled": true,
+ "manifest": {
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+ "name": "contract-review",
+ "version": "1.2.0",
+ "description": "Clause extraction and a risk checklist for commercial agreements.",
+ "author": { "name": "Example Legal Tools" },
+ "license": "MIT"
+ },
+ "mcpServers": [
+ { "name": "clauses", "transport": "http", "url": "https://mcp.example.com/clauses", "enabled": true },
+ { "name": "redline", "transport": "stdio", "command": "./bin/redline",
+ "args": ["--data", "${PLUGIN_DATA}"], "enabled": true }
+ ],
+ "skills": [
+ { "name": "risk-checklist", "description": "Turn an agreement into a JSON risk checklist." }
+ ],
+ "skipped": [],
+ "files": [
+ { "path": "plugin.json", "content": "{ … }" },
+ { "path": "mcp.json", "content": "{ … }" },
+ { "path": "skills/risk-checklist/SKILL.md", "content": "---\nname: risk-checklist\n…" },
+ { "path": "skills/risk-checklist/references/clauses.md", "content": "…" },
+ { "path": "bin/redline", "content_b64": "f0VMRgIB…" }
+ ]
+}
+```
+
+| Field | Type | Written by | Meaning |
+|---|---|---|---|
+| `name` | string | either | The manifest's `name`; unique among the harness's plugins |
+| `enabled` | boolean | client | Absent or `true` means installed and active |
+| `files` | array | client | The package, as files relative to the plugin root |
+| `blob` | string | server | Handle for a package the server stores out of line |
+| `manifest` | object | server | `plugin.json`, parsed |
+| `mcpServers` | array | server | The servers `mcp.json` declares, as plugin MCP server objects (`PluginMcpServer`) |
+| `skills` | array | server | The skills found under `skills/`: `name` and `description` each |
+| `skipped` | array | server | Components the server found and could not load, each with the reason |
+
+The server-written fields are derived from the package on every write. A client MAY send them back
+unchanged, which is what a client does when it `PUT`s what it read, and the server MUST recompute
+them rather than store what was sent. A client MUST NOT rely on changing them: editing `mcpServers`
+on a plugin changes nothing, because the package is the source and `mcp.json` is where the servers
+are.
+
+### 2.1 Files
+
+The rules are the ones skills already follow ([Harnesses §4.2](harnesses.md#42-skills)):
+
+- `files[].path` is relative to the plugin root and MUST support nested directories. A server MUST
+ reject a path that escapes the root, or that names anything other than a regular file, with
+ `plugin_invalid`.
+- Text travels in `content`; binary in `content_b64`. A server MUST preserve both byte-for-byte.
+- The package MUST contain `plugin.json` at its root. A server MUST reject one that does not, at
+ configuration time rather than at run time.
+- A server MUST materialise the **whole package** where the agent can read it. A plugin's skills
+ carry references and scripts, and its stdio servers carry the executables they launch.
+- A server MAY store the package out of line and return `blob` in place of `files`. It MUST then
+ return the complete file list from
+ `GET /v1/harnesses/{harness_id}/plugins/{plugin_name}/files` ([§3.1](#31-reading-the-files)).
+- A server SHOULD cap package size, and MUST refuse an oversized one with `file_too_large`
+ (`detail.max_bytes` states the limit) rather than truncating it.
+
+### 2.2 What the server derives
+
+On every write the server reads the package as an Agent Plugins client would, and records what it
+found on the object.
+
+**`manifest`.** The server MUST validate `plugin.json` against the rules of Agent Plugins §5 for the
+version its `$schema` names. A `$schema` the server does not support is refused with
+`unsupported_plugin_schema`; `detail.supported` lists the identifiers it does support. An unknown
+top-level field, or a non-object `extensions`, is not fatal: the field is ignored and recorded in
+`skipped`. Any other violation is fatal, and the write is refused with `plugin_invalid`.
+
+**`mcpServers`.** From `mcp.json`, read as Agent Plugins §7.2 says. Each valid server entry becomes
+one plugin MCP server object, mapped as follows. An invalid entry is recorded in `skipped` and the
+rest still load. If `mcp.json` itself is invalid, or its `$schema` names a different Agent Plugins
+version than `plugin.json`, every server in it is skipped with that reason.
+
+| `mcp.json` `type` | UHP `transport` | Fields carried |
+|---|---|---|
+| `streamable-http` | `http` | `url`, `headers` |
+| `sse` | `sse` | `url`, `headers` |
+| `stdio` | `stdio` | `command`, `args`, `env`, `cwd` |
+
+`${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are reported exactly as written. A server MUST NOT expand them
+in what it returns to a client: the expansion is a filesystem path inside the server's sandbox, which
+is not the client's business and changes from turn to turn. `enabled` on each derived server is
+always `true`; the plugin's own `enabled` is what turns them off, together.
+
+A plugin MCP server object is the harness MCP server object of
+[Harnesses §4.1](harnesses.md#41-mcp-servers) plus the `stdio` transport, with `command`, `args`,
+`env` and `cwd` in place of `url`, `headers` and `auth`. `command` is one executable token, never a
+shell string: a bare name, or a plugin-relative path beginning with `./`.
+
+> **Why is `stdio` declared only inside a plugin?**
+> A process needs somewhere to run from and somewhere to keep state, and a plugin is the object
+> that provides both: `PLUGIN_ROOT` and `PLUGIN_DATA` are defined by the package, not by the
+> harness. A stdio server on the harness's own list would need a second set of rules for a root
+> it does not have, and it could not be exported, because its executable would not travel with
+> it. So the harness's own list stays what it was in the previous version, remote servers only,
+> and a process is two files away: a `plugin.json` and an `mcp.json` make a complete plugin. That
+> keeps every object the previous version defined byte-for-byte unchanged, which is what lets a
+> server serve both versions from one code path ([§4.1](#41-the-direct-fields-are-unchanged)).
+
+**`skills`.** Each immediate child directory of `skills/` that contains a regular file named
+`SKILL.md` is one skill, per Agent Plugins §7.1. A server MUST NOT search deeper. Each skill MUST
+conform to Agent Skills, including the rule that its frontmatter `name` equals its directory name; a
+skill that does not is recorded in `skipped` and the rest still load. The derived entry carries the
+frontmatter `name` and `description`.
+
+**`skipped`.** Each entry is `{ "path": …, "reason": … }`, where `path` locates the component in
+the package (`skills/broken`, `mcp.json#/mcpServers/redline`, `plugin.json#/vendorField`) and
+`reason` is one sentence. A server MUST return `skipped` on every plugin object, empty when nothing
+was skipped, so a client can tell "nothing skipped" from "server does not report skips".
+
+> **Why is a broken component recorded rather than refused?**
+> Two rules meet here. [Harnesses §4.2](harnesses.md#42-skills) refuses a skill without a
+> `SKILL.md` at configuration time, because a bundle that is stored and then silently ignored at
+> run time is the hardest failure a user can be handed. Agent Plugins §11.3 requires the opposite
+> inside a package: a failure isolated to one component MUST NOT stop the rest from loading,
+> because a package is written by someone other than the person installing it, and one stale entry
+> should not take the whole plugin down with it. Both are right about their own case. The
+> reconciliation is the one [Tasks §1.1](tasks.md#11-request-fields) already makes for reserved
+> fields: ignoring is allowed, silent ignoring is not. The package installs, and what did not load
+> is written on the object, where the person configuring the harness can see it. The manifest is
+> the exception. Without a valid manifest there is no plugin to isolate failures within, so a fatal
+> manifest error refuses the write.
+
+## 3. Installing a plugin
+
+Plugins are part of the harness object and are set the way its other configuration is set
+([Harnesses §5](harnesses.md#5-managing-harnesses)): conformance class **Full**, and the `plugins`
+capability MUST be `true`.
+
+```http
+POST /v1/harnesses
+```
+
+```json
+{
+ "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: …\n---\n…" }
+ ] }
+ ]
+}
+```
+
+- `name` on the write is OPTIONAL. If present it MUST equal the manifest's `name`; otherwise the
+ write is refused with `plugin_invalid`. The manifest is the source of the name, so that a plugin
+ renamed on install is still the plugin its author published.
+- Two plugins with the same `name` in one harness MUST be refused with `plugin_conflict`.
+- A refused write MUST leave the harness unchanged. A plugin is installed whole or not at all.
+- `PUT /v1/harnesses/{harness_id}` replaces `plugins` as it replaces every other mutable field.
+ Round-tripping a harness through `GET` and `PUT` MUST NOT lose package contents; a client that
+ sends back `{ "name": "contract-review", "blob": "…" }` keeps the package it read.
+- `enabled: false` keeps the plugin installed and inert. Nothing in it is materialised, and none of
+ its MCP servers is contacted ([Harnesses §4.1](harnesses.md#41-mcp-servers)).
+
+### 3.1 Reading the files
+
+```http
+GET /v1/harnesses/{harness_id}/plugins/{plugin_name}/files
+```
+
+```json
+{ "files": [ { "path": "plugin.json", "content": "…" }, { "path": "bin/redline", "content_b64": "…" } ] }
+```
+
+The complete package, byte-for-byte, whether or not the server stores it out of line. `404` with
+`plugin_not_found` when the harness has no plugin of that name.
+
+## 4. Composition: what the agent gets
+
+A harness's **effective configuration** is what its agent runs with. A server computes it from the
+harness object for every turn:
+
+- the effective MCP servers are the harness's enabled `mcpServers`, plus the `mcpServers` of every
+ enabled plugin;
+- the effective skills are the harness's enabled `skills`, plus the `skills` of every enabled plugin;
+- `disabledTools` applies to all of them alike.
+
+### 4.1 The direct fields are unchanged
+
+`mcpServers` and `skills` on the harness keep exactly the meaning they had in the previous version.
+They report what a client wrote there and nothing else. A plugin's components are reported on the
+plugin and are never copied into the direct fields.
+
+A harness with no plugins is what it was before this version, with `plugins` an empty array. Every
+harness that exists today is a valid harness under this version, and every client written against
+the previous version keeps working, by the client rules in [Versioning](../../VERSIONING.md): it
+ignores `plugins` and sees a harness with fewer tools than the agent actually has, which is already
+what it sees for tools the base provides on its own.
+
+The converse holds too. Nothing this version defines changes the shape of an object the previous
+version defined, so a server that implements plugins serves both versions from one code path: it
+lists both in `versions`, answers a `2026-08-11` request with the same objects, and the `plugins`
+field is simply one more field that version's clients ignore. A server that has not implemented
+plugins keeps serving `2026-08-11`, reports the `plugins` capability `false`, and is conformant
+at every class under this version's suite; the plugin checks skip, and a skip is never a pass.
+
+> **Why not report the effective set in `mcpServers`?**
+> Because of the round trip. A client that reads a harness and `PUT`s it back after an unrelated
+> edit is the case [Harnesses §4.2](harnesses.md#42-skills) is designed around. If `mcpServers`
+> carried plugin-derived servers, that `PUT` would write them into the direct list, and the harness
+> would then carry every plugin server twice: once from the plugin and once as its own. Uninstalling
+> the plugin would leave its servers behind. So the direct fields report what was written to them,
+> and a client that wants the effective set takes the union, which this section makes a one-line
+> computation with no server-specific rules in it.
+
+### 4.2 One namespace, checked at configuration time
+
+Within a harness, MCP server names MUST be unique across the direct list and every enabled plugin,
+and skill names likewise. A write that would create a collision MUST be refused with `409` and
+`plugin_conflict`; `detail.component` is `mcp_server` or `skill`, `detail.name` is the colliding
+name, and `detail.between` names the two owners, each either `harness` or a plugin name.
+
+> **Why refuse rather than prefix?**
+> The agent sees one flat namespace: one MCP configuration, one skills directory. Whether a server
+> could prefix a plugin's components with the plugin's name depends on the harness base, and for
+> skills it cannot: Agent Skills requires a skill's `name` to equal its directory name, so renaming
+> the directory breaks the skill. A rule the protocol cannot keep on every base is not a rule. So
+> the ambiguity is refused at configuration time, where a person is present to resolve it, rather
+> than resolved silently at run time, where nobody is. Disabling either side clears the conflict.
+
+### 4.3 The direct fields are a plugin without a name
+
+The direct `mcpServers` and `skills` of a harness are exactly the contents of a plugin: tools and
+skills, with the harness standing in for the manifest. This is not an analogy. [§5](#5-exporting-a-harness-as-a-plugin)
+makes it an operation.
+
+## 5. Exporting a harness as a plugin
+
+```http
+GET /v1/harnesses/{harness_id}/plugin
+```
+
+Returns a plugin object whose `files` are an Agent Plugins package built from the harness's direct
+configuration. The result installs into another harness by passing it to `plugins` unchanged, or
+into any other Agent Plugins client by writing its files to disk.
+
+| In the package | Built from |
+|---|---|
+| `plugin.json` | `$schema` for Agent Plugins 1.0.0 and `name` derived from the harness `name` |
+| `mcp.json` | The enabled direct `mcpServers`; `http` becomes `streamable-http`, `sse` stays `sse` |
+| `skills/<name>/…` | Each enabled direct skill, the whole folder |
+
+- The derived `name` is the harness `name` lower-cased, with every run of characters outside
+ `a-z`, `0-9` and `.` replaced by one `-`, leading and trailing `-` removed, and `..` collapsed to
+ `.`. If nothing remains, the harness `id` is used the same way. The result satisfies Agent Plugins
+ §5.5 by construction.
+- `auth` and `headers` MUST be omitted from every server in `mcp.json`. They are credentials the
+ operator entered for this harness, and a package travels. Each omission is recorded in
+ `skipped`, with the server's path in `mcp.json`, so the person exporting knows what to re-enter.
+- Installed plugins are not included. A plugin does not contain plugins; a client that wants one of
+ them reads its files ([§3.1](#31-reading-the-files)).
+- `systemPrompt`, `defaultModel`, `disabledTools` and `base` are not included. They describe the
+ harness, not its tools and skills, and Agent Plugins has no portable place for them.
+- A harness with nothing to export still returns a valid package: a manifest and nothing else.
+
+## 6. Running with plugins
+
+What a hosted server owes an installed, enabled plugin at run time:
+
+- **Skills** are materialised as [Harnesses §4.2](harnesses.md#42-skills) requires: the whole folder,
+ where the agent reads skills.
+- **Remote MCP servers** (`http`, `sse`) are connected as [Harnesses §4.1](harnesses.md#41-mcp-servers)
+ requires. Placeholder expansion MUST NOT be performed in `url` or `headers`.
+- **stdio MCP servers** run inside the same sandbox as the agent, with the same privileges, and never
+ anywhere else. A server MUST set `PLUGIN_ROOT` and `PLUGIN_DATA` in the subprocess environment,
+ MUST expand `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` in `args`, `env` and `cwd`, MUST NOT expand
+ anything else, and MUST resolve `command` as Agent Plugins §7.2.1 says: a bare executable name, or
+ a plugin-relative path beginning with `./`, with no expansion in `command` itself. The default
+ working directory is the plugin root. The containment rules of Agent Plugins §4.1 apply: a
+ `command` or `cwd` that resolves outside the plugin root (or, for `cwd`, outside `PLUGIN_DATA`)
+ is an invalid entry.
+- **`PLUGIN_DATA`** MUST exist and be writable before the first subprocess launches, and MUST persist
+ for the life of the session ([Sessions](sessions.md)), which is the unit of workspace persistence
+ in UHP. A server MAY keep it longer. Agent Plugins asks for persistence across plugin updates; on
+ a hosted server the session is the boundary a client can reason about, so it is the one promised.
+- **A server that cannot run a transport for a base** MUST refuse the write with
+ `unsupported_transport`, naming the transport and the base in `detail`, rather than accept the
+ plugin and skip the server at run time. The rule of Harnesses §4.1 holds: a server MUST NOT
+ advertise MCP support it cannot deliver.
+- **An MCP server that fails** MUST NOT fail the task, exactly as for a directly attached one. A
+ stdio server that exits is the same event as a remote one that refuses the connection.
+- **A disabled plugin** is not materialised and nothing in it is contacted or launched.
+
+## 7. Discovery
+
+A server that implements this chapter reports it in the discovery document
+([Lifecycle §2](lifecycle.md#2-capability-discovery)):
+
+```json
+{
+ "capabilities": { "harness_management": true, "plugins": true },
+ "plugin_schemas": ["https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"]
+}
+```
+
+`plugin_schemas` lists the Agent Plugins manifest schema identifiers the server accepts, and MUST be
+present and non-empty when `plugins` is `true`. A client MUST check both before offering to install
+a package, and MUST NOT offer a package whose `$schema` the server does not list.
+
+A server that reports `plugins: true` MUST accept `plugins` on harness create and update, MUST serve
+the files endpoint ([§3.1](#31-reading-the-files)), and MUST serve the export
+([§5](#5-exporting-a-harness-as-a-plugin)). There is no partial form of the capability.
+
+## 8. Relationship to Agent Plugins conformance
+
+A UHP server with `plugins: true` is an Agent Plugins *client* in that specification's terms
+(§11): it loads a package from a directory, validates the closed manifest, discovers both component
+types from their fixed locations, and, when it launches subprocesses, provides the two environment
+variables and expands them. This chapter adds to that, and never subtracts:
+
+- what Agent Plugins §11.3 says a client SHOULD report, this chapter says a server MUST report, on
+ the object, as `skipped`;
+- placeholders are returned to clients unexpanded;
+- `PLUGIN_DATA` persistence is promised for the life of a session;
+- component names are unique within a harness, and a collision is refused at configuration time.
+
+Agent Plugins itself is versioned by its schema identifiers (§10.1). A later Agent Plugins version
+appears in UHP as a new entry in `plugin_schemas`, which is an additive change to a server and needs
+no new UHP version.
diff --git a/protocol/versions/2026-10-19/schema.md b/protocol/versions/2026-10-19/schema.md
new file mode 100644
index 00000000..f4a915a6
--- /dev/null
+++ b/protocol/versions/2026-10-19/schema.md
@@ -0,0 +1,71 @@
+# Schema
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+The machine-readable definitions are normative for structure. Where this prose and the schema
+disagree about the shape of an object, the schema wins; where they disagree about behaviour, the
+prose wins, because behaviour is not expressible in JSON Schema.
+
+## Files
+
+| File | Format | Use |
+|---|---|---|
+| [`uhp-2026-10-19.openapi.yaml`](../../schema/uhp-2026-10-19.openapi.yaml) | OpenAPI 3.1 | Generate clients and servers; browse the API |
+| [`uhp-2026-10-19.schema.json`](../../schema/uhp-2026-10-19.schema.json) | JSON Schema 2020-12 | Validate objects and streamed events |
+
+Both are versioned by filename. A published version is immutable: fixing a schema means publishing a
+new version, never editing one clients may already have generated from.
+
+## Generating a client
+
+```bash
+# TypeScript
+npx openapi-typescript protocol/schema/uhp-2026-10-19.openapi.yaml -o uhp.d.ts
+
+# Python
+openapi-python-client generate --path protocol/schema/uhp-2026-10-19.openapi.yaml
+
+# Go
+oapi-codegen -package uhp protocol/schema/uhp-2026-10-19.openapi.yaml > uhp.gen.go
+```
+
+## Validating events
+
+Every streamed event validates against the `Event` definition, which is a discriminated union on
+`type`:
+
+```python
+import json, jsonschema
+
+schema = json.load(open("protocol/schema/uhp-2026-10-19.schema.json"))
+validator = jsonschema.Draft202012Validator(
+ {"$ref": "#/$defs/Event", **schema})
+
+for line in stream:
+ if line.startswith("data: "):
+ validator.validate(json.loads(line[6:]))
+```
+
+The conformance suite does exactly this against a live server, so a schema change that the reference
+implementation does not satisfy fails CI rather than shipping.
+
+## The plugin manifest
+
+`PluginManifest` mirrors the Agent Plugins 1.0.0 manifest schema field for field, and is looser in
+one way: it permits additional properties, because a UHP client MUST ignore fields it does not know
+([Versioning](../../VERSIONING.md)) and a later Agent Plugins version will add some. The
+authoritative schema for a manifest is the one its own `$schema` names; a UHP server validates
+against that, and the definition here describes only the shape a client may rely on
+([Plugins §2.2](plugins.md#22-what-the-server-derives)).
+
+## Extension points
+
+A server MAY add fields anywhere the schema allows additional properties:
+
+- `metadata` on a request or response — the intended place for client and server context.
+- `detail` on an error — structured context for a specific failure.
+- Additional output item types, and additional event types.
+
+A server MUST NOT redefine the meaning of a specified field, and MUST NOT add a required field: a
+client written against this version has to keep working. Vendor-specific fields SHOULD carry a
+vendor prefix so that a later version of this specification cannot collide with them.
diff --git a/protocol/versions/2026-10-19/security.md b/protocol/versions/2026-10-19/security.md
new file mode 100644
index 00000000..8a4e9967
--- /dev/null
+++ b/protocol/versions/2026-10-19/security.md
@@ -0,0 +1,172 @@
+# Security considerations
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A UHP server runs an agent that executes tools, writes files, and holds a provider credential, on
+behalf of a caller it has never met. That is a larger blast radius than a model endpoint, and the
+requirements here are collected in one place so an implementer can check them off rather than
+rediscover them.
+
+Requirements stated in other chapters are repeated here rather than only cross-referenced. A
+security rule a reader has to assemble from six chapters is a rule that gets missed.
+
+## 1. Credentials
+
+- A server MUST authenticate every endpoint except `GET /v1/uhp`
+ ([Lifecycle §2](lifecycle.md)).
+- A server MUST NOT distinguish "no such token" from "token not permitted here" in a way that lets a
+ caller enumerate valid tokens.
+- A server MUST NOT echo a credential — the caller's or a provider's — in any response body, error
+ message, event, log line, or artifact.
+- A server SHOULD support revoking a credential, and revocation MUST take effect for new requests
+ immediately.
+
+### 1.1 Provider credentials
+
+The credential a server uses to reach a model provider is the most valuable secret in the system,
+and the agent's own sandbox is the least trustworthy place in it: an agent can be induced to read
+its environment and print it.
+
+- A server SHOULD NOT place a provider credential where the agent's tools can read it.
+- A server that must give a harness a credential SHOULD issue a short-lived, single-session one, and
+ MUST be able to revoke it independently of the underlying key.
+- A server MUST NOT accept a caller-supplied upstream URL for a brokered request without validating
+ it against a configured allow-list. An unvalidated upstream turns the server into an SSRF proxy
+ with its own credential attached.
+
+## 2. Object scope
+
+- Every object — harness, response, session, container, file — MUST be scoped to the principal that
+ created it.
+- A request for an object outside the caller's scope MUST return `404`, never `403`. `403` confirms
+ the id exists, which is exactly what an enumerating attacker wants
+ ([Architecture §5](architecture.md)).
+- Scope MUST be enforced on every operation, not only on read. Cancel, delete, continue and download
+ are all object access.
+
+> The conformance suite cannot fully verify this with one credential. An implementer SHOULD run the
+> equivalent check with two principals: create an object as A, then attempt every operation on it as
+> B, and confirm each returns `404`.
+
+## 3. Artifacts are attacker-influenced content
+
+An agent can be persuaded to write a file with chosen content and a chosen name. Everything that
+serves artifacts MUST treat them as hostile.
+
+- Artifact downloads MUST be served with `X-Content-Type-Options: nosniff`. Without it, an artifact
+ named `x.html` becomes stored XSS against the client's own origin
+ ([Files §3](files.md)).
+- Artifacts SHOULD be served from a different origin than the console or application UI, so that a
+ successful injection cannot reach first-party cookies or storage.
+- A server MUST NOT allow a `container_id` / `file_id` pair to address anything outside its
+ container. Path traversal through artifact ids is the most likely serious vulnerability in a UHP
+ implementation; the conformance suite probes for it (X-08), and passing that probe is a floor, not
+ proof.
+- A server SHOULD cap artifact size and count per session.
+
+## 4. Prompt injection is in scope for the client
+
+A harness that reads a web page, a repository, or an uploaded file may encounter instructions
+addressed to it. UHP cannot prevent this, and a specification that pretended otherwise would be
+worse than one that says so plainly.
+
+What the protocol does provide, and a client SHOULD use:
+
+- **`disabledTools`** on a configured harness — the smallest tool set that can do the job is the
+ smallest injection surface.
+- **`max_step` and `timeout_seconds`** — a bounded task cannot be induced into an unbounded one.
+- **Separate harnesses for separate trust levels.** A harness that reads untrusted input SHOULD NOT
+ be the same configured harness that holds privileged tools or MCP servers.
+- **The event stream.** Tool calls are visible as they happen; a client can surface or gate them.
+
+A server MUST NOT claim that any of this makes an agent safe to point at untrusted input.
+
+## 5. Resource exhaustion
+
+- A server MUST bound task duration, and MUST report `incomplete` rather than `completed` when a
+ budget stopped the work ([Lifecycle §3](lifecycle.md)).
+- A server MUST refuse a second concurrent task in the same session (`session_busy`) — two agents in
+ one working directory is not a defined state, and is also a cheap way to multiply cost.
+- A server SHOULD rate-limit task creation per principal and SHOULD expose remaining budget through
+ `rate_limit_error` responses rather than by failing opaquely.
+- A server MUST bound upload size and reject with `file_too_large` rather than truncating. A silently
+ truncated input produces a confident, wrong answer.
+
+## 6. Data handling
+
+- Session artifacts and transcripts MUST be unreachable after the session is deleted.
+- A server SHOULD document its retention period. "Indefinite" is an answer; silence is not.
+- Session sharing, where implemented, MUST be read-only and revocable, and MUST NOT expose
+ credentials or another principal's data ([Sessions §5](sessions.md)).
+
+## 7. Transport
+
+- TLS MUST be used except on loopback.
+- A server SHOULD send `Strict-Transport-Security`.
+- A server serving any HTML MUST send `X-Frame-Options: DENY` or an equivalent
+ `frame-ancestors 'none'` policy.
+
+## 8. Error hygiene
+
+- `error.message` MUST be safe to show a user: no credentials, internal hostnames, file paths, or
+ stack traces ([Errors §1](errors.md)).
+- A server SHOULD log the detail it withholds, with a correlation id it returns in `error.detail`,
+ so an operator can diagnose what a caller cannot see.
+
+## 9. Plugins are third-party code
+
+A plugin ([Plugins](plugins.md)) is instructions and executables written by someone other than the
+operator installing it. Installing one extends the harness's trust to its author.
+
+- A stdio MCP server declared by a plugin MUST run inside the sandbox that runs the agent, with the
+ agent's privileges and no more. It MUST NOT run on the server host, and MUST NOT be launched
+ through a shell.
+- A server MUST expand only `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`, only in `args`, `env` and `cwd`,
+ and MUST NOT perform any other placeholder or environment-variable expansion. A plugin that could
+ read the sandbox's environment into its own process arguments would read whatever credentials the
+ sandbox holds ([§1](#1-credentials)).
+- A `command` or `cwd` that resolves outside the plugin root is an invalid entry, never a permitted
+ one ([Plugins §6](plugins.md#6-running-with-plugins)).
+- Plugins are installed by whoever manages the harness (class Full), never per request. A
+ per-request plugin would be a per-request MCP server, which [Tasks §1.4](tasks.md#14-reserved-fields-tools-and-include)
+ already declines for the same reason: narrowing is safe, widening is escalation.
+- A skill inside a plugin is prompt content and is subject to [§4](#4-prompt-injection-is-in-scope-for-the-client).
+ A client SHOULD show the manifest's `author`, `homepage` and `repository` before installing, and
+ SHOULD show `skipped` after, so that what did not load is not mistaken for what did.
+- A server MUST omit `auth` and `headers` from an exported package
+ ([Plugins §5](plugins.md#5-exporting-a-harness-as-a-plugin)). An export is meant to leave.
+
+## 10. Environments are shared, and built from what the owner sends
+
+An environment ([Environments](environments.md)) is read by every session that names it, and its
+build runs the project's own manifests and `setup.sh`. Three rules follow:
+
+- **Read-only is enforced.** An agent told not to write will still try; a server MUST make the
+ write fail, by a read-only mount, a user without permission, or an equivalent, and MUST NOT rely
+ on the instruction ([Environments §6](environments.md#6-what-a-session-sees)).
+- **A build has a task's privileges, not the server's.** It runs with the toolchain and network a
+ task gets and no more; it cannot read another environment or any session. On a multi-tenant
+ server it is a job of the tenant that owns the environment ([Environments §9](environments.md#9-security)).
+- **Paths are confined at every endpoint.** A file path, an archive member and a repository tree
+ are all held to the environment's root; links out of it and absolute paths are dropped, never
+ followed ([Environments §3](environments.md#3-files)).
+
+## 11. Memories are read by someone else, later
+
+A memory ([Memories](memories.md)) is written in one session and read in another, by another agent,
+for another person. Three properties follow, and none can be left to the agent.
+
+- **What a memory returns is untrusted content.** A record may have been written by a model that
+ had read a hostile page. A server MUST present recalled content to an agent as data, fenced from
+ instructions, with who wrote it ([Memories §13](memories.md#13-security)).
+- **Reach is the agent's grants, on every call.** An agent may walk the tree from where it was
+ attached, and a search covers what is below the memory it asks; what it can reach is decided by the server from grants, not by what the agent asks
+ for, and a memory it may not read is answered exactly as one that does not exist.
+- **A provider's credential never reaches a sandbox.** It belongs to whoever connected the provider
+ and is used by the server at the moment of a call ([§1](#1-credentials)).
+
+## 12. Reporting a vulnerability
+
+Vulnerabilities in the reference implementation or in this specification follow private disclosure,
+not a public issue. See the repository's security policy. A specification bug that makes a secure
+implementation impossible is treated as a vulnerability, not as a documentation defect.
diff --git a/protocol/versions/2026-10-19/sessions.md b/protocol/versions/2026-10-19/sessions.md
new file mode 100644
index 00000000..0f34c3e0
--- /dev/null
+++ b/protocol/versions/2026-10-19/sessions.md
@@ -0,0 +1,177 @@
+# Sessions
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A session is what makes a second task cheaper than the first: the conversation is still there, and
+so is the working directory. This chapter defines continuing a session, inspecting one, and stopping
+work in one.
+
+## 1. Continuing a session
+
+Send the next task with `previous_response_id`:
+
+```json
+{
+ "input": "Now add tests for the function you just wrote.",
+ "previous_response_id": "resp_a1b2c3"
+}
+```
+
+The server MUST:
+
+- run the new task in the same session, with the same working directory and its files;
+- give the harness the conversational context of the earlier tasks;
+- use the same configured harness;
+- report the same `metadata.session_id`.
+
+`model` MAY differ between tasks in a session. A server MUST honour a per-task model change, because
+switching to a cheaper model for a follow-up is a common and legitimate pattern.
+
+If `previous_response_id` names an unknown response, the server MUST fail with `404` and
+`code: "response_not_found"`. If the session it referred to has expired, `404` with
+`code: "session_expired"` — a client can retry the first from scratch, and should not retry the
+second.
+
+> **Why chain on the response id rather than the session id?**
+> Because the response id is what the client already has: it comes back from the task it just ran.
+> Chaining on it also names an exact point in the conversation, which leaves room for a server to
+> branch from an earlier response later without changing the request shape.
+
+## 2. Listing sessions
+
+Conformance class **Extended**.
+
+```http
+GET /v1/sessions?limit=20&cursor=&harness=chrn_…
+```
+
+```json
+{
+ "sessions": [
+ {
+ "id": "hsess7e78…",
+ "object": "session",
+ "harness_id": "chrn_…",
+ "title": "Summarise README.md",
+ "status": "completed",
+ "created_at": 1786400000,
+ "updated_at": 1786400240
+ }
+ ],
+ "next_cursor": null
+}
+```
+
+Pagination is cursor-based. A server MUST return `next_cursor: null` on the last page, and MUST NOT
+require a client to detect the end by receiving fewer items than it asked for — that heuristic is
+wrong whenever a page is exactly full.
+
+## 3. Inspecting a session
+
+```http
+GET /v1/sessions/{session_id}
+GET /v1/sessions/{session_id}/turns
+```
+
+`/turns` returns the ordered task history of the session, so a client can rebuild a transcript it did
+not store. Each turn identifies its response id, so a client can fetch the full response for any of
+them.
+
+Each item in `turns` MUST carry at least:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | The response id of the turn, usable with `GET /v1/responses/{id}`. |
+| `status` | string | The turn's status, in the response-status vocabulary of [Tasks §1](tasks.md). |
+
+and SHOULD carry, when the server has them: `user` (string, the user message), `assistant` (string,
+the assistant's final text), `tools` (array, the tool calls of the turn), and `files` (array, the
+files the turn produced). A server MAY add fields; a client MUST ignore fields it does not
+understand. This was previously an object with no stated shape, which meant no conformance check
+could assert anything past the status code, and every client that rebuilt a transcript did so
+against one implementation's habits.
+
+A session whose turns read an environment carries `environment`, the environment's id, so a client
+can tell which project a conversation worked in ([Environments §6](environments.md#6-what-a-session-sees)).
+
+## 4. Cancelling
+
+Two scopes, deliberately distinct:
+
+```http
+POST /v1/responses/{response_id}/cancel # stop this task
+POST /v1/sessions/{session_id}/cancel # stop whatever is running in this session
+```
+
+Semantics:
+
+- Cancellation is a request, not a guarantee of immediacy. A server MUST stop the work as soon as it
+ can and MUST reach a terminal state.
+- A cancelled task MUST end with `status: "cancelled"`, never `failed`.
+- Output produced before cancellation MUST be retained.
+- Cancelling an already-terminal task MUST succeed and change nothing. A client retrying a cancel
+ after a dropped connection should not receive an error for having succeeded twice.
+- Cancelling MUST NOT delete the session. The conversation remains continuable.
+
+A server SHOULD respond to cancel within one second even if the harness takes longer to wind down.
+The client is usually a user interface, and a Stop button that does nothing visible for thirty
+seconds reads as broken.
+
+## 5. Session sharing
+
+Conformance class **Full**. A server MAY let a client publish a read-only view of a session.
+
+```http
+POST /v1/sessions/{session_id}/share # publish (a body is OPTIONAL; no body means publish)
+GET /v1/sessions/{session_id}/share # read the share back
+DELETE /v1/sessions/{session_id}/share # revoke
+```
+
+If implemented, the share object returned by `POST` and `GET` MUST carry:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | string | The share's identity. |
+| `url` | string | Where the shared view is served. May be relative, in which case it resolves against the base URL the caller is already using — a server behind a proxy cannot know its public origin, and a base-relative path survives every fronting. |
+
+`object` SHOULD be `"session.share"`. A server MAY carry additional fields (the reference also
+returns an `enabled` toggle and accepts `{"enabled": bool}` bodies); a client MUST ignore fields it
+does not understand. A second `POST` MAY return the existing share or mint a new one, but
+revocation MUST reach every link minted for the session — revoking only the newest tells an
+operator the session is private while somebody still holds a working link.
+
+The rules, unchanged:
+
+- the shared view MUST be read-only — it MUST NOT permit continuing, cancelling, or uploading;
+- `GET` on the published `url` MUST serve the view to a holder of the link with no other
+ credential — a view only its creator can open has not been published to anyone;
+- after `DELETE`, and after the session itself is deleted (§6), the published `url` MUST stop
+ resolving (404 or 410);
+- the share's id MUST NOT function as a credential for the rest of the API;
+- the server MUST NOT expose provider credentials, tokens, or another principal's data through the
+ view.
+
+These were previously behaviors the conformance suite had to discover by probing (the endpoints and
+the object had no stated shape, so a portable check could only guess at paths and skip when the
+guesses missed). They are codified from the shapes the reference implementation demonstrates and
+the R-series measures; the suite now asserts them.
+
+## 6. Deleting
+
+```http
+DELETE /v1/sessions/{session_id}
+```
+
+Deletes the session and its stored history: the transcript, the trace, and the working folder the
+session's tasks wrote. Afterwards the session MUST NOT count toward any storage or memory allowance
+the server enforces, because deletion is how a client makes room. A server MUST answer `2xx`, and a
+later `GET /v1/sessions/{session_id}` MUST return `404`.
+
+`DELETE /v1/traces/{session_id}` is the older path for the same operation. It predates the session
+vocabulary; a server MAY keep serving it (the reference implementation does, as the same handler),
+but the path above is the one the protocol names and the one clients SHOULD use.
+
+A server MUST cancel any in-flight task in the session first, and MUST make the session
+unreadable afterwards. Deletion is the one place where cancel and
+delete are legitimately coupled, because the alternative is a running task writing into storage that
+no longer has an owner.
diff --git a/protocol/versions/2026-10-19/streaming.md b/protocol/versions/2026-10-19/streaming.md
new file mode 100644
index 00000000..fc243f9c
--- /dev/null
+++ b/protocol/versions/2026-10-19/streaming.md
@@ -0,0 +1,161 @@
+# Streaming
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+Agent tasks take minutes. Without a stream, a product can only show a spinner and hope. This chapter
+defines how a server reports progress while work is happening.
+
+## 1. Opening a stream
+
+Set `"stream": true` on `POST /v1/responses`. The server MUST respond with:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache
+```
+
+Each event is a Server-Sent Events message whose `data` is one JSON object:
+
+```
+data: {"type":"response.created","sequence_number":0,"response":{…}}
+
+data: {"type":"response.output_text.delta","sequence_number":7,"item_id":"msg_1","output_index":0,"content_index":0,"delta":"Sum"}
+
+data: {"type":"response.completed","sequence_number":42,"response":{…}}
+
+```
+
+Rules:
+
+- Every event MUST carry `type` and `sequence_number`.
+- `sequence_number` MUST start at `0` and increase by exactly 1 per event within a stream. A client
+ can therefore detect a dropped event rather than silently rendering a gap.
+- The stream MUST end with exactly one terminal event (§4).
+- A server MUST NOT buffer the stream to completion before sending it. A stream delivered all at once
+ at the end is not a stream, and a client cannot tell the difference between that and a hang.
+- Servers behind a proxy MUST disable response buffering. This is the single most common deployment
+ error for UHP servers; it looks exactly like the harness being slow.
+
+## 2. Event vocabulary
+
+Events describe *what happened*. They never describe how to display it.
+
+### 2.1 Response lifecycle
+
+| Event | When |
+|---|---|
+| `response.created` | The task was accepted. Carries the initial `response` with `status: in_progress`. |
+| `response.in_progress` | Work has started. |
+| `response.completed` | Terminal — success. Carries the final `response`. |
+| `response.incomplete` | Terminal — a budget stopped the work. Carries the final `response`. |
+| `response.failed` | Terminal — failure. Carries the final `response`, whose `error` is non-null. |
+
+### 2.2 Output items
+
+| Event | When |
+|---|---|
+| `response.output_item.added` | A new item begins. Carries `output_index` and a shell `item`. |
+| `response.output_item.done` | That item is final. Carries the complete `item`. |
+
+### 2.3 Assistant text
+
+| Event | Payload |
+|---|---|
+| `response.content_part.added` | An empty `output_text` part opens |
+| `response.output_text.delta` | `delta`: the next fragment of text |
+| `response.output_text.done` | `text`: the complete text of the part |
+| `response.content_part.done` | `part`: the finished part |
+| `response.output_text.annotation.added` | `annotation`: an artifact citation (see [Files](files.md)) |
+
+Text deltas are fragments, not lines or tokens. A client MUST concatenate them in `sequence_number`
+order and MUST NOT assume any particular chunking.
+
+### 2.4 Reasoning
+
+| Event | Payload |
+|---|---|
+| `response.reasoning_summary_part.added` | An empty summary part opens |
+| `response.reasoning_summary_text.delta` | `delta`: the next fragment of the summary |
+| `response.reasoning_summary_part.done` | `part`: the finished summary part |
+
+Reasoning is a *summary*, not a verbatim chain of thought. A server MUST NOT be required to expose
+raw model reasoning, and a client MUST treat reasoning as optional — many harness and model
+combinations produce none, and a client that requires it will break on those.
+
+### 2.5 Tool use
+
+| Event | Payload |
+|---|---|
+| `response.function_call_arguments.delta` | `delta`: fragment of the JSON arguments |
+| `response.function_call_arguments.done` | `arguments`: the complete JSON string |
+
+The tool call itself arrives as an `output_item` of type `function_call`, and its result as
+`function_call_output` matched by `call_id`.
+
+### 2.6 Errors
+
+| Event | Payload |
+|---|---|
+| `error` | `code`, `message`, `param` — an error that did not end the task |
+
+An `error` event MUST be followed by a terminal event. A stream that emits `error` and then stops
+without a terminal event is malformed: the client cannot tell whether the task died or the
+connection did.
+
+## 3. Ordering guarantees
+
+A server MUST guarantee:
+
+1. `response.created` is the first event.
+2. Exactly one terminal event is the last.
+3. For any item, `output_item.added` precedes every event referring to it, and `output_item.done`
+ follows them all.
+4. `sequence_number` is strictly monotonic with no gaps.
+
+A server MUST NOT guarantee, and a client MUST NOT assume:
+
+- that items complete in the order they were added (a long tool call may finish after later text);
+- that text arrives in any particular chunk size;
+- that any optional event type appears at all.
+
+## 4. Terminal events
+
+Exactly one of `response.completed`, `response.incomplete`, `response.failed`. Each carries the
+complete final `response` object — a client that missed intermediate events can rely on this one
+alone to render the result. This redundancy is deliberate: a dropped connection mid-stream should
+cost latency, not correctness.
+
+A cancelled task terminates with `response.failed` carrying `status: "cancelled"` in the response
+object. The status field, not the event name, is authoritative.
+
+## 5. Reconnecting
+
+A dropped connection MUST NOT abort the task. The work continues server-side.
+
+To follow a task after a disconnect, a client re-reads it:
+
+```http
+GET /v1/responses/{response_id}
+```
+
+or, for a live event feed of a harness's sessions:
+
+```http
+GET /v1/harnesses/{harness_id}/events
+```
+
+A server MAY additionally support SSE `Last-Event-ID` resumption. If it does, it MUST resume from
+the event *after* the given `sequence_number` and MUST NOT replay events the client already saw.
+
+> A client SHOULD treat the stream as an optimisation and the stored response as the source of
+> truth. Products written the other way round — where the stream is the only place a result exists —
+> lose work every time a load balancer recycles a connection.
+
+## 6. Non-streaming
+
+With `"stream": false` (the default), the server returns a single response object when the task
+reaches a terminal state, with the same `output` array the stream would have assembled. The two
+paths MUST produce identical results for identical input. A server that assembles a different
+`output` for streaming than for non-streaming has two implementations of its own protocol, and one
+of them is wrong.
diff --git a/protocol/versions/2026-10-19/tasks.md b/protocol/versions/2026-10-19/tasks.md
new file mode 100644
index 00000000..a262e8cc
--- /dev/null
+++ b/protocol/versions/2026-10-19/tasks.md
@@ -0,0 +1,288 @@
+# Tasks
+
+**Unified Harness Protocol, version `2026-10-19`**
+
+A task is one unit of work: input in, a result out. It is the endpoint most clients spend all their
+time in.
+
+## 1. Run a task
+
+```http
+POST /v1/responses
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+ "input": "Summarise README.md in three bullets.",
+ "model": "claude-sonnet-4.6",
+ "metadata": { "harness_id": "chrn_08dae611630d467ab3e67ed792570ae5" },
+ "stream": true
+}
+```
+
+### 1.1 Request fields
+
+| Field | Type | Required | Meaning |
+|---|---|---|---|
+| `input` | string \| item[] | yes | The work. A bare string is shorthand for one user message. See §2. |
+| `model` | string | no | Canonical model id. Omitted means the harness's default. |
+| `metadata` | object | no | Client metadata. `harness_id` selects the configured harness (§1.2). `memory` names one more memory this task works with, on a server with the `memories` capability ([Memories §9](memories.md#9-an-agent-and-its-memories)). |
+| `stream` | boolean | no | `true` streams Server-Sent Events; default `false` returns one JSON object. |
+| `previous_response_id` | string | no | Continue the session that produced that response. See [Sessions](sessions.md). |
+| `instructions` | string | no | Additional system guidance for this task only. |
+| `store` | boolean | no | Whether the server retains the response for later reads. Default `true`. |
+| `max_output_tokens` | integer | no | Upper bound on generated tokens. |
+| `max_step` | integer | no | Upper bound on agent steps (tool-call rounds) for this task. |
+| `timeout_seconds` | integer | no | Wall-clock budget for this task. |
+| `environment` | string | no | The environment this task reads, overriding the harness's; refused with `environment_not_found` or `environment_not_ready` before the task starts. Requires the `environments` capability ([Environments §5](environments.md#5-attaching-an-environment)). |
+| `tools` | array | no | **Reserved and ignored.** Accepted, never acted on. See §1.4. |
+| `include` | string[] | no | **Reserved and ignored.** Accepted, never acted on. See §1.4. |
+| `background` | boolean | no | Return as soon as the task is accepted; follow it with the events endpoint. |
+
+A server MUST ignore request fields it does not understand rather than rejecting the request. A
+client MUST NOT rely on an unknown field having an effect.
+
+Ignoring MUST be observable. When a server does not act on a field the request carried, it MUST
+name that field in `metadata.ignored_fields` on the response — an array of request-field names, in
+any order. This is the same principle as model substitution in §1.3: where the server did not do
+what the request literally said, the response says so. A silently ignored field is
+indistinguishable from an honoured one, and a client cannot tell which it got.
+
+`tools` and `include` are reserved and ignored (§1.4), so a server MUST name them in
+`metadata.ignored_fields` whenever a request carries them. A server MUST NOT reject a request for
+carrying either.
+
+`max_step` and `timeout_seconds` are budgets, not guarantees of precision: a server MUST stop the
+task at or after the budget, MUST report `incomplete`, and MUST NOT report `completed` for work it
+truncated.
+
+### 1.2 Selecting the harness
+
+The configured harness is selected by `metadata.harness_id`:
+
+```json
+{ "metadata": { "harness_id": "chrn_…" } }
+```
+
+- If `harness_id` is absent, the server MUST use a default harness and MUST report which one it used
+ in the response `metadata`.
+- If `harness_id` names an unknown harness, or one outside the caller's scope, the server MUST fail
+ with `404` and `code: "harness_not_found"`.
+- If both `previous_response_id` and `harness_id` are present and disagree, the server MUST fail with
+ `409` and `code: "harness_mismatch"` (see [Lifecycle §4](lifecycle.md)).
+
+> **Why is the harness in `metadata` rather than a top-level field?**
+> Because the task surface is deliberately Responses-compatible (see the
+> [README](../../README.md)), and `metadata` is the extension point that surface already defines for
+> caller-supplied context. A top-level `harness` field would be a second, conflicting convention for
+> the same idea, and every existing Responses SDK would have to be patched to send it.
+
+### 1.3 Model selection and substitution
+
+`model` names a canonical model id, not a provider-specific one. Canonical ids are stable across
+providers, so the same request works whether the server reaches a model directly or through an
+aggregator.
+
+If the requested model cannot be served for the selected harness, a server MUST NOT fail silently
+and MUST NOT pretend it ran what was asked. It MUST do exactly one of:
+
+1. **Fail** with `422` and `code: "model_unavailable"`; or
+2. **Substitute** the harness's authorized default, and record the substitution in the response:
+
+```json
+{
+ "model": "gpt-5.4",
+ "metadata": {
+ "requested_model": "gpt-5.6-sol",
+ "model_fallback": true,
+ "model_fallback_reason": "model 'gpt-5.6-sol' is not available for this harness's backend"
+ }
+}
+```
+
+A client can therefore always answer "did the model I asked for actually run?" by comparing `model`
+with `metadata.requested_model`.
+
+> This rule exists because its absence is expensive. A server that substitutes silently makes every
+> measurement downstream wrong — benchmarks, cost attribution, quality comparisons — and the client
+> has no way to detect it. Reporting the substitution costs two fields.
+
+### 1.4 Reserved fields: `tools` and `include`
+
+Both fields arrived with the OpenAI Responses wire shape this version stays compatible with. Neither
+was designed for UHP, and neither has ever had defined semantics here. They are **reserved**: a
+server accepts them, never acts on them, and reports them under `metadata.ignored_fields` (§1.1).
+
+This is a decision rather than a gap left open, so implementers can stop carrying them as unfinished
+work and client authors can stop building on them.
+
+**`tools` cannot mean what it means in the Responses API.** There, the field exists because the
+*client* executes tools: the model emits a `function_call`, the client runs it, and returns a
+`function_call_output` as input on the next request. UHP puts both of those in `output` (§3.1). The
+harness invokes and executes tools itself and reports them as observability. There is no input path
+for a tool result, so the loop `tools` implies cannot be completed by a conformant server — not
+because implementations are immature, but because the object model has no place for the return leg.
+
+**`tools` also cannot mean "MCP servers for this task", which is the other plausible reading.**
+[Harnesses](harnesses.md) §4.1 already specifies MCP servers on the harness, with a
+field table and the semantics that matter: a disabled entry MUST NOT be contacted, an unreachable
+server MUST NOT fail the task. A request-level form would be a second mechanism for one behaviour.
+
+More importantly, it would be an **escalation primitive**. If a request can attach an MCP server,
+anyone holding an API key can point the agent at an endpoint of their choosing, and the agent
+executes tools server-side with the harness's credentials and workspace access. The harness owner
+and the API caller are routinely different parties — a product configures a harness, and its end
+users drive tasks against it. Request-level declaration silently moves a capability decision from
+the accountable party to any caller. The configured harness is a first-class object precisely so
+that decision is made once, deliberately, by whoever owns the consequences.
+
+The durable rule underneath, which applies beyond this field: **narrowing is safe, widening is
+escalation.** A future version could reasonably add a typed per-request tool *disable* list. It
+should never add a per-request *grant*.
+
+**`include` has no vocabulary.** It is `array of string` with no enumerated values, so any string a
+server recognises is one that server named itself. Recognising a value would be inventing a
+vocabulary no other implementation shares.
+
+**How an agent gets tools:** configure them on the harness. See
+[Harnesses](harnesses.md) §4.1 for MCP servers and §4.2 for skills.
+
+Removal is a question for the next version. This one is additive-only and cannot drop a field, so
+the honest form here is to say plainly that these two do nothing.
+
+## 2. Input
+
+`input` is either a string or an array of items.
+
+```json
+{ "input": "Summarise README.md" }
+```
+
+```json
+{
+ "input": [
+ { "role": "user", "content": [
+ { "type": "input_text", "text": "Summarise this report." },
+ { "type": "input_file", "filename": "q3.pdf", "file_data": "data:application/pdf;base64,…" }
+ ]}
+ ]
+}
+```
+
+| Item type | Purpose |
+|---|---|
+| `input_text` | Text |
+| `input_file` | A file, inline as a data URL in `file_data`, or by `file_id` from a prior upload |
+| `input_image` | An image, inline or by `file_id` |
+
+A server at conformance class **Core** MUST accept `input_text`. A server at **Extended** MUST also
+accept `input_file` and `input_image`. See [Files](files.md).
+
+## 3. The response object
+
+```json
+{
+ "id": "resp_a1b2c3",
+ "object": "response",
+ "created_at": 1786400000,
+ "status": "completed",
+ "error": null,
+ "incomplete_details": null,
+ "previous_response_id": null,
+ "model": "claude-sonnet-4.6",
+ "output": [
+ { "id": "rs_1", "type": "reasoning", "summary": [ { "type": "summary_text", "text": "…" } ], "status": "completed" },
+ { "id": "fc_1", "type": "function_call", "call_id": "call_1", "name": "read_file",
+ "arguments": "{\"path\":\"README.md\"}", "status": "completed" },
+ { "id": "fco_1", "type": "function_call_output", "call_id": "call_1", "output": "…", "status": "completed" },
+ { "id": "msg_1", "type": "message", "role": "assistant", "status": "completed",
+ "content": [ { "type": "output_text", "text": "- …\n- …\n- …", "annotations": [] } ] }
+ ],
+ "store": true,
+ "usage": { "input_tokens": 5120, "output_tokens": 240, "total_tokens": 5360 },
+ "metadata": { "session_id": "hsess7e78…" }
+}
+```
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | `resp_`-prefixed |
+| `object` | string | yes | Always `response` |
+| `created_at` | integer | yes | Unix seconds |
+| `status` | string | yes | See [Lifecycle §3](lifecycle.md) |
+| `error` | object \| null | yes | Present and non-null only when `status` is `failed` |
+| `output` | item[] | yes | Ordered; MAY be empty for a task that produced nothing |
+| `model` | string | yes | The model that actually ran |
+| `usage` | object \| null | yes | `null` when the server cannot account for usage — never a fabricated zero |
+| `metadata` | object | yes | MUST include `session_id`; see §1.3 for substitution fields |
+| `previous_response_id` | string \| null | yes | The response this one continues, if any |
+| `store` | boolean | yes | Whether this response was retained |
+
+### 3.1 Output items
+
+| `type` | Meaning |
+|---|---|
+| `message` | Assistant text, in `content[].text`, with `annotations` for artifacts |
+| `reasoning` | The agent's summarised thinking, in `summary[].text` |
+| `function_call` | A tool the agent invoked, with `arguments` as a JSON string |
+| `function_call_output` | The result of that tool call, matched by `call_id` |
+
+A client MUST tolerate output item types it does not recognise, and MUST NOT assume any ordering
+beyond the array order given. A client that renders only `message` items and ignores the rest is a
+valid client.
+
+## 4. Reading a task back
+
+```http
+GET /v1/responses/{response_id}
+```
+
+Returns the same response object. A server that retained the response (`store: true`) MUST return it
+after completion; a server MAY return `404` with `code: "response_not_found"` for a response created
+with `store: false`.
+
+```http
+GET /v1/responses/{response_id}/input_items
+```
+
+Returns the input the task was created with, for clients that need to reconstruct a transcript
+without having stored it themselves.
+
+## 5. Cancelling
+
+```http
+POST /v1/responses/{response_id}/cancel
+```
+
+See [Sessions §4](sessions.md).
+
+## 6. Idempotency
+
+A client MAY send an idempotency key:
+
+```http
+Idempotency-Key: <client-generated-unique-string>
+```
+
+A server that advertises `idempotency` MUST, for a repeated key:
+
+- return the result of the **first** request, and
+- **not** start a second execution.
+
+If the first request is still running, the server MUST wait for it and return its result rather than
+returning a partial or a conflict. Agent tasks are expensive and side-effecting: a retry that runs
+the work twice is worse than a slow answer.
+
+Idempotency keys SHOULD be retained for at least 24 hours.
+
+## 7. Deleting
+
+```http
+DELETE /v1/responses/{response_id}
+```
+
+Deletes the stored response. A server MUST NOT let this cancel a running task — cancellation and
+deletion are different intentions, and conflating them means a client cannot clean up history
+without stopping work.