HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
site: version-addressable spec URLs, TOC scroll-spy, and repo→web build automation
AIinWEB38991a84ea03a
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.ymlindex 807c8e2e..1bb34146 100644--- a/.github/workflows/tests.yml+++ b/.github/workflows/tests.yml@@ -83,3 +83,29 @@ jobs:# suite pass and a failing test still fail; the first real test file makes it moot.- run: npm test -- --passWithNoTests- run: npm run build++ # The unifiedharnessprotocol.org site is generated from protocol/ markdown by+ # protocol/site/build.py and deployed by Vercel. Nothing gated it until now — a broken generator,+ # a dead cross-link, a missing #anchor, or a description-manifest violation would reach the+ # production deploy with a green PR. This job runs the SAME build.sh the Vercel deploy runs, from+ # the same working directory (protocol/), so the gate and the deploy cannot diverge; build.py+ # self-checks links, anchors, versions and metadata, so the build failing is the signal.+ site:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ # Read the interpreter from the same .python-version the Vercel build reads, so CI and the+ # deploy can never run different Pythons.+ - uses: actions/setup-python@v5+ with:+ python-version-file: protocol/.python-version+ cache: pip+ cache-dependency-path: protocol/site/requirements.txt+ - name: Build the spec site exactly as the deploy does+ working-directory: protocol+ run: bash site/build.sh+ # The single host config gates the deploy; a malformed vercel.json, or one whose build no+ # longer points at build.sh, would break publishing silently. Assert it stays valid and wired.+ - name: The host config stays valid and wired to build.sh+ run: |+ python3 -c "import json; c=json.load(open('protocol/vercel.json')); assert c['buildCommand']=='bash site/build.sh', 'buildCommand drifted from build.sh'; assert c['outputDirectory']=='site/dist', 'outputDirectory drifted'"diff --git a/protocol/.python-version b/protocol/.python-versionnew file mode 100644index 00000000..e4fba218--- /dev/null+++ b/protocol/.python-version@@ -0,0 +1 @@+3.12diff --git a/protocol/CONNECTING.md b/protocol/CONNECTING.mdnew file mode 100644index 00000000..2878e70f--- /dev/null+++ b/protocol/CONNECTING.md@@ -0,0 +1,58 @@+# Implement a client++A UHP [client](versions/2026-08-11/architecture.md#1-roles) discovers the harnesses a server+runs, submits a task, receives progress events, and retrieves the resulting files. It speaks+only UHP over HTTP and does not need to know which harness runs behind the server. This guide+is the procedure; the [Architecture chapter](versions/2026-08-11/architecture.md#1-roles) is+the definition.++For the other role — a server that runs harnesses behind the contract — see [Implement a server](SERVING.md).++## What a client does++A client is a product, CLI, CI job, or another agent that wants work done. It does not run+the harness; it drives a server that does. The full definitions of client, server, and+harness are in the [Architecture chapter](versions/2026-08-11/architecture.md#1-roles) — this guide is+the procedure, not the definition.++Integration is deliberately light. The task surface is shaped like a responses API, so most+of the work is ordinary HTTP plus reading an event stream.++## Generate the client++Do not hand-write types. Every version publishes OpenAPI 3.1 and JSON Schema 2020-12 in the+[schema chapter](versions/2026-08-11/schema.md) — generate a typed client for your language from it and+you have the request and response shapes for free.++## The integration, step by step++1. **Discover the catalog.** Ask the server which harnesses it runs and which models each+ accepts. A client selects a *configured harness* — a base plus its configuration — by the+ server-assigned id. [Harnesses chapter](versions/2026-08-11/harnesses.md).+2. **Submit a task.** One unit of work: input in, result out. Name the configured harness and+ send the request. [Tasks chapter](versions/2026-08-11/tasks.md).+3. **Consume the stream.** Read the event stream to follow progress while the task runs, and+ reconnect if the connection drops — the protocol defines how to resume without losing+ events. [Streaming chapter](versions/2026-08-11/streaming.md).+4. **Continue in a session.** To pick up where a task left off, carry the session forward+ instead of starting cold. [Sessions chapter](versions/2026-08-11/sessions.md).+5. **Take the artifacts.** Download the files the run produced. [Files chapter](versions/2026-08-11/files.md).+6. **Cancel and handle errors.** Stop work cleanly, and read failures from the documented+ error taxonomy rather than guessing from status codes. [Errors chapter](versions/2026-08-11/errors.md).++## A minimal end-to-end shape++A client that submits one task and reads its result touches only the core surface:++ POST /v1/tasks → submit against a configured harness+ GET /v1/tasks/{id}/events → stream progress to completion+ GET /v1/tasks/{id} → read the result+ GET /v1/files/{id} → download an artifact++Generate the exact request and response bodies from the [schema](versions/2026-08-11/schema.md); the+[conformance suite](conformance/README.md) shows the same calls run against a real server.++## Next++For the server role, see [Implement a server](SERVING.md). Questions the specification does not answer belong in+[GitHub discussions](https://github.com/HarnessRouter/harnessrouter/discussions).diff --git a/protocol/IMPLEMENTATIONS.md b/protocol/IMPLEMENTATIONS.mdnew file mode 100644index 00000000..7bec788c--- /dev/null+++ b/protocol/IMPLEMENTATIONS.md@@ -0,0 +1,60 @@+# Examples++Example implementations of the Unified Harness Protocol, grouped by the+[role](versions/2026-08-11/architecture.md#1-roles) each fills. Listings are+community-maintained by pull request and **do not imply endorsement or+certification** — the only conformance claim that means anything is+[passing the conformance suite](conformance/README.md).++<div class="impl-actions">+<a class="impl-cta" href="#listing-criteria">Add an implementation</a>+<a class="impl-crit" href="#listing-criteria">Listing criteria</a>+</div>++## Example servers++A server runs one or more harnesses behind the contract. Guide: [Implement a server](SERVING.md).++<div class="impl-list">++<div class="impl-card">+<div class="impl-head"><a href="https://github.com/HarnessRouter/harnessrouter"><b>HarnessRouter Community Edition</b></a><span class="role role-server">Server</span></div>+<p>Open-source runner that puts existing harnesses — Codex, Claude Code, Hermes — behind the UHP contract. HarnessRouter · Apache-2.0.</p>+<p class="impl-meta">UHP 2026-08-11</p>+</div>++</div>++## Example clients++A client drives a UHP server. Guide: [Implement a client](CONNECTING.md).++<div class="impl-list">++<div class="impl-card">+<div class="impl-head"><a href="https://github.com/SuperagenticAI/superqode"><b>SuperQode</b></a><span class="role role-client">Client</span></div>+<p>Harness-engineering framework that connects to a UHP server via <code>superqode connect uhp</code>. SuperagenticAI · Apache-2.0.</p>+<p class="impl-meta">UHP 2026-08-11</p>+</div>++</div>++## Listing criteria++A listing is a factual row, not a certification. Open a pull request against+this file in the [repository](https://github.com/HarnessRouter/harnessrouter)+adding one card. To merge, an entry needs:++1. A public, usable release — a repository or a product page, not an announcement.+2. The UHP version the implementation targets.+3. A maintainer contact reachable from the linked page.+4. The role it fills: **Server** (runs harnesses behind the contract), **Client**+ (drives a UHP server), **SDK** (a library for building either), or a+ combination.++A conformance level appears on a listing only once UHP publishes reproducible+test evidence for that implementation; until then, absence of a level is+expected, not a mark against the entry.++Building an implementation? Start with [Implement a server](SERVING.md) or+[Implement a client](CONNECTING.md).diff --git a/protocol/README.md b/protocol/README.mdindex 102426e8..aaae0485 100644--- a/protocol/README.md+++ b/protocol/README.md@@ -35,25 +35,17 @@ job, not a completion.| **Versioning rules** | [`VERSIONING.md`](VERSIONING.md) || **License** | Apache-2.0, same as the repository |-## This standard does not require HarnessRouter Cloud--That is the point of writing it down, so it is worth being concrete rather than reassuring.+## No hosted service requiredUHP is an HTTP contract. A conformant server is any server that answers the requests in thisspecification with the responses in this specification. It may run agents in containers, insubprocesses, on a queue, or on someone else's infrastructure. Nothing in the wire format requires-a hosted service, an account, a licence key, or a call home.--Two independent implementations exist to keep that honest:+a hosted service, an account, a licence key, or a call home — a conformant server can run wholly on+your own machine, on your own provider keys, storing everything on a volume you own.-- **HarnessRouter Community Edition** — the reference implementation, in this repository, running- wholly on your own machine (`docker run harnessrouter/harnessrouter:0.3.0`). It uses your own- provider keys and stores everything on a volume you own. It is the implementation the conformance- suite is developed against.-- **HarnessRouter Cloud** — a commercial hosted implementation of the same protocol.--A client written against this specification works with either, and with any third implementation-that passes the conformance suite. If you find a behaviour the specification does not describe but+A client written against this specification works with any server that passes the conformance+suite, whoever built it. The [examples](IMPLEMENTATIONS.md) page lists the servers and clients+built against UHP so far. If you find a behaviour the specification does not describe butyour client depends on, that is a specification bug — please[open an issue](https://github.com/HarnessRouter/harnessrouter/issues).@@ -123,6 +115,11 @@ of an existing field. A client that ignores every UHP extension still gets a wor4. Publish your report. A server that passes at a class MAY describe itself as"UHP 2026-08-11 conformant (<class>)".+Two role-specific guides walk through this in order:+[Implement a client](CONNECTING.md) — discovery, task submission, event handling, and+artifact retrieval — and [Implement a server](SERVING.md) — the operations a server answers+and how it connects one or more harnesses.+## ContributingChanges to this specification follow [`GOVERNANCE.md`](GOVERNANCE.md). The short version: propose indiff --git a/protocol/SERVING.md b/protocol/SERVING.mdnew file mode 100644index 00000000..395fd172--- /dev/null+++ b/protocol/SERVING.md@@ -0,0 +1,68 @@+# Implement a server++How to put an agent harness behind the Unified Harness Protocol — what a server must+answer, in what order to build it, and how to prove it works. This guide is the+practical companion to the [specification](versions/2026-08-11/index.md); where the two+disagree, the specification wins.++## What a UHP server is++A UHP server is any HTTP server that answers the requests in the specification with the+responses in the specification. It may run agents in containers, in subprocesses, on a+queue, or on someone else's infrastructure. Nothing in the wire format requires a hosted+service, an account, a licence key, or a call home.++Two shapes of server exist, and the contract is identical for both:++- A **runner** puts existing harnesses — Codex, Claude Code, Hermes — behind the+ contract and advertises them as its catalog.+- A **native harness** speaks UHP itself: one harness, served directly, no adapter in+ between. If you maintain a harness, this is the shape that makes every UHP client+ yours at once.++## The contract, in build order++Build in the order the conformance suite tests, because each stage is testable on its+own:++1. **Discovery** — advertise the harnesses you run and the models they accept.+ [Harnesses chapter](versions/2026-08-11/harnesses.md).+2. **Tasks** — accept one unit of work, run it, return the result. The task surface is+ deliberately shaped like a responses API, plus what a harness needs and a model+ endpoint has no concept of. [Tasks chapter](versions/2026-08-11/tasks.md).+3. **Streaming** — report progress while long tasks run, and survive a dropped+ connection. [Streaming chapter](versions/2026-08-11/streaming.md).+4. **Sessions** — let a task continue where a previous one left off.+ [Sessions chapter](versions/2026-08-11/sessions.md).+5. **Files** — take files in, hand artifacts back.+ [Files chapter](versions/2026-08-11/files.md).+6. **Cancellation and errors** — stop running work cleanly and fail in the documented+ taxonomy. [Errors chapter](versions/2026-08-11/errors.md).++The [schema chapter](versions/2026-08-11/schema.md) publishes OpenAPI 3.1 and JSON+Schema 2020-12 for every version — generate your types instead of writing them.++## Prove it++Run the conformance suite against your server from day one; it is designed to be a+development tool, not a final exam:++ pip install -e protocol/conformance+ uhp-conformance --base-url https://your-server --api-key "$KEY" --class core++Classes are cumulative: `core` is the contract every server must answer, `extended` and+`full` add the surfaces above it. `--only` reruns a single failing check while you fix+it, and every failure cites the specification sentence it violates. The suite runs real+agent tasks — that is deliberate, because the defects worth catching only appear when+real work runs.++## Get listed++When the suite passes at any class, add your server to the+[examples](IMPLEMENTATIONS.md) page by pull request, with the report JSON as+evidence. Listing is not certification, and the page says so — but a row with a+reproducible report is how every ecosystem entry starts.++Questions the specification does not answer belong in+[GitHub discussions](https://github.com/HarnessRouter/harnessrouter/discussions);+changes you need belong in [governance](GOVERNANCE.md), prose first.diff --git a/protocol/site/.gitignore b/protocol/site/.gitignorenew file mode 100644index 00000000..245259b6--- /dev/null+++ b/protocol/site/.gitignore@@ -0,0 +1,2 @@+.vercel+.env*diff --git a/protocol/site/build.py b/protocol/site/build.pyindex 7e0af7c5..d87fa919 100644--- a/protocol/site/build.py+++ b/protocol/site/build.py@@ -14,6 +14,7 @@ to any static host.from __future__ import annotationsimport html+import jsonimport pathlibimport reimport shutil@@ -28,8 +29,29 @@ HERE = pathlib.Path(__file__).parentROOT = HERE.parent # protocol/DIST = HERE / "dist"VERSION = "2026-08-11"+# 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.+VERSIONS = ["2026-08-11"]SITE = "unifiedharnessprotocol.org"+# The specification's chapters, in reading order. NAV builds their per-version paths from this so+# the version lives in exactly one place; adding a version means prepending it to VERSIONS.+SPEC_CHAPTERS = [+ ("index", "Overview"),+ ("architecture", "Architecture"),+ ("lifecycle", "Lifecycle"),+ ("harnesses", "Harnesses"),+ ("tasks", "Tasks"),+ ("streaming", "Streaming"),+ ("sessions", "Sessions"),+ ("files", "Files"),+ ("errors", "Errors"),+ ("security", "Security"),+ ("schema", "Schema"),+]+# ── information architecture ────────────────────────────────────────────────────────────# Mirrors the shape a protocol site is expected to have — an introduction, a versioned# specification, the machine-readable definitions, conformance, and the change process — so a@@ -38,27 +60,25 @@ NAV = [("Introduction", [("index.html", "What is UHP?", ROOT / "README.md"),]),- (f"Specification · {VERSION}", [- ("spec/index.html", "Overview", ROOT / f"versions/{VERSION}/index.md"),- ("spec/architecture.html", "Architecture", ROOT / f"versions/{VERSION}/architecture.md"),- ("spec/lifecycle.html", "Lifecycle", ROOT / f"versions/{VERSION}/lifecycle.md"),- ("spec/harnesses.html", "Harnesses", ROOT / f"versions/{VERSION}/harnesses.md"),- ("spec/tasks.html", "Tasks", ROOT / f"versions/{VERSION}/tasks.md"),- ("spec/streaming.html", "Streaming", ROOT / f"versions/{VERSION}/streaming.md"),- ("spec/sessions.html", "Sessions", ROOT / f"versions/{VERSION}/sessions.md"),- ("spec/files.html", "Files", ROOT / f"versions/{VERSION}/files.md"),- ("spec/errors.html", "Errors", ROOT / f"versions/{VERSION}/errors.md"),- ("spec/security.html", "Security", ROOT / f"versions/{VERSION}/security.md"),- ("spec/schema.html", "Schema", ROOT / f"versions/{VERSION}/schema.md"),+ ("Specification", [+ (f"spec/{VERSION}/{name}.html", title, ROOT / f"versions/{VERSION}/{name}.md")+ for name, title in SPEC_CHAPTERS]),("Conformance", [("conformance.html", "Conformance suite", ROOT / "conformance/README.md"),]),+ ("Implement UHP", [+ ("connecting.html", "Implement a client", ROOT / "CONNECTING.md"),+ ("serving.html", "Implement a server", ROOT / "SERVING.md"),+ ]),("Community", [("versioning.html", "Versioning", ROOT / "VERSIONING.md"),("governance.html", "Governance", ROOT / "GOVERNANCE.md"),("changelog.html", "Changelog", ROOT / "CHANGELOG.md"),]),+ ("Ecosystem", [+ ("examples.html", "Examples", ROOT / "IMPLEMENTATIONS.md"),+ ]),]# Pages reachable by link but not listed in the sidebar: background and context that should not sit@@ -75,6 +95,15 @@ DESCRIPTIONS = {"index.html":"The Unified Harness Protocol (UHP) is an open standard for running complete agent ""harnesses — tasks, sessions, streaming, files — through one shared contract.",+ "connecting.html":+ "How to connect a product to a UHP server: discover the harness catalog, submit a "+ "task, stream progress, manage sessions, and take back files — client-side, over HTTP.",+ "serving.html":+ "How to serve UHP: the endpoints a conformant server answers, the order to build "+ "them in, and the conformance suite that proves the implementation works.",+ "examples.html":+ "Example implementations of the Unified Harness Protocol: servers that run harnesses "+ "behind the contract and clients that drive them, listed by pull request.","spec/index.html":"The complete UHP specification: architecture, lifecycle, harnesses, tasks, streaming, ""sessions, files, errors, security, and schema — versioned and testable.",@@ -134,55 +163,176 @@ CSS = """--ink:#111317; --muted:#6f6f78; --faint:#9696a0;--mono:"IBM Plex Mono",ui-monospace,SFMono-Regular,Menlo,monospace;--sans:"Inter",-apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif;- --sidebar:288px; --content:800px;+ --display:"Newsreader",Georgia,"Times New Roman",serif;+ --sidebar:264px; --content:760px; --toc:220px;+ --shell-max:1360px; --gutter:clamp(16px,3vw,40px);}++/* ── Implementations: compact list cards, not a wide table ──────────────────────────── */+.impl-actions{display:flex;gap:10px;flex-wrap:wrap;margin:18px 0 26px}+.impl-cta{display:inline-flex;align-items:center;min-height:38px;border-radius:9px;+ background:var(--brand);color:#fff;font-size:14px;font-weight:600;padding:0 16px}+.impl-cta:hover{background:var(--brand-deep);text-decoration:none;color:#fff}+.impl-crit{display:inline-flex;align-items:center;min-height:38px;border-radius:9px;+ border:1px solid var(--line);color:var(--ink);font-size:14px;font-weight:550;padding:0 15px}+.impl-crit:hover{border-color:var(--brand);text-decoration:none}+.impl-list{display:grid;gap:12px;margin:0 0 32px}+.impl-card{border:1px solid var(--line);border-radius:12px;padding:16px 18px;background:var(--surface)}+.impl-card:hover{border-color:var(--line-strong)}+.impl-head{display:flex;align-items:center;gap:12px}+.impl-head b{font-size:16px;font-weight:640}+.impl-head a{color:var(--ink)}+.impl-head a:hover{color:var(--brand)}+.role{margin-left:auto;font-size:11px;font-weight:660;letter-spacing:.03em;text-transform:uppercase;+ border-radius:6px;padding:3px 9px;white-space:nowrap}+.role-server{background:var(--brand-soft);color:var(--brand-deep)}+.role-client{background:var(--subtle);color:var(--muted)}+.impl-card p{margin:8px 0 0;color:var(--muted);font-size:14px;line-height:1.55}+.impl-card .impl-meta{margin-top:8px;font:500 12px/1 var(--mono);color:var(--faint)}+/* Drawer nav: primary links shown inside the mobile sidebar drawer only */+.drawernav{display:none;margin-bottom:22px;padding-bottom:18px;border-bottom:1px solid var(--line)}+.drawernav a{display:block;padding:8px 10px;border-radius:7px;color:var(--ink);+ font-size:14px;font-weight:550}+.drawernav a:hover{background:var(--subtle);text-decoration:none}++/* ── Theme menu ─────────────────────────────────────────────────────────────────────── */+.theme{position:relative;margin-left:16px}+.tbtn{display:inline-grid;place-items:center;width:34px;height:34px;border:1px solid var(--line);+ border-radius:9px;background:var(--subtle);color:var(--muted);cursor:pointer;padding:0}+.tbtn:hover{color:var(--ink);border-color:var(--ink)}+.tmenu{position:absolute;top:calc(100% + 6px);right:0;min-width:130px;padding:5px;+ border:1px solid var(--line);border-radius:10px;background:var(--surface);+ box-shadow:0 12px 34px -12px rgba(15,17,21,.4);z-index:60}+.tmenu button{display:flex;align-items:center;justify-content:space-between;width:100%;+ border:0;border-radius:7px;background:none;color:var(--ink);cursor:pointer;+ font:inherit;font-size:13px;padding:7px 10px}+.tmenu button:hover{background:var(--subtle)}+.tmenu button[aria-checked=true]::after{content:"\\2713";color:var(--brand);font-weight:700}++/* ── Search: a compact trigger in the header, a dialog over the page ─────────────────── */+.sbtn{display:inline-flex;align-items:center;gap:7px;min-height:34px;min-width:200px;+ border:1px solid var(--line);border-radius:9px;background:var(--subtle);+ color:var(--muted);cursor:pointer;font:inherit;font-size:13px;padding:0 11px}+.sbtn .sbtn-label{flex:1;text-align:left}+.sbtn:hover{color:var(--ink);border-color:var(--ink)}+.sbtn kbd{border:1px solid var(--line);border-radius:4px;font-family:inherit;font-size:11px;+ padding:1px 5px;color:var(--muted)}+#sdlg{position:fixed;inset:0;z-index:90}+#sdlg .sbackdrop{position:absolute;inset:0;background:rgba(15,17,21,.45)}+#sdlg .spanel{position:relative;width:min(640px,calc(100% - 32px));margin:9vh auto 0;+ border:1px solid var(--line);border-radius:12px;background:var(--surface);+ box-shadow:0 24px 70px -20px rgba(15,17,21,.5);padding:10px 10px 8px}+#sinput{width:100%;min-height:44px;border:0;outline:0;background:transparent;color:var(--ink);+ font:inherit;font-size:16px;padding:0 8px;border-bottom:1px solid var(--line)}+#sresults{list-style:none;margin:6px 0 0;padding:0;max-height:52vh;overflow-y:auto}+#sresults li{border-radius:8px;padding:9px 10px;cursor:pointer}+#sresults li.sel,#sresults li:hover{background:rgba(0,0,0,.05)}+#sresults .st{font-weight:600;font-size:14px}+#sresults .st small{color:var(--muted);font-weight:400;margin-left:8px}+#sresults .sx{color:var(--muted);font-size:13px;line-height:1.45;margin-top:2px}+#sresults mark{background:transparent;color:var(--ink);font-weight:650}+#sresults .snone{color:var(--muted);padding:12px 10px;font-size:14px}+.shint{margin:8px 2px 2px;color:var(--muted);font-size:12px}+.shint kbd{border:1px solid var(--line);border-radius:4px;padding:0 4px;font-family:inherit;font-size:11px}+@media (prefers-color-scheme:dark){:root{--canvas:#0d0e11;--surface:#131519;--subtle:#181a1f;--line:#24262d;--line-strong:#31343d;- --ink:#e9eaee;--muted:#9a9ba4;--faint:#6f7078;--brand-soft:#152246;}+ --ink:#e9eaee;--muted:#9a9ba4;--faint:#6f7078;+ --brand:#5b82ff;--brand-deep:#84a3ff;--brand-soft:#182444;}}:root[data-theme=dark]{--canvas:#0d0e11;--surface:#131519;--subtle:#181a1f;--line:#24262d;- --line-strong:#31343d;--ink:#e9eaee;--muted:#9a9ba4;--faint:#6f7078;--brand-soft:#152246;}+ --line-strong:#31343d;--ink:#e9eaee;--muted:#9a9ba4;--faint:#6f7078;+ --brand:#5b82ff;--brand-deep:#84a3ff;--brand-soft:#182444;}:root[data-theme=light]{--canvas:#fbfbfc;--surface:#fff;--subtle:#f7f7f9;--line:#e7e7eb;- --line-strong:#d8d8df;--ink:#111317;--muted:#6f6f78;--faint:#9696a0;--brand-soft:#eff3ff;}+ --line-strong:#d8d8df;--ink:#111317;--muted:#6f6f78;--faint:#9696a0;+ --brand:#285aff;--brand-deep:#1641d8;--brand-soft:#eff3ff;}+:root{color-scheme:light}+@media (prefers-color-scheme:dark){:root{color-scheme:dark}}+:root[data-theme=light]{color-scheme:light}+:root[data-theme=dark]{color-scheme:dark}*{box-sizing:border-box}body{margin:0;background:var(--canvas);color:var(--ink);font-family:var(--sans);- font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}+ font-size:16.5px;line-height:1.68;letter-spacing:-.003em;+ -webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}a{color:var(--brand);text-decoration:none}a:hover{text-decoration:underline}header.top{position:sticky;top:0;z-index:30;background:var(--surface);- border-bottom:1px solid var(--line);display:flex;align-items:center;gap:16px;- padding:0 20px;height:56px}+ border-bottom:1px solid var(--line);height:56px}+.header-inner{display:flex;align-items:center;gap:16px;height:100%;+ width:min(100%,var(--shell-max));margin:0 auto;padding:0 var(--gutter);box-sizing:border-box}.brand{display:flex;align-items:center;gap:10px;font-weight:680;color:var(--ink);letter-spacing:-.01em}.brand .mark{width:22px;height:22px;border-radius:6px;background:var(--brand);color:#fff;display:grid;place-items:center;font:600 11px/1 var(--mono)}.brand .ver{font:500 11px/1 var(--mono);color:var(--muted);background:var(--subtle);border:1px solid var(--line);border-radius:999px;padding:4px 8px}+.ver{position:relative;margin-left:2px}+.verpill{display:inline-flex;align-items:center;gap:6px;cursor:pointer;+ font:500 11.5px/1 var(--mono);color:var(--muted);background:var(--subtle);+ border:1px solid var(--line);border-radius:999px;padding:5px 9px 5px 10px;white-space:nowrap}+.verpill:hover{color:var(--ink);border-color:var(--line-strong)}+.verpill[aria-expanded=true]{color:var(--ink);border-color:var(--ink)}+.verpill .dot{width:6px;height:6px;border-radius:50%;background:#16a34a;flex:none;+ box-shadow:0 0 0 3px rgba(22,163,74,.15)}+.verpill .vchev{opacity:.6;margin-left:1px}+.vmenu{position:absolute;top:calc(100% + 6px);left:0;min-width:190px;padding:5px;+ border:1px solid var(--line);border-radius:10px;background:var(--surface);+ box-shadow:0 12px 34px -12px rgba(15,17,21,.4);z-index:60}+.vmenu-h{margin:4px 8px 5px;font:660 10px/1 var(--sans);letter-spacing:.07em;+ text-transform:uppercase;color:var(--faint)}+.vmenu a{display:flex;align-items:center;gap:8px;border-radius:7px;padding:7px 9px;+ color:var(--ink);font:500 13px/1 var(--mono)}+.vmenu a:hover{background:var(--subtle);text-decoration:none}+.vmenu .vname{flex:1}+.vmenu .vtag{font:600 10px/1 var(--sans);letter-spacing:.03em;text-transform:uppercase;+ color:#16a34a;background:rgba(22,163,74,.12);border-radius:4px;padding:3px 6px}.top .spacer{flex:1}.top nav a{color:var(--muted);font-size:14px;font-weight:520;margin-left:18px}.top nav a:hover{color:var(--ink);text-decoration:none}#menu{display:none;background:none;border:1px solid var(--line);border-radius:8px;color:var(--ink);font-size:18px;line-height:1;padding:6px 10px;cursor:pointer}-.shell{display:grid;grid-template-columns:var(--sidebar) minmax(0,1fr);align-items:start;- max-width:1320px;margin:0 auto}+.shell{display:grid;grid-template-columns:var(--sidebar) minmax(0,1fr) var(--toc);align-items:start;+ width:min(100%,var(--shell-max));margin:0 auto;padding:0 var(--gutter);box-sizing:border-box}+.shell.no-toc{grid-template-columns:var(--sidebar) minmax(0,1fr)}+.toc{position:sticky;top:56px;max-height:calc(100vh - 56px);overflow-y:auto;+ overscroll-behavior:contain;padding:40px 16px 48px 12px;scrollbar-width:thin}+.toc .toc-h{margin:0 0 8px;padding:0 10px;font:650 11px/1 var(--mono);+ letter-spacing:.02em;text-transform:uppercase;color:var(--faint)}+.toc ul{display:grid;gap:1px;margin:0;padding:0;list-style:none}+.toc a{display:flex;align-items:center;min-height:31px;padding:5px 10px;border-radius:7px;+ color:var(--muted);font-size:13px;line-height:1.35;text-decoration:none}+.toc a.lvl3{padding-left:22px;font-size:12.5px;color:var(--faint)}+.toc a:hover{color:var(--ink);background:var(--subtle)}+.toc a[aria-current=location]{color:var(--ink);font-weight:660}+.toc a.lvl3[aria-current=location]{color:var(--ink)}aside{position:sticky;top:56px;height:calc(100vh - 56px);overflow-y:auto;- border-right:1px solid var(--line);padding:24px 16px 48px}+ border-right:1px solid var(--line);padding:24px 20px 48px 0}+.verbadge{display:flex;align-items:center;gap:8px;margin:0 6px 22px;padding:9px 11px;+ border:1px solid var(--line);border-radius:9px;background:var(--subtle)}+.verbadge .verlabel{font-size:11px;font-weight:660;letter-spacing:.07em;text-transform:uppercase;color:var(--faint)}+.verbadge .vertag{display:flex;align-items:center;gap:7px;margin-left:auto;+ font:600 12px/1 var(--mono);color:var(--ink)}+.verbadge .vertag em{font:500 10px/1 var(--sans);font-style:normal;letter-spacing:.03em;+ text-transform:uppercase;color:#16a34a;background:rgba(22,163,74,.12);border-radius:4px;padding:3px 6px}+.verbadge .dot{width:7px;height:7px;border-radius:50%;background:#16a34a;flex:none;+ box-shadow:0 0 0 3px rgba(22,163,74,.15)}aside .group{margin-bottom:22px}aside .group h4{margin:0 0 8px;padding:0 10px;font-size:11px;font-weight:660;letter-spacing:.07em;text-transform:uppercase;color:var(--faint)}aside a{display:block;padding:6px 10px;border-radius:7px;color:var(--muted);font-size:14px;line-height:1.4}aside a:hover{background:var(--subtle);color:var(--ink);text-decoration:none}-aside a.active{background:var(--brand-soft);color:var(--brand-deep);font-weight:600}+aside a.active{background:var(--brand-soft);color:var(--brand-deep);font-weight:600;box-shadow:inset 2px 0 0 var(--brand)}main{padding:40px 40px 96px;min-width:0}article{max-width:var(--content)}-article h1{font-size:34px;line-height:1.2;letter-spacing:-.02em;margin:0 0 8px;font-weight:700}-article h2{font-size:22px;line-height:1.3;letter-spacing:-.01em;margin:44px 0 12px;- font-weight:660;padding-top:20px;border-top:1px solid var(--line)}-article h3{font-size:17px;margin:28px 0 8px;font-weight:640}+article h1{font-family:var(--display);font-size:40px;line-height:1.12;letter-spacing:-.01em;+ margin:0 0 10px;font-weight:600}+article h2{font-family:var(--display);font-size:26px;line-height:1.25;letter-spacing:-.005em;+ margin:46px 0 14px;font-weight:600;padding-top:22px;border-top:1px solid var(--line)}+article h3{font-size:17px;margin:30px 0 8px;font-weight:640;letter-spacing:-.005em}article p{margin:0 0 16px;color:var(--ink)}article ul,article ol{margin:0 0 16px;padding-left:22px}article li{margin:5px 0}@@ -209,15 +359,38 @@ blockquote p:last-child{margin-bottom:0}hr{border:0;border-top:1px solid var(--line);margin:32px 0}.hero{padding:56px 0 8px;max-width:var(--content)}-.hero h1{font-size:44px;letter-spacing:-.03em;margin-bottom:14px}+.hero h1{font-family:var(--display);font-size:52px;line-height:1.06;letter-spacing:-.015em;font-weight:600;margin-bottom:16px}.hero .lede{font-size:19px;color:var(--muted);line-height:1.55}-.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px;- margin:28px 0 8px;max-width:var(--content)}-.card{display:block;border:1px solid var(--line);border-radius:12px;padding:18px;- background:var(--surface);color:var(--ink)}-.card:hover{border-color:var(--brand);text-decoration:none}-.card b{display:block;font-size:15px;margin-bottom:4px}-.card span{color:var(--muted);font-size:13.5px;line-height:1.5}+/* ── Homepage role flow: Client -> UHP server -> Harness (rendering of architecture Roles) ── */+.quicklinks{display:grid;grid-template-columns:repeat(2,1fr);gap:12px;margin:8px 0 40px;max-width:var(--content)}+@media (max-width:640px){.quicklinks{grid-template-columns:1fr}}+.home-h2{font-family:var(--display);font-size:20px;font-weight:600;margin:38px 0 4px;letter-spacing:-.005em}+.role-flow{display:flex;align-items:stretch;flex-wrap:wrap;gap:10px;margin:30px 0 14px}+.role-flow .node{display:flex;flex-direction:column;justify-content:center;gap:2px;+ border:1px solid var(--line);border-radius:12px;padding:12px 16px;background:var(--surface);min-width:0}+.role-flow .node b{font-size:14.5px;font-weight:640}+.role-flow .node small{color:var(--muted);font-size:12px}+.role-flow .arrow{align-self:center;color:var(--faint);flex:none}+.role-note{margin:0 0 6px;color:var(--muted);font-size:14px;max-width:var(--content)}+.card-badge{align-self:flex-start;font-size:11px;font-weight:660;letter-spacing:.02em;+ border-radius:6px;padding:3px 9px;margin-bottom:10px;background:var(--brand-soft);color:var(--brand-deep)}+.card-badge-quiet{background:var(--subtle);color:var(--muted)}+@media (max-width:560px){.role-flow .arrow{transform:rotate(90deg)}.role-flow{flex-direction:column}}+.cards-primary{display:grid;grid-template-columns:1fr 1fr;gap:16px;margin:30px 0 14px;max-width:var(--content)}+.card-lg{display:flex;flex-direction:column;border:1px solid var(--line);border-radius:14px;+ padding:22px;background:var(--surface);color:var(--ink);transition:border-color .15s,box-shadow .15s}+.card-lg:hover{border-color:var(--brand);text-decoration:none;box-shadow:0 6px 24px -14px var(--brand)}+.card-lg svg{color:var(--brand);margin-bottom:12px}+.card-lg b{font-size:17px;font-weight:640;margin-bottom:6px}+.card-lg span{color:var(--muted);font-size:14px;line-height:1.55;flex:1}+.card-lg em{margin-top:14px;font-style:normal;font-size:13.5px;font-weight:600;color:var(--brand)}+.cards-secondary{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:0 0 8px;max-width:var(--content)}+.card-sm{display:block;border:1px solid var(--line);border-radius:11px;padding:14px 16px;+ background:transparent;color:var(--ink)}+.card-sm:hover{border-color:var(--brand);text-decoration:none;background:var(--subtle)}+.card-sm b{display:block;font-size:14.5px;font-weight:620;margin-bottom:3px}+.card-sm span{color:var(--muted);font-size:13px;line-height:1.5}+@media (max-width:640px){.cards-primary,.cards-secondary{grid-template-columns:1fr}}.pager{display:flex;justify-content:space-between;gap:16px;margin-top:56px;padding-top:20px;border-top:1px solid var(--line);max-width:var(--content)}@@ -225,26 +398,37 @@ hr{border:0;border-top:1px solid var(--line);margin:32px 0}footer{border-top:1px solid var(--line);margin-top:64px;padding:24px 0 0;color:var(--faint);font-size:13px;max-width:var(--content)}-@media (max-width:900px){- .shell{grid-template-columns:1fr}- aside{position:fixed;inset:56px auto 0 0;width:280px;background:var(--surface);+/* ── Tablet/below: sidebar becomes a drawer, top nav collapses into the drawer ───────── */+@media (max-width:960px){+ .shell,.shell.no-toc{grid-template-columns:1fr}+ .toc{display:none}+ aside{position:fixed;inset:56px auto 0 0;width:min(300px,84vw);background:var(--surface);transform:translateX(-100%);transition:transform .18s ease;z-index:25;height:calc(100vh - 56px)}aside.open{transform:none;box-shadow:0 12px 40px #0000001f}- #menu{display:block}+ #menu{display:grid;place-items:center}main{padding:28px 20px 72px}+ /* Move the primary nav links into the drawer instead of dropping them entirely. */.top nav{display:none}- article h1,.hero h1{font-size:28px}+ aside .drawernav{display:block}+ .ver{display:none}+ /* Search shrinks to an icon-only button — same target, no dead label space. */+ .sbtn{min-width:0;width:34px;padding:0;justify-content:center}+ .sbtn-label,.sbtn kbd{display:none}+ article h1{font-size:30px}+ .hero h1{font-size:34px}.hero{padding:32px 0 4px}}+/* ── Phone: keep the wordmark text (readable), tighten spacing ───────────────────────── */@media (max-width:560px){- /* The wordmark and the version chip together are wider than a phone, and wrapping them broke- the fixed-height bar. Collapse to the mark, which is what the header is for at this width. */- header.top{gap:10px;padding:0 14px}- .brand{font-size:0}- .brand .mark{font-size:11px}- .brand .ver,header.top>.ver{display:none}+ header.top{gap:10px;padding:0 12px}+ .brand{font-size:15px;gap:8px}+ .theme{margin-left:8px}main{padding:22px 16px 64px}}+/* ── Very narrow: drop the wordmark text, keep the mark ──────────────────────────────── */+@media (max-width:400px){+ .brand span:not(.mark){position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0)}+}"""JS = """@@ -252,48 +436,220 @@ JS = """var b=document.getElementById('menu'),s=document.querySelector('aside');if(b&&s){b.addEventListener('click',function(){s.classList.toggle('open');});s.addEventListener('click',function(e){if(e.target.tagName==='A')s.classList.remove('open');});}++ // Theme: Auto / Light / Dark, persisted to localStorage; Auto defers to the OS media query.+ var tb=document.getElementById('tbtn'),tm=tb&&tb.parentElement.querySelector('.tmenu');+ if(tb&&tm){+ function cur(){try{return localStorage.getItem('theme')||'auto';}catch(e){return 'auto';}}+ function mark(){var v=cur();tm.querySelectorAll('[data-theme-set]').forEach(function(x){+ x.setAttribute('aria-checked', x.getAttribute('data-theme-set')===v?'true':'false');});}+ function set(v){try{ if(v==='auto'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme;}+ else{localStorage.setItem('theme',v);document.documentElement.dataset.theme=v;} }catch(e){}+ mark();}+ function openM(o){tm.hidden=!o;tb.setAttribute('aria-expanded',o?'true':'false');if(o)mark();}+ tb.addEventListener('click',function(e){e.stopPropagation();openM(tm.hidden);});+ tm.querySelectorAll('[data-theme-set]').forEach(function(x){+ x.addEventListener('click',function(){set(x.getAttribute('data-theme-set'));openM(false);});});+ document.addEventListener('click',function(){if(!tm.hidden)openM(false);});+ document.addEventListener('keydown',function(e){if(e.key==='Escape'&&!tm.hidden)openM(false);});+ mark();+ }++ // Version dropdown: toggle the menu, close on outside click or Escape.+ var vb=document.getElementById('vbtn'),vm=vb&&vb.parentElement.querySelector('.vmenu');+ if(vb&&vm){+ function vopen(o){vm.hidden=!o;vb.setAttribute('aria-expanded',o?'true':'false');}+ vb.addEventListener('click',function(e){e.stopPropagation();vopen(vm.hidden);});+ document.addEventListener('click',function(){if(!vm.hidden)vopen(false);});+ document.addEventListener('keydown',function(e){if(e.key==='Escape'&&!vm.hidden)vopen(false);});+ }++ // On-this-page scroll-spy: mark the last heading whose top has crossed an anchor line 32% down+ // the viewport (capped at 220px). Throttled through requestAnimationFrame; forces the final item+ // when the page is scrolled to the bottom so a short last section still lights up.+ var toc=document.querySelector('.toc');+ if(toc){+ var tlinks=[].slice.call(toc.querySelectorAll('a[href^="#"]'));+ var tids=tlinks.map(function(a){return decodeURIComponent(a.getAttribute('href').slice(1));});+ var theads=tids.map(function(id){return document.getElementById(id);});+ var tcur=null,tsched=false;+ function tpick(){+ var anchor=window.scrollY+Math.min(window.innerHeight*0.32,220),id=tids[0]||null;+ for(var i=0;i<theads.length;i++){ var h=theads[i]; if(!h)continue;+ if(h.getBoundingClientRect().top+window.scrollY<=anchor){id=tids[i];}else{break;} }+ if(tids.length&&window.scrollY+window.innerHeight>=document.documentElement.scrollHeight-4)+ id=tids[tids.length-1];+ if(id!==tcur){ tcur=id;+ tlinks.forEach(function(a){+ if(decodeURIComponent(a.getAttribute('href').slice(1))===id)a.setAttribute('aria-current','location');+ else a.removeAttribute('aria-current'); }); }+ }+ function tspy(){ if(tsched)return; tsched=true;+ requestAnimationFrame(function(){tsched=false;tpick();}); }+ window.addEventListener('scroll',tspy,{passive:true});+ window.addEventListener('resize',tspy);+ tpick();+ }++ var dlg=document.getElementById('sdlg'),inp=document.getElementById('sinput'),+ res=document.getElementById('sresults'),btn=document.getElementById('sbtn');+ if(!dlg||!inp||!btn)return;+ var root=inp.getAttribute('data-root')||'',idx=null,sel=-1,rows=[];++ function load(cb){ if(idx){cb();return;}+ fetch(root+'search-index.json').then(function(r){return r.json();})+ .then(function(d){idx=d;cb();}).catch(function(){idx=[];cb();}); }+ function open_(){ dlg.hidden=false; load(function(){inp.focus();run();}); }+ function close_(){ dlg.hidden=true; sel=-1; }+ function esc(t){return t.replace(/[&<>]/g,function(c){return{'&':'&','<':'<','>':'>'}[c];});}+ function mark(t,q){ if(!q)return esc(t);+ var i=t.toLowerCase().indexOf(q.toLowerCase()); if(i<0)return esc(t);+ return esc(t.slice(0,i))+'<mark>'+esc(t.slice(i,i+q.length))+'</mark>'+esc(t.slice(i+q.length)); }+ function excerpt(body,q){ var i=body.toLowerCase().indexOf(q.toLowerCase());+ if(i<0)return esc(body.slice(0,120));+ var a=Math.max(0,i-40); return (a>0?'…':'')+mark(body.slice(a,i+q.length+80),q)+'…'; }+ function run(){ var q=inp.value.trim(); res.innerHTML=''; sel=-1; rows=[];+ if(!idx){return;}+ var out=[];+ if(q){ var ql=q.toLowerCase();+ for(var i=0;i<idx.length;i++){ var p=idx[i];+ var t=(p.title+' '+p.body).toLowerCase(); var k=t.indexOf(ql);+ if(k>=0){ out.push([p, (p.title.toLowerCase().indexOf(ql)>=0?0:1), k]); } }+ out.sort(function(a,b){return a[1]-b[1]||a[2]-b[2];});+ out=out.slice(0,8);+ }+ if(q && !out.length){ res.innerHTML='<li class="snone">No matches for “'+esc(q)+'”</li>'; return; }+ out.forEach(function(e){ var p=e[0]; var li=document.createElement('li');+ li.innerHTML='<div class="st">'+mark(p.title,q)+'<small>'+esc(p.section)+'</small></div>'++ '<div class="sx">'+excerpt(p.body,q)+'</div>';+ li.addEventListener('click',function(){location.href=root+p.url;});+ res.appendChild(li); rows.push(p); });+ }+ function move(d){ var items=res.querySelectorAll('li'); if(!items.length)return;+ if(sel>=0)items[sel].classList.remove('sel');+ sel=(sel+d+items.length)%items.length; items[sel].classList.add('sel');+ items[sel].scrollIntoView({block:'nearest'}); }++ btn.addEventListener('click',open_);+ dlg.querySelector('.sbackdrop').addEventListener('click',close_);+ inp.addEventListener('input',run);+ document.addEventListener('keydown',function(e){+ if((e.metaKey||e.ctrlKey)&&e.key.toLowerCase()==='k'){e.preventDefault();dlg.hidden?open_():close_();return;}+ if(dlg.hidden)return;+ if(e.key==='Escape'){close_();}+ else if(e.key==='ArrowDown'){e.preventDefault();move(1);}+ else if(e.key==='ArrowUp'){e.preventDefault();move(-1);}+ else if(e.key==='Enter'&&sel>=0&&rows[sel]){location.href=root+rows[sel].url;} });})();"""-def render_markdown(text: str) -> str:+def render_markdown(text: str):md = markdown.Markdown(extensions=["tables", "fenced_code", "toc", "attr_list", "sane_lists"])out = md.convert(text)# Tables must scroll inside their own box rather than widening the page on a phone.out = re.sub(r"<table>", '<div class="table-wrap"><table>', out)out = re.sub(r"</table>", "</table></div>", out)- return out+ # Collect h2/h3 for the on-this-page rail; ids come from the toc extension.+ toc = [(int(m.group(1)), m.group(2), re.sub("<[^>]+>", "", m.group(3)))+ for m in re.finditer(r'<h([23]) id="([^"]+)">(.*?)</h[23]>', out, re.S)]+ return out, toc+++def toc_html(toc):+ if len(toc) < 2:+ return ""+ items = "".join(+ f'<li><a href="#{i}" class="lvl{lvl}">{html.escape(t)}</a></li>' for lvl, i, t in toc)+ return (f'<nav class="toc" aria-label="On this page"><p class="toc-h">On this page</p>'+ f'<ul>{items}</ul></nav>')def rewrite_links(html_text: str, depth: int) -> str:"""Point in-repo markdown links at their built pages (root-absolute, see url_for)."""up = "/"- samedir = "/spec/" if depth else "/"+ samedir = f"/spec/{VERSION}/" if depth else "/"pairs = [- (rf'href="(?:\.\./)*versions/{VERSION}/([a-z]+)\.md"', rf'href="{up}spec/\1"'),+ # The spec overview is served at /spec/<version> (index stripped), so map it before the+ # general chapter rule, which would otherwise turn index.md into …/index (a 404).+ (rf'href="(?:\.\./)*versions/{VERSION}/index\.md"', rf'href="{up}spec/{VERSION}"'),+ (rf'href="(?:\.\./)*versions/{VERSION}/([a-z]+)\.md"', rf'href="{up}spec/{VERSION}/\1"'),(r'href="(?:\.\./)*README\.md"', f'href="{url_for("index.html", up)}"'),(r'href="(?:\.\./)*VERSIONING\.md"', f'href="{up}versioning"'),(r'href="(?:\.\./)*GOVERNANCE\.md"', f'href="{up}governance"'),(r'href="(?:\.\./)*CHANGELOG\.md"', f'href="{up}changelog"'),+ (r'href="(?:\.\./)*SERVING\.md"', f'href="{up}serving"'),+ (r'href="(?:\.\./)*CONNECTING\.md"', f'href="{up}connecting"'),+ (r'href="(?:\.\./)*IMPLEMENTATIONS\.md"', f'href="{up}examples"'),+ (r'href="(?:\.\./)*conformance/README\.md"', f'href="{up}conformance"'),(r'href="(?:\.\./)*conformance/?"', f'href="{up}conformance"'),(r'href="(?:\.\./)*\.\./conformance/"', f'href="{up}conformance"'),(r'href="([a-z]+)\.md"', rf'href="{samedir}\1"'),(r'href="(?:\.\./)*schema/([^"/]+)"',rf'href="{up}schema/\1"'), # the machine-readable files ship with the site- (r'href="(?:\.\./)*schema/"', f'href="{up}spec/schema"'),- (r'href="versions/2026-08-11/"', f'href="{up}spec/"'),+ (r'href="(?:\.\./)*schema/"', f'href="{up}spec/{VERSION}/schema"'),+ (rf'href="versions/{VERSION}/"', f'href="{up}spec/{VERSION}"'),# An anchor into another document's section: keep the section, retarget the document.(r'href="(?:\.\./)*VERSIONING\.md#([^"]+)"', rf'href="{up}versioning#\1"'),(r'href="(?:\.\./)*GOVERNANCE\.md#([^"]+)"', rf'href="{up}governance#\1"'),(r'href="(?:\.\./)*README\.md#([^"]+)"', rf'href="{url_for("index.html", up)}#\1"'),(rf'href="(?:\.\./)*versions/{VERSION}/([a-z]+)\.md#([^"]+)"',- rf'href="{up}spec/\1#\2"'),+ rf'href="{up}spec/{VERSION}/\1#\2"'),]for pat, repl in pairs:html_text = re.sub(pat, repl, html_text)return html_text+def redirect_html(target: str, label: str) -> str:+ """A tiny bounce page. /spec has no version of its own — it forwards to the latest, so a typed+ or cited /spec always lands on the current specification without duplicating its content. The+ canonical points at the dated page, so crawlers index that, not this."""+ return (+ f'<!doctype html><html lang="en"><head><meta charset="utf-8">'+ f'<meta name="viewport" content="width=device-width,initial-scale=1">'+ f'<meta http-equiv="refresh" content="0; url={target}">'+ f'<link rel="canonical" href="https://{SITE}{target}">'+ f'<meta name="robots" content="noindex,follow">'+ f'<title>{html.escape(label)} · Unified Harness Protocol</title></head>'+ f'<body style="font-family:system-ui,sans-serif;padding:2rem">'+ f'Redirecting to the <a href="{target}">current specification</a>…</body></html>')+++def ver_menu_html() -> str:+ """The version dropdown's rows: each published version links to its own spec overview, latest+ marked. With one version it is a one-row menu; it grows by prepending to VERSIONS, and the+ per-version URLs already exist, so no page has to move when a version is added."""+ rows = []+ for i, v in enumerate(VERSIONS):+ tag = '<span class="vtag">latest</span>' if i == 0 else ""+ rows.append(f'<a role="menuitem" href="/spec/{v}"><span class="vname">{v}</span>{tag}</a>')+ return "".join(rows)+++def desc_key(path: str) -> str:+ """Map a built page path to its description key. Spec pages carry the version in their path+ (spec/2026-08-11/architecture.html) but their descriptions are authored per chapter, version-+ independent (spec/architecture.html) — one description serves every version of a chapter."""+ return re.sub(rf"^spec/{re.escape(VERSION)}/", "spec/", path)+++def section_of(path):+ for group, items in NAV:+ for pp, _, _ in items:+ if pp == path:+ return group+ return "Background"+++def plain_text(html_body: str) -> str:+ """Body HTML to a single line of searchable text."""+ t = re.sub(r"<(script|style)[^>]*>.*?</\1>", " ", html_body, flags=re.S)+ t = re.sub(r"<[^>]+>", " ", t)+ t = html.unescape(t)+ return re.sub(r"\s+", " ", t).strip()++def flat_pages():return [(path, title, src) for _, items in NAV for path, title, src in items]@@ -320,7 +676,12 @@ def url_for(path: str, up: str = "") -> str:def sidebar(current: str, depth: int) -> str:up = "../" * depth- out = []+ out = [f'<nav class="drawernav">'+ f'<a href="{url_for(f"spec/{VERSION}/index.html", up)}">Specification</a>'+ f'<a href="{url_for("conformance.html", up)}">Conformance</a>'+ f'<a href="{url_for("governance.html", up)}">Governance</a>'+ f'<a href="https://github.com/HarnessRouter/harnessrouter">GitHub</a>'+ f'</nav>']for group, items in NAV:out.append(f'<div class="group"><h4>{html.escape(group)}</h4>')for path, title, _ in items:@@ -330,8 +691,11 @@ def sidebar(current: str, depth: int) -> str:return "\n".join(out)-def page(current: str, title: str, body: str, depth: int, hero: str = "") -> str:+def page(current: str, title: str, body: str, depth: int, hero: str = "", toc: str = "") -> str:up = "../" * depth+ # On a dated spec page the pill names that page's version; elsewhere it names the latest.+ page_ver = next((v for v in VERSIONS if current.startswith(f"spec/{v}/")), VERSION)+ shell_wide = "" if toc else " no-toc"pages = flat_pages()idx = next((i for i, (p, _, _) in enumerate(pages) if p == current), -1)prev_ = pages[idx - 1] if idx > 0 else None@@ -348,27 +712,62 @@ def page(current: str, title: str, body: str, depth: int, hero: str = "") -> str<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>{html.escape(title)} · Unified Harness Protocol</title>-<meta name="description" content="{html.escape(DESCRIPTIONS[current])}">+<meta name="description" content="{html.escape(DESCRIPTIONS[desc_key(current)])}"><link rel="canonical" href="https://{SITE}/{url_for(current).lstrip("./")}"><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;450;500;600;700&family=Newsreader:opsz,[email protected],500;6..72,600&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">+<script>try{{var t=localStorage.getItem("theme");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t;}}catch(e){{}}</script><style>{CSS}</style></head><body><header class="top">+ <div class="header-inner"><button id="menu" aria-label="Toggle navigation">☰</button>- <a class="brand" href="{url_for("index.html", up)}"><span class="mark">U</span> Unified Harness Protocol</a>- <span class="ver">{VERSION}</span>+ <a class="brand" href="{url_for("index.html", up)}"><span class="mark">U</span><span>Unified Harness Protocol</span></a>+ <div class="ver" id="ver">+ <button id="vbtn" class="verpill" aria-haspopup="menu" aria-expanded="false" aria-label="Specification version">+ <span class="dot"></span><span class="vcur">{page_ver}</span>+ <svg class="vchev" viewBox="0 0 24 24" width="11" height="11" fill="none" stroke="currentColor" stroke-width="2.4" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg>+ </button>+ <div class="vmenu" role="menu" hidden>+ <p class="vmenu-h">Specification version</p>+ {ver_menu_html()}+ </div>+ </div>+ <button id="sbtn" class="sbtn" aria-label="Search the site" aria-haspopup="dialog">+ <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.8-3.8"/></svg>+ <span class="sbtn-label">Search…</span><kbd>⌘K</kbd>+ </button><span class="spacer"></span><nav>- <a href="{url_for("spec/index.html", up)}">Specification</a>+ <a href="{url_for(f"spec/{VERSION}/index.html", up)}">Specification</a><a href="{url_for("conformance.html", up)}">Conformance</a><a href="{url_for("governance.html", up)}">Governance</a><a href="https://github.com/HarnessRouter/harnessrouter">GitHub</a></nav>+ <div class="theme" id="theme">+ <button id="tbtn" class="tbtn" aria-label="Theme" aria-haspopup="menu" aria-expanded="false">+ <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2M2 12h2m16 0h2m-3.5-6.5-1.4 1.4M6.9 17.1l-1.4 1.4m0-13 1.4 1.4m10.2 10.2 1.4 1.4"/></svg>+ </button>+ <div class="tmenu" role="menu" hidden>+ <button role="menuitemradio" data-theme-set="auto">Auto</button>+ <button role="menuitemradio" data-theme-set="light">Light</button>+ <button role="menuitemradio" data-theme-set="dark">Dark</button>+ </div>+ </div>+ </div></header>-<div class="shell">+<div id="sdlg" hidden role="dialog" aria-modal="true" aria-label="Search">+ <div class="sbackdrop"></div>+ <div class="spanel">+ <input id="sinput" type="search" placeholder="Search the specification…"+ autocomplete="off" spellcheck="false" data-root="{up}">+ <ol id="sresults" role="listbox"></ol>+ <p class="shint"><kbd>↑</kbd><kbd>↓</kbd> navigate · <kbd>Enter</kbd> open · <kbd>Esc</kbd> close</p>+ </div>+</div>+<div class="shell{shell_wide}"><aside>{sidebar(current, depth)}</aside><main>{hero}@@ -378,9 +777,10 @@ def page(current: str, title: str, body: str, depth: int, hero: str = "") -> strUnified Harness Protocol {VERSION} · Apache-2.0 ·defined and maintained in the<a href="https://github.com/HarnessRouter/harnessrouter">HarnessRouter open-source repository</a>.- The standard can be implemented without HarnessRouter Cloud.+ The standard can be implemented independently of any hosted service.</footer></main>+ {toc}</div><script>{JS}</script></body>@@ -388,6 +788,73 @@ def page(current: str, title: str, body: str, depth: int, hero: str = "") -> str"""+def check_links(dist: pathlib.Path) -> None:+ """Fail the build on any broken same-site link, so a dead cross-link can never reach deploy.++ A standards site's URLs are a contract: pages get cited, and a link that 404s — or an anchor+ that points at a heading that was renamed — is a defect in the standard's presentation. This+ runs on every build, local and CI, so the check lives with the generator and cannot drift from+ a separate linter. Across all output HTML it verifies three things for every same-site `href`+ and `src`: no in-repo `.md` link leaked through link rewriting; the path resolves to a file the+ build produced (honouring cleanUrls — /foo is served by foo.html or foo/index.html, and+ /schema/x.yaml is an exact file); and any `#fragment` matches an id on the target page. External+ schemes (http, mailto, tel, data, javascript) are out of scope.+ """+ import urllib.parse+ assets = {"/" + p.relative_to(dist).as_posix() for p in dist.rglob("*") if p.is_file()}+ id_cache: dict = {}++ def file_for(path_url: str):+ """The built file that serves a cleanUrls path, or None."""+ if path_url in assets:+ return path_url # exact file (e.g. a schema asset)+ if path_url == "/":+ return "/index.html" if "/index.html" in assets else None+ for c in (path_url + ".html", path_url.rstrip("/") + "/index.html"):+ if c in assets:+ return c+ return None++ def ids_of(file_rel: str):+ if file_rel not in id_cache:+ id_cache[file_rel] = set(+ re.findall(r'id="([^"]+)"', (dist / file_rel.lstrip("/")).read_text()))+ return id_cache[file_rel]++ def page_url(rel: str) -> str:+ if rel == "/index.html":+ return "/"+ if rel.endswith("/index.html"):+ return rel[: -len("index.html")] # ".../index.html" -> ".../"+ return rel[:-5] if rel.endswith(".html") else rel++ external = ("http://", "https://", "mailto:", "tel:", "data:", "javascript:")+ bare_md, broken, bad_frag = [], [], []+ for p in sorted(dist.rglob("*.html")):+ rel = "/" + p.relative_to(dist).as_posix()+ base = page_url(rel)+ for _attr, href in re.findall(r'\b(href|src)="([^"]+)"', p.read_text()):+ if href.startswith(external):+ continue # github .md blobs etc. are not ours+ if href.endswith(".md") or ".md#" in href:+ bare_md.append((rel, href))+ continue+ u = urllib.parse.urlsplit(href)+ if not u.path: # a same-page "#anchor"+ if u.fragment and u.fragment not in ids_of(rel):+ bad_frag.append((rel, href))+ continue+ path = u.path if u.path.startswith("/") else urllib.parse.urljoin(base, u.path)+ f = file_for(urllib.parse.unquote(path))+ if f is None:+ broken.append((rel, href))+ elif u.fragment and u.fragment not in ids_of(f):+ bad_frag.append((rel, href))+ assert not bare_md, f"in-repo .md links leaked into the build (link rewriting missed them): {bare_md[:10]}"+ assert not broken, f"internal links resolve to no built page: {broken[:15]}"+ assert not bad_frag, f"internal links point to a missing #anchor: {bad_frag[:15]}"++def check_count() -> int:"""How many checks the conformance suite actually registers.@@ -403,20 +870,11 @@ def check_count() -> int:HERO = f"""-<div class="hero">- <h1>The Unified Harness Protocol</h1>- <p class="lede">One open standard for driving complete agent harnesses — Codex, Claude Code,- Hermes, and whatever ships next — so a product integrates once instead of once per harness.</p>-</div>-<div class="cards">- <a class="card" href="spec/"><b>Read the specification</b>- <span>Normative, versioned, and testable. Ten chapters from architecture to errors.</span></a>- <a class="card" href="conformance"><b>Run the conformance suite</b>- <span>{check_count()} checks across three classes. Passing it is the only conformance claim that means anything.</span></a>- <a class="card" href="spec/schema"><b>Generate a client</b>- <span>OpenAPI 3.1 and JSON Schema 2020-12, published per version.</span></a>- <a class="card" href="governance"><b>Propose a change</b>- <span>Prose first. Spec, reference implementation and suite move together.</span></a>+<div class="quicklinks">+ <a class="card-sm" href="/spec/{VERSION}"><b>Specification</b><span>The normative contract — ten versioned chapters.</span></a>+ <a class="card-sm" href="/conformance"><b>Conformance suite</b><span>{check_count()} runnable checks; the definition of conformant.</span></a>+ <a class="card-sm" href="/connecting"><b>Implement a client</b><span>Discovery, tasks, events, artifacts — over HTTP.</span></a>+ <a class="card-sm" href="/serving"><b>Implement a server</b><span>The operations a server answers behind the contract.</span></a></div>"""@@ -424,7 +882,7 @@ HERO = f"""def build() -> int:# The description manifest must cover every page, one page per description, at snippet length.# Asserted here so a new page cannot ship with the homepage's description by accident.- all_pages = {p for p, _, _ in flat_pages() + EXTRA}+ all_pages = {desc_key(p) for p, _, _ in flat_pages() + EXTRA}assert all_pages == set(DESCRIPTIONS), (f"description manifest out of sync — missing: {sorted(all_pages - set(DESCRIPTIONS))}, "f"stale: {sorted(set(DESCRIPTIONS) - all_pages)}")@@ -432,24 +890,56 @@ def build() -> int:bad_len = {p: len(d) for p, d in DESCRIPTIONS.items() if not 100 <= len(d) <= 170}assert not bad_len, f"meta descriptions outside the 100-170 char band: {bad_len}"+ # Every version the dropdown offers must have a frozen source tree — a version is an address to+ # snapshotted markdown under protocol/versions/<date>/, never a re-render of the current text.+ missing_src = [v for v in VERSIONS if not (ROOT / "versions" / v).is_dir()]+ assert not missing_src, (+ f"VERSIONS lists versions with no source tree under protocol/versions/: {missing_src}")+if DIST.exists():shutil.rmtree(DIST)- (DIST / "spec").mkdir(parents=True)+ (DIST / "spec" / VERSION).mkdir(parents=True)built = 0+ search_index = []for path, title, src in flat_pages():if not src.exists():print(f" !! missing source: {src}")return 1depth = path.count("/")- body = rewrite_links(render_markdown(src.read_text()), depth)+ md_text = src.read_text()+ GUIDE_CTA = (+ "\n\n---\n\n### Implementation guidance\n\n"+ "**[Implement a client](CONNECTING.md)** — discovery, task submission, event "+ "handling, and artifact retrieval. \n"+ "**[Implement a server](SERVING.md)** — the operations a server answers and how it "+ "connects one or more harnesses.\n")+ if path in ("connecting.html", "serving.html"):+ md_text += GUIDE_CTA+ if path == "conformance.html":+ md_text += (+ "\n\n## Example implementations\n\n"+ "The [examples](IMPLEMENTATIONS.md) page lists the servers and clients "+ "built against UHP, with the version each targets. A listing is a factual entry, "+ "not a certification — this suite is the only thing that certifies.\n")+ rendered, toc = render_markdown(md_text)+ body = rewrite_links(rendered, depth)# The home page leads with the hero; its markdown H1 would repeat it.- hero = ""+ hero, toc_markup = "", toc_html(toc)if path == "index.html":- hero = HERO- body = re.sub(r"<h1>.*?</h1>", "", body, count=1, flags=re.S)- body = re.sub(r"<p><strong>An open standard.*?</strong></p>", "", body, count=1, flags=re.S)- (DIST / path).write_text(page(path, title, body, depth, hero))+ # README is the homepage body (single source of truth). The quick-entry cards are+ # navigation scaffolding, not content — they follow the definition rather than+ # preceding the title, so the page reads title → definition → where to go next+ # (the neutral-standard order). Inject before the first H2 section.+ m = re.search(r"<h2", body)+ body = body[: m.start()] + HERO + body[m.start():] if m else body + HERO+ hero = ""+ # The homepage is a long, multi-section page like any other — keep its on-this-page+ # rail (toc_markup) so it navigates consistently with the rest of the site.+ (DIST / path).write_text(page(path, title, body, depth, hero, toc_markup))+ search_index.append({"title": title, "section": section_of(path),+ "url": url_for(path).lstrip("/"),+ "body": plain_text(body)[:1400]})built += 1for path, title, src in EXTRA:@@ -457,10 +947,28 @@ def build() -> int:print(f" !! missing source: {src}")return 1depth = path.count("/")- body = rewrite_links(render_markdown(src.read_text()), depth)- (DIST / path).write_text(page(path, title, body, depth))+ rendered, toc = render_markdown(src.read_text())+ body = rewrite_links(rendered, depth)+ (DIST / path).write_text(page(path, title, body, depth, "", toc_html(toc)))+ search_index.append({"title": title, "section": "Background",+ "url": url_for(path).lstrip("/"),+ "body": plain_text(body)[:1400]})built += 1+ # The dropdown offers every entry in VERSIONS; each must actually have been built, or a reader+ # who picks it lands on a 404. Today NAV emits only the latest version's chapters, so adding a+ # second version means teaching the build to emit its pages too — this assertion makes that a+ # hard build failure rather than a silent dead link.+ unbuilt = [v for v in VERSIONS if not (DIST / "spec" / v / "index.html").exists()]+ assert not unbuilt, (+ f"VERSIONS offers versions whose spec pages were not built: {unbuilt} — "+ f"extend NAV/build to emit /spec/<version>/ for each before listing it")++ # /spec forwards to the latest version's overview: a stable, friendly entry that never holds+ # content of its own, so there is nothing to keep in sync with the dated page it points at.+ (DIST / "spec" / "index.html").write_text(+ redirect_html(f"/spec/{VERSION}", "Specification"))+# Publishing metadata: a protocol site that cannot be crawled is a protocol nobody finds.(DIST / "robots.txt").write_text(f"User-agent: *\nAllow: /\nSitemap: https://{SITE}/sitemap.xml\n")@@ -476,21 +984,32 @@ def build() -> int:for group, items in NAV:llms.append(f"\n## {group}\n")for p, title, _ in items:- llms.append(f"- [{title}](https://{SITE}/{url_for(p).lstrip('./')}): {DESCRIPTIONS[p]}")+ llms.append(f"- [{title}](https://{SITE}/{url_for(p).lstrip('./')}): {DESCRIPTIONS[desc_key(p)]}")llms.append("\n## Background\n")for p, title, _ in EXTRA:- llms.append(f"- [{title}](https://{SITE}/{url_for(p).lstrip('./')}): {DESCRIPTIONS[p]}")+ llms.append(f"- [{title}](https://{SITE}/{url_for(p).lstrip('./')}): {DESCRIPTIONS[desc_key(p)]}")(DIST / "llms.txt").write_text("\n".join(llms) + "\n", encoding="utf-8")- # Host config travels WITH the build, so `python site/build.py && vercel deploy dist` is the- # whole publish. cleanUrls lives there, and the extensionless links this file emits depend on- # it — keeping the two in separate places is how they drift apart.- shutil.copy(HERE / "vercel.json", DIST / "vercel.json")+ # Search index: every page's title and plain-text body, built from the same render as the+ # pages themselves so it can never describe a page that no longer exists. Served static; the+ # search dialog fetches it once and filters in the browser — no search service, no build chain.+ (DIST / "search-index.json").write_text(json.dumps(search_index, ensure_ascii=False),+ encoding="utf-8")++ # One host config, at protocol/vercel.json — the Vercel project's Root Directory is protocol/,+ # so the Git integration reads it there on every push. It is also copied into the build so a+ # manual `vercel deploy site/dist` publishes with the identical cleanUrls/headers/redirects;+ # a single source means the two paths can never drift.+ shutil.copy(ROOT / "vercel.json", DIST / "vercel.json")# The machine-readable definitions are part of the standard, so they are served with it.shutil.copytree(ROOT / "schema", DIST / "schema",ignore=shutil.ignore_patterns("build.py", "__pycache__"))+ # Last: every link in the finished site must resolve. Runs after schema is in place so links+ # to the machine-readable files are checked against the files that actually shipped.+ check_links(DIST)+print(f"built {built} pages + schema into {DIST}")return 0diff --git a/protocol/site/build.sh b/protocol/site/build.shnew file mode 100755index 00000000..2465e303--- /dev/null+++ b/protocol/site/build.sh@@ -0,0 +1,9 @@+#!/usr/bin/env bash+# The one place the site's build steps live. Vercel (protocol/vercel.json) and CI+# (.github/workflows/tests.yml) both invoke this script rather than repeating the commands, so the+# deployed build and the gated build can never diverge. It resolves paths against its own location,+# so it runs identically from any working directory.+set -euo pipefail+cd "$(dirname "$0")"+python3 -m pip install --quiet --requirement requirements.txt+python3 build.pydiff --git a/protocol/site/requirements.txt b/protocol/site/requirements.txtnew file mode 100644index 00000000..101b7b5c--- /dev/null+++ b/protocol/site/requirements.txt@@ -0,0 +1 @@+Markdown==3.6diff --git a/protocol/site/vercel.json b/protocol/vercel.jsonsimilarity index 65%rename from protocol/site/vercel.jsonrename to protocol/vercel.jsonindex 53942677..f25e436a 100644--- a/protocol/site/vercel.json+++ b/protocol/vercel.json@@ -1,7 +1,14 @@{"$schema": "https://openapi.vercel.sh/vercel.json",+ "framework": null,+ "buildCommand": "bash site/build.sh",+ "outputDirectory": "site/dist",+ "ignoreCommand": "git diff --quiet \"$VERCEL_GIT_PREVIOUS_SHA\" \"$VERCEL_GIT_COMMIT_SHA\" -- .","cleanUrls": true,"trailingSlash": false,+ "redirects": [+ { "source": "/spec", "destination": "/spec/2026-08-11", "permanent": false }+ ],"headers": [{"source": "/schema/(.*).json",