Integrate Devin backend with ACP and update documentation

.github/workflows/open-pr.yml

@@ -0,0 +1,45 @@
+# Open a pull request as github-actions[bot].
+#
+# Main requires a pull request, one approval, and green checks, with no bypass for anyone. A
+# pull request cannot be approved by its own author, so an operator who works alone (or through
+# an agent using their account) could never merge. This workflow lets the agent open the PR
+# under the bot identity instead; the operator is then a reviewer, not the author, and approves
+# like anyone else.
+#
+# Trigger it with the branch to open, e.g.
+#   gh workflow run open-pr.yml -f branch=fix/x -f title="..." -f body="..."
+#
+# A PR opened with GITHUB_TOKEN does not start the checks workflow by itself (GitHub's guard
+# against recursive runs). The next push to the branch does, and the agent makes one; an empty
+# commit is enough.
+name: open-pr
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: head branch to open against main
+        required: true
+      title:
+        description: pull request title
+        required: true
+      body:
+        description: pull request body (markdown)
+        required: false
+        default: ""
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  open:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ inputs.branch }}
+          TITLE: ${{ inputs.title }}
+          BODY: ${{ inputs.body }}
+        run: |
+          existing=$(gh pr list --head "$BRANCH" --state open --json number -q '.[0].number')
+          if [ -n "$existing" ]; then echo "PR #$existing already open for $BRANCH"; exit 0; fi
+          gh pr create --base main --head "$BRANCH" --title "$TITLE" --body "$BODY"

.github/workflows/release.yml

@@ -140,6 +140,7 @@ jobs:
           build-args: |
             HR_SKILLS_REF=${{ needs.plan.outputs.skills }}
             HR_KITS_REF=${{ needs.plan.outputs.kits }}
+            HR_VERSION=${{ needs.plan.outputs.version }}
           outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
           cache-from: type=gha,scope=${{ matrix.arch }}
           cache-to: type=gha,mode=max,scope=${{ matrix.arch }}
@@ -163,7 +164,7 @@ jobs:
           docker logs smoke 2>&1 | tail -30
           LINE=$(docker logs smoke 2>&1 | grep "backends available" | tail -1 || true)
           echo "$LINE"
-          for b in claude codex hermes; do
+          for b in claude codex hermes pi dsh; do
             echo "$LINE" | grep -q "$b" || { echo "::error::$b did not install on ${{ matrix.arch }}"; exit 1; }
           done
           docker exec smoke ls /opt/harnessrouter/kits

.github/workflows/tests.yml

@@ -0,0 +1,111 @@
+# Run every test suite the repository carries, on every pull request and every push to main.
+#
+# This exists because until now nothing did: `release.yml` gates what ships, but the tests in
+# gateway/tests, runner/tests, protocol/conformance/tests and ui only ran when someone remembered
+# to run them — which is how a green-looking PR carries a red suite. CONTRIBUTING.md's
+# "Development checks" section tells contributors which commands to run; this workflow runs the
+# same commands, so the two cannot drift apart without this file changing.
+#
+# One job per suite, because they fail for unrelated reasons and a contributor should see WHICH
+# area broke without reading logs: a gateway failure is not a console failure. No job depends on
+# another; they all run in parallel and each is a required signal on its own.
+name: tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gateway:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: gateway/requirements.txt
+      # The media tests build real fixtures (a one-second mp4, an mp3 with a readable duration)
+      # and gate themselves on `have_ffmpeg()` — without ffmpeg they silently skip, and a media
+      # regression would ride a green run. Installing it makes them actually run here.
+      - name: Install ffmpeg for the media fixtures
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg
+      # jsonschema is test-only: test_response_error_envelope.py validates failed Responses
+      # against the spec schema. It stays out of requirements.txt so it never ships in the image.
+      - run: pip install -r gateway/requirements.txt pytest jsonschema
+      - run: python -m pytest gateway/tests -q
+
+  runner:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: runner/requirements.txt
+      # httpx: the runner suite drives the app through FastAPI's TestClient, which needs it. The
+      # runner itself does not, so it stays out of requirements.txt and lives with pytest here.
+      - run: pip install -r runner/requirements.txt pytest httpx
+      - run: python -m pytest runner/tests -q
+
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: protocol/conformance/pyproject.toml
+      - run: pip install -e protocol/conformance pytest
+      - run: python -m pytest protocol/conformance/tests -q
+
+  console:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+      # Mirrors the Dockerfile's install: .npmrc carries legacy-peer-deps, without which npm
+      # refuses the tree (several deps still declare React 18 peers while the app runs 19).
+      - run: npm ci --no-audit --no-fund || npm install --no-audit --no-fund
+      - run: npm run type-check
+      # The console has no jest tests yet, and bare `jest` exits 1 on "No tests found" — which
+      # would read as a test failure when the truth is an empty suite. The flag makes an empty
+      # 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'"

