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.

spec: session sharing codified, closing the four gaps of #44

richard-epsilla76fd68346969
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index a8f0bba5..9ecc05d4 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -6,6 +6,27 @@ All notable changes to the Unified Harness Protocol.
### Clarified
+- **Session sharing is codified** ([Sessions §5](versions/2026-08-11/sessions.md#5-session-sharing)),
+ closing the four gaps of [#44](https://github.com/HarnessRouter/harnessrouter/issues/44): the
+ share object is schema'd (`SessionShare`: `id` and `url` required, `url` may be base-relative),
+ `DELETE /v1/sessions/{id}/share` is the named revocation endpoint (other forms MAY be kept), a
+ bodyless `POST` publishes, and revocation MUST reach every link minted. Sharing itself remains a
+ MAY. These are the shapes the reference implementation already demonstrates and the R-series
+ already measures; the suite now asserts them instead of probing for them.
+
+- **Turn items have a shape** ([Sessions §3](versions/2026-08-11/sessions.md#3-inspecting-a-session)):
+ each item of `GET /v1/sessions/{id}/turns` MUST carry `id` (the response id) and `status`, and
+ SHOULD carry `user` / `assistant` / `tools` / `files`. Previously `additionalProperties: true`
+ and nothing else, which held X-04 at "the endpoint answered 200".
+
+### Conformance
+
+- `R-01`/`R-02` validate the share object against the schema and FAIL (no longer skip) when it
+ carries no `url`; `R-06` asserts the named `DELETE` revocation endpoint and FAILs (no longer
+ skips) when it does not work; `X-04` validates every turn item. New defect stub mode:
+ a server whose revocation exists only as a toggle now fails `R-06`.
+
+
- **`tools` and `include` are reserved and ignored** ([Tasks §1.4](versions/2026-08-11/tasks.md#14-reserved-fields-tools-and-include)).
Both arrived with the OpenAI Responses wire shape this version stays compatible with, and neither
ever had defined semantics in UHP. A server accepts them and does not act on them.
diff --git a/protocol/conformance/tests/share_defect_stub.py b/protocol/conformance/tests/share_defect_stub.py
index bb99e040..823d27aa 100644
--- a/protocol/conformance/tests/share_defect_stub.py
+++ b/protocol/conformance/tests/share_defect_stub.py
@@ -39,6 +39,8 @@ DEFECTS = {
"revoke_lies", # revocation answers 200 and revokes nothing
"multi_mint", # every POST mints a new link; revocation kills only the newest
"share_outlives_session", # the link survives the deletion of its session
+ "no_delete_revocation", # revocation exists only as the {"enabled": false} toggle; the
+ # endpoint §5 NAMES (DELETE on /share) answers 405
}
assert DEFECT in DEFECTS, f"unknown defect {DEFECT!r}; one of {sorted(DEFECTS)}"
@@ -155,15 +157,13 @@ class H(BaseHTTPRequestHandler):
if method == "POST" and not rest:
if DIALECT == "enabled":
+ # §5: a body is OPTIONAL and no body means publish. This dialect ALSO accepts the
+ # toggle body, which §5 permits ("a server MAY accept {"enabled": bool}").
try:
- body = json.loads(self.body or b"")
+ body = json.loads(self.body or b"null")
except Exception:
body = None
- if not isinstance(body, dict) or "enabled" not in body:
- return self.send(422, {"detail": [{"type": "missing",
- "loc": ["body", "enabled"],
- "msg": "Field required"}]})
- if body["enabled"] is False:
+ if isinstance(body, dict) and body.get("enabled") is False:
return self.revoke(sid, existing)
if existing and DEFECT != "multi_mint":
return self.send(200, self.share_body(existing[-1], sid))
@@ -181,9 +181,10 @@ class H(BaseHTTPRequestHandler):
return self.send(200, self.share_body(existing[-1], sid))
if method == "DELETE" and not rest:
- if DIALECT == "enabled":
- # This dialect's revocation lives in the POST body, nowhere else — which is
- # exactly the shape R-06's last attempt exists for.
+ if DEFECT == "no_delete_revocation":
+ # The toggle still works; the endpoint §5 NAMES does not. R-06 must refuse to
+ # call that conformant — a named MUST that answers 405 is per-implementation
+ # folklore again.
return self.send(405, {"error": {"code": "method_not_allowed", "message": "no"}})
if not existing:
return self.send(404, {"error": {"code": "share_not_found", "message": "none"}})
diff --git a/protocol/conformance/tests/test_session_sharing_checks.py b/protocol/conformance/tests/test_session_sharing_checks.py
index 737fba67..5f310097 100644
--- a/protocol/conformance/tests/test_session_sharing_checks.py
+++ b/protocol/conformance/tests/test_session_sharing_checks.py
@@ -37,6 +37,7 @@ CAUGHT_BY = {
"leaks_credentials": "R-05",
"revoke_lies": "R-06",
"multi_mint": "R-06",
+ "no_delete_revocation": "R-06",
"share_outlives_session": "R-07",
}
@@ -134,9 +135,9 @@ def test_a_conformant_toggle_dialect_server_passes_every_check():
assert all(o is Outcome.PASS for o in out.values()), out
-def test_the_toggle_dialects_revocation_is_still_a_real_probe():
- """R-06's last attempt believes a 200 only when it speaks revocation's vocabulary, so a
- toggle server whose revocation lies must still be caught through that path."""
+def test_a_lying_revocation_is_caught_in_the_toggle_dialect_too():
+ """§5 now NAMES the revocation endpoint, and the dialect stub serves it; a server whose
+ DELETE answers 200 and revokes nothing must still fail R-06 whichever dialect minted."""
out = _run_series("revoke_lies", dialect="enabled")
assert out["R-06"] is Outcome.FAIL, out
assert [i for i, o in out.items() if o is Outcome.FAIL] == ["R-06"], out
diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.py
index 77dafe32..7567c4d1 100644
--- a/protocol/conformance/uhp_conformance/checks.py
+++ b/protocol/conformance/uhp_conformance/checks.py
@@ -557,7 +557,7 @@ def x03(ctx):
assert r.status == 200, f"GET /v1/sessions/{{id}} returned HTTP {r.status}"
-@check("X-04", "A session's turn history is available", "extended",
+@check("X-04", "A session's turn history is available, in the specified shape", "extended",
f"{SPEC}/sessions.md#3-inspecting-a-session")
def x04(ctx):
sid = ctx.state.get("session_id")
@@ -565,6 +565,16 @@ def x04(ctx):
raise Skip("no session id from an earlier task")
r = ctx.client.get(f"/v1/sessions/{sid}/turns")
assert r.status == 200, f"GET /v1/sessions/{{id}}/turns returned HTTP {r.status}"
+ # Sessions §3 now states the item shape (id + status at least), so this asserts it instead of
+ # stopping at the status code — the check that could previously only "check for a 200".
+ turns = (r.json or {}).get("turns")
+ assert isinstance(turns, list), f"the body carries no `turns` array (keys: {sorted(r.json or {})})"
+ if not turns:
+ raise Skip("the session reports no turns to inspect, so the item shape cannot be observed")
+ for i, t in enumerate(turns):
+ ctx.validate(t, "TurnItem")
+ assert t.get("id") and isinstance(t.get("id"), str), f"turns[{i}] has no response id"
+ assert t.get("status"), f"turns[{i}] has no status"
@check("X-05", "A file can be sent as task input", "extended", f"{SPEC}/files.md#1-sending-files-in")
@@ -1015,11 +1025,18 @@ def _share(ctx) -> dict:
d = r.json
url = next((d[k] for k in ("url", "share_url", "href", "link", "location")
if isinstance(d.get(k), str) and d[k]), "") or r.header("location")
- if not url:
- _skip("the share carries no URL, and Sessions §5 does not say where a shared view is "
- f"served, so this check cannot locate it (keys: {sorted(d)[:8]}). The specification "
- "should name the view's endpoint, or the share object should be schema'd with a "
- "field that does.")
+ assert url, (
+ f"the share object carries no `url` (keys: {sorted(d)[:8]}). Sessions §5 requires the "
+ "share to say where its view is served; without it a client cannot open, audit, or "
+ "revoke what it just published.")
+ try:
+ ctx.validate(d, "SessionShare")
+ except Skip:
+ # Validator unavailable (no jsonschema, or the schema file is not alongside an installed
+ # wheel). The structural asserts above already ran; degrading here is the difference
+ # between one weaker check and the ENTIRE R-series cascade-skipping through this cached
+ # mint. A real schema VIOLATION is an AssertionError and still fails.
+ pass
share = {"id": d.get("id") or "", "url": url, "path": _view_path(ctx, url), "session_id": sid,
"body": d}
ctx.state["share"] = share
@@ -1151,34 +1168,14 @@ def r06(ctx):
if url and _view_path(ctx, url) not in live:
live.append(_view_path(ctx, url))
- # §5 requires revocation and names no path, so the endpoint has to be searched for.
- attempts = [("DELETE", f"/v1/sessions/{sid}/share", None),
- ("POST", f"/v1/sessions/{sid}/share/revoke", None),
- ("DELETE", f"/v1/shares/{sh['id']}" if sh["id"] else "", None),
- # The toggle dialect (the reference implementation's native form). Tried LAST,
- # and believed only when the answer speaks revocation's own vocabulary: a
- # bodyless-dialect server would 200 this by MINTING — it ignores the body — and
- # a mint mistaken for a revocation would fail this check with a false message.
- ("POST", f"/v1/sessions/{sid}/share", {"enabled": False})]
- done = ""
- for method, path, payload in attempts:
- if not path:
- continue
- r = ctx.client.request(method, path, body=payload)
- if not 200 <= r.status < 300:
- continue
- if payload is not None:
- d = r.json if isinstance(r.json, dict) else {}
- if not (d.get("enabled") is False or d.get("deleted") is True):
- continue
- done = f"{method} {path}"
- break
- if not done:
- raise Skip(
- "Sessions §5 requires that a share be revocable and names no endpoint for it, so this "
- "check cannot locate one. The specification should name a path: a MUST with no "
- "endpoint is a MUST that every implementation satisfies differently, and no portable "
- "check can confirm it.")
+ # §5 names the endpoint: DELETE on the share endpoint revokes. What used to be a search
+ # over guessed paths, ending in a skip that blamed the specification, is now an assertion.
+ r = ctx.client.delete(f"/v1/sessions/{sid}/share")
+ assert 200 <= r.status < 300, (
+ f"DELETE /v1/sessions/{{id}}/share returned HTTP {r.status}. §5 names this endpoint for "
+ "revocation; a server may keep other forms besides, but the named one must work — that "
+ "is what makes revocation portable instead of per-implementation folklore.")
+ done = f"DELETE /v1/sessions/{sid}/share"
ctx.state["share"] = "the share minted for this run was revoked by R-06"
ctx.state["share_readable"] = False
diff --git a/protocol/schema/uhp-2026-08-11.openapi.yaml b/protocol/schema/uhp-2026-08-11.openapi.yaml
index 5c47ec14..fa5e35bc 100644
--- a/protocol/schema/uhp-2026-08-11.openapi.yaml
+++ b/protocol/schema/uhp-2026-08-11.openapi.yaml
@@ -338,7 +338,56 @@ paths:
schema:
type: object
properties:
- turns: { type: array, items: { type: object, additionalProperties: true } }
+ 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:
@@ -882,6 +931,37 @@ components:
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
+
Session:
type: object
required: [id]
diff --git a/protocol/schema/uhp-2026-08-11.schema.json b/protocol/schema/uhp-2026-08-11.schema.json
index f2592cf2..070f3df7 100644
--- a/protocol/schema/uhp-2026-08-11.schema.json
+++ b/protocol/schema/uhp-2026-08-11.schema.json
@@ -1005,6 +1005,68 @@
}
},
"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'.",
+ "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
}
}
}
diff --git a/protocol/versions/2026-08-11/sessions.md b/protocol/versions/2026-08-11/sessions.md
index 7b4c7a70..163b7bf4 100644
--- a/protocol/versions/2026-08-11/sessions.md
+++ b/protocol/versions/2026-08-11/sessions.md
@@ -77,6 +77,20 @@ GET /v1/sessions/{session_id}/turns
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.
+
## 4. Cancelling
Two scopes, deliberately distinct:
@@ -105,15 +119,39 @@ seconds reads as broken.
Conformance class **Full**. A server MAY let a client publish a read-only view of a session.
```http
-POST /v1/sessions/{session_id}/share
-GET /v1/sessions/{session_id}/share
+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:
+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;
-- the server MUST allow revocation;
-- the server MUST NOT expose provider credentials, tokens, or another principal's data through it.
+- `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