.gitignore

@@ -12,3 +12,4 @@ __pycache__/
 protocol/site/dist/
 
 protocol/site/dist/
+*.egg-info/

CONTRIBUTING.md

@@ -2,6 +2,11 @@
 
 Contributions are welcome, and so are questions.
 
+This project is two connected open-source layers: the Unified Harness Protocol (UHP), an open
+standard for how products work with agent harnesses, and this repository, a working implementation
+of it. Both take contributions — the specification, the conformance suite, harness support, the
+implementation, and the documentation.
+
 ## Where things go
 
 - Proposals and bug reports: GitHub Issues.
@@ -10,14 +15,67 @@ Contributions are welcome, and so are questions.
 
 ## Substantial changes: describe before you build
 
-For anything beyond a small fix, open an issue first. Describe the problem you are solving, the change you propose, and its expected impact, before writing the implementation. Once a maintainer agrees on the direction, either you or a maintainer implements it.
+For anything beyond a small fix, open an issue first. Describe the problem you are solving, the
+change you propose, and its expected impact, before writing the implementation. Once a maintainer
+agrees on the direction, either you or a maintainer implements it.
 
-Small, obvious fixes such as typos or a clear bug with an equally clear fix can go straight to a pull request.
+Small, obvious fixes such as typos or a clear bug with an equally clear fix can go straight to a
+pull request.
 
 ## Changes to the protocol
 
-The Unified Harness Protocol has a stricter process, because a specification, a reference implementation, and a conformance suite have to stay in step. If your change touches the protocol, follow [protocol/GOVERNANCE.md](protocol/GOVERNANCE.md): open a UHP Enhancement Proposal (UEP) as an issue labelled `uep` with Problem, Proposal, Compatibility, and Alternatives. Maintainers respond within 10 working days. An accepted UEP ships as one pull request that updates the specification, the schema, the reference implementation, a conformance test, and the changelog together.
+The Unified Harness Protocol has a stricter process, because a specification, a reference
+implementation, and a conformance suite have to stay in step. If your change touches the protocol,
+follow [protocol/GOVERNANCE.md](protocol/GOVERNANCE.md): open a UHP Enhancement Proposal (UEP) as
+an issue labelled `uep` with Problem, Proposal, Compatibility, and Alternatives. Maintainers
+respond within 10 working days. An accepted UEP ships as one pull request that updates the
+specification, the schema, the reference implementation, a conformance test, and the changelog
+together.
+
+## Pull requests
+
+Keep each pull request to one problem. Before requesting review: link the issue when one exists;
+add or update tests for behavior changes; update the documentation when the public API, protocol,
+configuration, or user workflow changes; call out compatibility, security, or licensing
+implications; and check that no credentials, generated dependencies, or unrelated files ride
+along.
+
+## Development checks
+
+Run the checks that match the area you changed.
+
+For the console:
+
+```bash
+cd ui
+npm ci
+npm run type-check
+npm test
+npm run build
+```
+
+For the gateway:
+
+```bash
+python -m pytest gateway/tests
+```
+
+For container-level changes, build the image and walk the documented self-hosted flow before
+requesting review.
 
 ## License
 
-By contributing, you agree that your contribution is licensed under the Apache License 2.0, the same license as this repository.
+By contributing, you agree that your contribution is licensed under the Apache License 2.0, the
+same license as this repository.
+
+## How changes land on main
+
+`main` takes pull requests only: one approval, every check green, no bypass for anyone, admins
+included. A pull request cannot be approved by its own author, so an agent working through a
+maintainer's account opens its pull requests with the `open-pr` workflow instead, which creates
+them as `github-actions[bot]`; the maintainer then reviews and approves like any other change.
+
+```bash
+gh workflow run open-pr.yml -f branch=<branch> -f title="<title>" -f body="<body>"
+git commit --allow-empty -m "ci: start checks" && git push   # a bot-opened PR needs one push to run CI
+```

Dockerfile

@@ -17,8 +17,8 @@
 # They land in the data volume, so the cost is paid once per volume rather than once per start.
 # Choose backends at RUN time:
 #
-#   docker run -e HR_BACKENDS=claude,codex,hermes   ...   # default: all three
-#   docker run -e HR_BACKENDS=claude                ...   # lean
+#   docker run -e HR_BACKENDS=claude,codex,hermes,pi,dsh,opencode ...   # the default
+#   docker run -e HR_BACKENDS=opencode                            ...   # lean
 #
 # WITH_BROWSER is still a build arg because Chromium and its system libraries genuinely belong
 # in the image layer.
@@ -27,7 +27,7 @@
 # This is the SAME console the hosted product runs. Surfaces with no self-hosted backend
 # (billing, marketplace, analytics, sign-in) are hidden by the edition flag rather than removed,
 # so the two stay one codebase. See ui/src/lib/edition.ts.
-FROM node:20-slim AS ui
+FROM node:22-slim AS ui
 WORKDIR /ui
 # git: the UI depends on the ReifyUI component library straight from its repository.
 RUN apt-get update -y && apt-get install -y --no-install-recommends git ca-certificates \
@@ -84,8 +84,10 @@ RUN set -eux; \
       && rm -rf /var/lib/apt/lists/*; \
     fi
 
-# Node is needed for the UI server and for the npm-based agent CLIs.
-RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+# Node is needed for the UI server and for the npm-based agent CLIs. 22, not 20: pi's
+# engine floor is >=22.19, and node 20 has been end-of-life since April 2026 anyway —
+# the other CLIs (claude >=18, codex >=20) run unchanged on 22.
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y --no-install-recommends nodejs \
     && rm -rf /var/lib/apt/lists/* /root/.npm
 
@@ -139,6 +141,13 @@ RUN chmod +x /tmp/install-skills.sh \
 # Starter Kits: a Harness plus an app, both baked in. Same pull-and-pin shape as the skills
 # bundle above, and the same rule: pass a commit sha to get the newest catalogue, because that
 # is what changes the layer's inputs.
+# What this build IS, for the discovery document and anything else that reports a version. The
+# release workflow passes the tag; a local build says so honestly rather than claiming a number.
+# Without this the gateway fell back to a literal that had been six releases stale, so every
+# install told clients it was 0.3.0 (found by the 0.9.0 release sanity run).
+ARG HR_VERSION=dev
+ENV HR_VERSION=${HR_VERSION}
+
 ARG WITH_STARTER_KITS=1
 ARG HR_KITS_REPO=https://github.com/HarnessRouter/starter-kit.git
 ARG HR_KITS_REF=main
@@ -160,8 +169,12 @@ COPY --from=ui /ui/.next/standalone /app/ui/
 COPY --from=ui /ui/.next/static     /app/ui/.next/static
 COPY --from=ui /ui/public           /app/ui/public
 
-# The agent CLIs refuse to run as root (they gate their own permission bypass on it), so the
-# runtime user is unprivileged and owns the workspace and data volume.
+# `agent` is the PRODUCT's user: the gateway and the console run as it and it owns the data
+# volume. The container itself starts as root and the entrypoint drops privileges per process,
+# because the runner needs root for one thing: every agent CLI runs as its own per-session uid,
+# which owns its session directory and nothing else (the write-wall; see docker/entrypoint.sh).
+# The CLIs refuse to run as root anyway (they gate their own permission bypass on it), and they
+# never do.
 #
 # The `rm -rf /home/agent/.npm` is not tidying. HOME is already /home/agent while the kit apps are
 # built above, and those builds run as root — so npm leaves ~1600 root-owned files in the cache
@@ -179,7 +192,6 @@ RUN useradd -m -u 10001 agent \
     && mkdir -p /data \
     && chown -R agent:agent /data /app /home/agent \
     && chmod -R a+rX /opt/harnessrouter/skills /opt/harnessrouter/kits
-USER agent
 
 EXPOSE 3000
 VOLUME ["/data"]