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
openhands: a new backend, driven through its maintained agent-server (1.49.2) (#215)
ZixiaoL97e247fc5a21
diff --git a/Dockerfile b/Dockerfileindex f8e68c44..9588d682 100644--- a/Dockerfile+++ b/Dockerfile@@ -56,8 +56,13 @@ ENV DEBIAN_FRONTEND=noninteractive \HARNESS_WORKSPACE=/data/workspaces \HR_DATA_DIR=/data+# tmux is here for openhands and nothing else: openhands-tools declares `libtmux`, the python+# client, and libtmux drives the real `tmux` binary — upstream's own image apt-installs it. Without+# it the agent-server dies on import (`ModuleNotFoundError` / a tmux that is not there), which is a+# failure at START, not at use. The locale above matters to it too: libtmux's format parsing needs+# a UTF-8 locale, which LANG=C.UTF-8 already gives.RUN apt-get update -y && apt-get install -y --no-install-recommends \- curl ca-certificates git bash tini \+ curl ca-certificates git bash tini tmux \&& rm -rf /var/lib/apt/lists/*# Document preview. The built-in skills create .docx/.pptx/.xlsx routinely, and LibreOffice isdiff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex d6d47c68..7f1e97c4 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -177,7 +177,7 @@ export HOSTNAME=0.0.0.0TOOLS="$DATA_DIR/agent-tools"export PATH="$TOOLS/bin:$PATH"export NODE_PATH="$TOOLS/lib/node_modules"-export HR_BACKENDS="${HR_BACKENDS:-claude,codex,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider}"+export HR_BACKENDS="${HR_BACKENDS:-claude,codex,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider,openhands}"wanted() { [[ ",$HR_BACKENDS," == *",$1,"* ]]; }# The executable IS the definition of "installed" — an installer that exits 0 without producing@@ -198,6 +198,7 @@ backend_bin() {goose) echo "$TOOLS/bin/goose" ;;kimi) echo "$TOOLS/bin/kimi" ;;aider) echo "$TOOLS/aider-venv/bin/aider" ;;+ openhands) echo "$TOOLS/openhands-venv/bin/python" ;;esac}@@ -306,6 +307,74 @@ if aider.__version__ != want:# from KIMI_MODEL_* alone, -r refusing an unknown session, agent files matching tool NAMES,# $KIMI_CODE_HOME/mcp.json, the exit-1 failure line) was measured on THIS version.KIMI_PIN="${HR_KIMI_VERSION:-2.0.0}"; KIMI_PIN="${KIMI_PIN#v}"+# OpenHands V1, MIT (OpenHands/agent-sdk), pinned to 1.49.2 — the AGENT SERVER, not the CLI.+#+# PyPI `openhands` is OpenHands/openhands-cli, whose README opens with "This project is no longer+# actively maintained" and whose last release is 1.16.0 of 2026-05-08. This is the interface its+# vendor does maintain: `openhands-agent-server`, released 1.49.2 on 2026-09-17.+#+# THE THREE PINS GO IN ONE pip INVOCATION, and that is not cosmetic. `openhands-agent-server`+# imports `openhands.tools` and `libtmux` at module level and declares NEITHER; `openhands-tools`+# is what brings both. Installed one at a time, pip resolves each call on its own and lands on+# browser-use 0.13.10, which pins `openai==2.26.0` against the server's own `openai>=2.33.0` — a+# set `pip check` refuses. Given all three at once it backtracks to browser-use 0.11.13 and the+# environment is consistent (verified: `No broken requirements found`, and the same resolution uv+# reaches). The 1.34.0 set the OpenHands platform itself declares does not resolve at all+# (`ResolutionImpossible`, lmnr against openhands-sdk), so 1.49.2 is the floor as well as the pin.+#+# THE FOURTH PIN IS litellm, HELD BELOW 1.95.0, and it decides whether a follow-up turn survives.+# The SDK asks only for `litellm>=1.93.0`, so pip takes the newest — and from 1.95.0 litellm's+# PromptTokensDetailsWrapper mirrors an assignment between `cache_write_tokens` and+# `cache_creation_tokens`, which puts BOTH names into `model_fields_set` and then drops the unset+# attribute from __dict__. The SDK's telemetry (llm/utils/telemetry.py, _cache_buckets) reads+# `"cache_creation_tokens" in details.model_fields_set` as its existence test, so it asks for an+# attribute that is no longer there: `AttributeError: 'PromptTokensDetailsWrapper' object has no+# attribute 'cache_creation_tokens'`. Each side is self-consistent; together they are not, and+# 1.49.2 is the newest SDK, so there is nothing to upgrade to.+#+# It only fires once a response carries prompt_tokens_details — a prompt-cache hit, which a FIRST+# turn cannot have — so it reads as "follow-ups fail and first turns do not". The agent-server+# publishes no error event for it (see the driver's fallback), tenacity retries it five times, and+# the record shows a 150-200 s turn that ended for no stated reason. Measured on gemini-3-flash-preview,+# same command and image, litellm the only difference: 1.101.0 gave first ok / follow-up FAIL 145 s /+# switch ok / artifact FAIL 175 s / recycle FAIL 148 s, and 1.94.3 gave five of five in 10-14 s each.+#+# Own venv, the dsh/hermes precedent: it pins litellm, fastmcp, pydantic and a browser stack, and+# must not share the runner's interpreter.+install_openhands() {+ oh_py="${HR_OPENHANDS_BASE_PYTHON:-python3}"+ "$oh_py" -m venv "$TOOLS/openhands-venv" || return 1+ "$TOOLS/openhands-venv/bin/pip" install -q --disable-pip-version-check \+ "openhands-agent-server==${HR_OPENHANDS_VERSION:-1.49.2}" \+ "openhands-tools==${HR_OPENHANDS_VERSION:-1.49.2}" \+ "openhands-sdk==${HR_OPENHANDS_VERSION:-1.49.2}" \+ "litellm==${HR_OPENHANDS_LITELLM_VERSION:-1.94.3}" || return 1+ # Prove the server can actually START, and that the litellm pin still buys what it is for, before+ # declaring the install good. Importing its api module is what catches the undeclared dependencies+ # above: the failure they cause is an import error at the first live turn, not a pip error here.+ "$TOOLS/openhands-venv/bin/python" -c '+import sys+import libtmux # noqa: F401 — undeclared by the server, brought by openhands-tools+import openhands.agent_server.api # noqa: F401 — the module the server boots from+import importlib.metadata as md+want = sys.argv[1]+have = md.version("openhands-agent-server")+if have != want:+ sys.exit("openhands-agent-server %s installed, wanted %s" % (have, want))+# The litellm pin is asserted by BEHAVIOUR, not by version, because the version is only how this+# pair happens to be broken today: build the wrapper the way a cached prompt does and check that+# the existence test the SDK uses still agrees with the attribute. A pin bumped past 1.95.0 fails the+# image here instead of failing every follow-up turn on a provider that reports prompt caching.+from litellm.types.utils import PromptTokensDetailsWrapper+details = PromptTokensDetailsWrapper(cached_tokens=1)+if "cache_creation_tokens" in details.model_fields_set and not hasattr(+ details, "cache_creation_tokens"):+ sys.exit("litellm %s and openhands-sdk %s disagree about cache_creation_tokens; "+ "hold litellm below 1.95.0" % (md.version("litellm"), md.version("openhands-sdk")))+' "${HR_OPENHANDS_VERSION:-1.49.2}" || return 1+ command -v tmux >/dev/null 2>&1 || { echo "openhands: the tmux binary is missing"; return 1; }+}+install_kimi() {case "$(uname -m)" inx86_64) km_arch="x64"; km_sha="ebc1ad504e458d66f0cc57d4e9d709a2060647f5b89d4e21026903b96204c3ed" ;;@@ -492,6 +561,37 @@ install_backends() {# `kimi --version` prints the bare version on Kimi Code CLI ("2.0.0") and "kimi, version 1.50.0" on# its predecessor, so comparing it to the pin both installs a missing binary and replaces the old# product on a volume that was first started by 0.18.0.+ # In the default set, for the reason aider is: the console offers every base the gateway's+ # catalogue lists, and a listed base that is not installed fails on its first task. An operator+ # who does not want the 666 MB leaves it out of HR_BACKENDS, the switch every backend has.+ #+ # THE GUARD COMPARES THE VERSION, not the file, for the reason dsh's venv already carries: the+ # venv lives on the data volume and outlives the image. A volume first started by an earlier+ # build of this branch held an `openhands-venv` whose python was perfectly executable and whose+ # contents were the DEPRECATED CLI's stack — openhands 1.16.0 pinning openhands-sdk 1.21.0 — so+ # an existence check skipped the install and every turn died on+ # `No module named 'openhands.sdk.marketplace.registration'`. Caught by the first column, not by+ # a test. A mismatch rebuilds the venv from scratch; conversations live in the workspace, not in+ # it, so nothing of a session is lost.+ OPENHANDS_PIN="${HR_OPENHANDS_VERSION:-1.49.2}"+ # BOTH pins are compared, because the venv outlives the image in the same way for each: a volume+ # whose openhands-venv was built before litellm was pinned holds the right agent-server and the+ # wrong litellm, and an agent-server-only comparison would skip the install and hand that volume+ # back the follow-up failures the pin exists to remove.+ OPENHANDS_LITELLM_PIN="${HR_OPENHANDS_LITELLM_VERSION:-1.94.3}"+ # Probed only when there IS something to probe: asking a path that does not exist for its version+ # is a 127 that takes the whole entrypoint down with it, which is how this line first shipped.+ oh_have=""+ if [ -x "$(backend_bin openhands)" ]; then+ oh_have="$("$(backend_bin openhands)" -c \+ 'import importlib.metadata as m; print(m.version("openhands-agent-server"), m.version("litellm"))' 2>/dev/null || true)"+ fi+ if wanted openhands && [ "$oh_have" != "$OPENHANDS_PIN $OPENHANDS_LITELLM_PIN" ]; then+ rm -rf "$TOOLS/openhands-venv"+ echo "[harnessrouter] installing OpenHands agent-server $OPENHANDS_PIN (MIT) — ~666 MB, this takes a minute…"+ try_install "OpenHands" install_openhands || true+ fi+if wanted kimi && [ "$("$(backend_bin kimi)" --version 2>/dev/null | head -n 1)" != "$KIMI_PIN" ]; thenecho "[harnessrouter] installing Kimi Code CLI $KIMI_PIN (MIT, version-pinned)…"try_install "Kimi Code CLI" install_kimi || truediff --git a/docs/harness-verification.md b/docs/harness-verification.mdindex f4067983..86fc1d98 100644--- a/docs/harness-verification.md+++ b/docs/harness-verification.md@@ -142,6 +142,14 @@ which fails the type-check, and that is the only one a compiler will find for yoa history carrying the error prose. The normaliser must recognise the CLI's prefix, fail theturn, and keep the sentence as the reason — `_CLAUDE_ERR_RE` and `_GOOSE_ERR_RE`. Pin theprefix with a test, and take it from the pinned binary (`strings`), not from the docs.+ A harness can also report a failure NOWHERE. openhands' agent-server publishes an error event+ only for an exception that is not a `ConversationRunError`, on the assumption that the run+ already emitted its own — and an exception raised out of the run's error handling is exactly+ the case where nobody did: the status flips to error and the wire carries no reason at all.+ Where a backend writes a log, read its tail as the fallback, and take the EXCEPTION lines out+ of it rather than the last lines — a turn that dies in seconds and is then retried to+ exhaustion ends with `SIGTERM … Shutting down`, and putting that in the record is worse than+ silence, because it reads like a reason.7. `CHECKPOINT_EXCLUDE` and `_git_ensure`'s ignore list: any file the CLI writes that can hold acredential.diff --git a/docs/self-hosting-guide.md b/docs/self-hosting-guide.mdindex 383ef6c5..0ddfeee8 100644--- a/docs/self-hosting-guide.md+++ b/docs/self-hosting-guide.md@@ -333,16 +333,16 @@ problem, because it only offers you providers that work.| Connection `provider` | Backends that can use it ||---|---|-| `anthropic` | Claude Code, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `openai` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `openrouter` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `azure-foundry` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `google` | Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Gemini CLI, Cline, Oh My Pi, Kimi Code CLI, Aider |+| `anthropic` | Claude Code, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `openai` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `openrouter` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `azure-foundry` | Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `google` | Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Gemini CLI, Cline, Oh My Pi, Kimi Code CLI, Aider, OpenHands || `bedrock` | Claude Code, Hermes |-| `tokenrouter` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Gemini CLI, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `vercel` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `llmtr` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |-| `custom` | Claude Code, Codex (Responses format), Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider |+| `tokenrouter` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Gemini CLI, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `vercel` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `llmtr` | Claude Code, Codex, Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |+| `custom` | Claude Code, Codex (Responses format), Hermes, Pi, DeepSeek Harness, OpenCode, Qwen Code, Cline, Oh My Pi, goose, Kimi Code CLI, Aider, OpenHands |</details>@@ -650,15 +650,16 @@ Backends are installed into your data volume rather than baked into the image, swant is a run-time setting:```bash-docker run -e HR_BACKENDS=claude,codex,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider ... # the default+docker run -e HR_BACKENDS=claude,codex,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider,openhands ... # the defaultdocker run -e HR_BACKENDS=opencode ... # lean```-Aider is the largest of the set: its environment is about 735 MB and takes about ninety seconds to-install on a fresh volume. Leave it out of `HR_BACKENDS` if you will not use it.+Aider and OpenHands are the largest of the set: each environment is about 700 MB and takes a minute+or two to install on a fresh volume. Leave either out of `HR_BACKENDS` if you will not use it.-A backend that fails to install is not fatal: the others still work, and the console offers what-the gateway's catalogue lists, so an unavailable backend simply is not shown.+A backend that fails to install is not fatal: the others still work. The console offers every+base the gateway's catalogue lists, so a task on a backend that did not install fails on its+first turn; the container's log names the install that failed.Chromium is genuinely an image layer, so it stays a build flag:diff --git a/docs/support-matrix-notes.md b/docs/support-matrix-notes.mdindex fb4fae2e..2f1ba3a4 100644--- a/docs/support-matrix-notes.md+++ b/docs/support-matrix-notes.md@@ -1050,3 +1050,219 @@ officecli in about two runs of five (gpt-5.5, 29 s and 74 s, six commands) and oan outline .md and stops, treating the file as the deliverable under aider's coding prompt;nemotron-3-super and claude-sonnet-4.6 built it every time on the hosted service (457 s and 428 s).Not a harness defect: the prompt is aider's, the choice is the model's, and the record says which.++++## The openhands backend: OpenHands V1 through its agent-server (2026-09-18/19)++PyPI `openhands` is OpenHands/openhands-cli, whose README opens with "This project is no longer+actively maintained". The product its vendor does maintain is the SDK's **agent-server**+(`openhands-agent-server` 1.49.2, MIT), a REST + WebSocket service, and that is what this base+drives. One server process per turn — cold start 3.3-4.1 s measured — so the one-process-per-turn+contract every other backend keeps is kept here too, and a conversation survives in the workspace+rather than in the process.++**The surface, as measured.**++- A turn is: start the server on a free port, `POST /api/conversations` (created once; a second+ create with a different tool list leaves the persisted agent as it was), then send the message+ and read the event WebSocket to EOF.+- The agent is FROZEN at the conversation's first creation, so the conversation id is a uuid5 over+ the tool policy AND the declared MCP servers: a changed policy has to be a different conversation+ or the change is silently dropped.+- The credential is never persisted: `base_state.json` holds the whole LLM spec with+ `api_key: None`, so the key rides the environment and a resumed turn gets it from there.+- The model id is sent with an `openai/` prefix. Without an explicit provider litellm infers one+ from the base url, and a relay url inferred as Vercel produced+ `Missing credentials … VERCEL_AI_GATEWAY_API_KEY` on a resumed turn.+- The answer can arrive as a `FinishAction` rather than a trailing assistant message; disabling a+ tool is enforced by OMISSION from the spec, not by a refusal.++**TMUX_TMPDIR, the defect that cost the most.** The terminal tool runs commands in tmux, and the+server defaults `TMUX_TMPDIR` to a directory inside the working directory. A workspace here is+`/data/workspaces/hsess<32 hex>`, so the socket landed at+`/data/workspaces/hsess…/tmp/openhands-agent-server-<pid>/tmux-<uid>/openhands` — 106 characters+against the 108-byte `sun_path` limit — and tmux answered `error connecting to … (File name too+long)`. The agent then retried the tool it could not start, which turned a 10 s turn into 235 s and+then into 4,000 s. Four wrong guesses came first (a tmux session leak, process exhaustion, a+Chromium preload, a blocking relay); none of them survived contact with the server's own output,+which at that point was going to `DEVNULL`. The server's stdout now goes to a FILE under+`.harness/`, and that single change is what ended the investigation. A driver run from a short cwd+never sees any of this.++**Columns.**++- **vercel** (49 of the 50 catalog ids runnable): 239 of 245 scenarios. qwen3.8-27b missed a recall+ after a switch and after a recycle (the model, not the wiring). mistral-medium-3.5 failed its+ other four scenarios; Vercel names its own fix in the refusal (`Assistant message must have+ either content`), the relay now stringifies assistant content for that route, and the re-run+ passed five of five. The section below rules out the litellm defect as a second cause.+- **google** (the eight gemini ids): 40 of 40 after the litellm pin below; 29 of 40 before it.+- **custom-harness**: openhands carries its own skill, script and tool policy, and reaches a+ declared MCP server (`https://mcp.deepwiki.com/mcp`, 19 s, all six claims).++## openhands: a follow-up dies of a field that two dependencies disagree about (2026-09-19)++Every gemini follow-up on the google column failed after 145-212 s with `the turn failed: the turn+ended error` and no reason of any kind. Eleven scenarios across five models, and never a FIRST+turn. The cause is neither the provider nor the request shape:++```+AttributeError: 'PromptTokensDetailsWrapper' object has no attribute 'cache_creation_tokens'+ openhands/sdk/llm/utils/telemetry.py:259, _cache_buckets+```++From litellm 1.95.0, `PromptTokensDetailsWrapper.__setattr__` mirrors an assignment between+`cache_write_tokens` and `cache_creation_tokens`, which puts BOTH names into `model_fields_set`,+and litellm then drops the unset attribute from `__dict__` as a construction-cost optimisation. The+SDK's telemetry uses `"cache_creation_tokens" in details.model_fields_set` as its existence test.+Each side is self-consistent; together they are not. Three lines reproduce it with no agent, no+provider and no network:++```+>>> PromptTokensDetailsWrapper(cached_tokens=123).model_fields_set+{'cache_creation_tokens', 'cached_tokens', 'cache_write_tokens'}+>>> hasattr(_, 'cache_creation_tokens')+False+```++`_cache_buckets` returns `(0, 0)` before reading anything when `prompt_tokens_details` is absent,+so the defect needs a response that carries it — which is why this reads as "follow-ups fail and+first turns do not". Vercel is immune for a reason worth recording: it reports+`cache_creation_input_tokens` on every response, litellm therefore SETS `cache_creation_tokens`+rather than leaving it None, the attribute genuinely exists, and the existence test agrees with it.+Measured through litellm 1.101.0 on the real streaming path — vercel/mistral-medium-3.5 and+vercel/gpt-5.4 both `hasattr=True`, both ok.++**Not yet pinned: what makes Google report the field.** Four shapes asked of Google directly (a+short prompt, a 4,008-token prefix sent twice, tools declared, and a follow-up carrying a tool+result) all came back with no `prompt_tokens_details` at all, so none of them reproduces the crash+from outside. The production turns that do crash go through the relay and carry the SDK's own large+system prompt; the necessary condition is established and the sufficient one is not. This does not+touch the fix, which was measured end to end.++1.49.2 is the newest SDK, so there is nothing to upgrade to; the SDK asks only for+`litellm>=1.93.0`, so the fix is to hold litellm below 1.95.0. The entrypoint pins 1.94.3 as a+fourth pin in the same single pip invocation and then asserts the DEFECT IS ABSENT rather than+asserting the version, so a future bump fails the image instead of failing every follow-up on a+provider that reports prompt caching.++**THE DEFECT IS INTERMITTENT, and that shapes what the evidence can carry.** Google populates+`prompt_tokens_details` only sometimes; a turn that does not get it passes on the broken pin too.+Captured from inside `_cache_buckets` on litellm 1.101.0, on a 7,410-token follow-up that passed:+`Usage(prompt_tokens=7410, …, prompt_tokens_details=None)`. In one five-scenario run on the broken+pin, follow-up, switch and artifact failed while recycle passed. So the single-model A/B below is+supporting evidence rather than proof — the column is the measurement that carries the claim:+**29 of 40 before the pin, 40 of 40 after**, same eight ids, same image otherwise.++**The A/B.** Same command, same image, same model (gemini-3-flash-preview), litellm the only+difference:++| scenario | litellm 1.101.0 | litellm 1.94.3 |+| --- | --- | --- |+| first | ok 10.71 s | ok 10.69 s |+| follow-up | **FAIL 145.01 s** | ok 10.70 s |+| switch | ok 34.80 s | ok 10.71 s |+| artifact | **FAIL 175.02 s** | ok 13.76 s |+| recycle | **FAIL 147.59 s** | ok 10.69 s |++**Why the record said nothing.** `event_service._run_and_publish` publishes an error event only+for an exception that is NOT a `ConversationRunError`, on the assumption that `run()/arun()` already+emitted its own — and an exception raised out of arun's error handling is exactly the case where+nobody did. The status flips to error, the WebSocket carries nothing else, and tenacity retries+five times with an 8→64 s backoff, which is the whole of the 145-212 s. The sentence existed only+in the server's log. The driver now falls back to that log's tail when a turn fails with no reason+on the wire, and sets `COLUMNS` so the log is wide enough for the sentence to survive in one piece.++**mistral-medium-3.5 on Vercel was a different defect, and this settles it.** Its four failures+share the shape and the duration band (144-208 s, never a first turn) of the litellm defect above,+which is reason enough to doubt the first attribution — a re-run passing five of five cannot rule+out a probabilistic cache-hit crash. It is ruled out by the probe instead: asked through litellm+1.101.0 on the real streaming path, vercel/mistral-medium-3.5 answers `hasattr=True`, so that turn+never reaches the missing attribute. The four failures were the assistant-content refusal Vercel+named in its own bytes, as first recorded.++## openhands, the review of PR #215 on hr-test (2026-09-19)++Reviewed on a derived image of the PR branch merged with main (0.19.0 plus #214 and #216), tmux+added to the image, every built-in skill installed as a fresh volume installs them. What the+review changed, each with the measurement that made it a defect.++**No served model and no usage on any turn.** The relay token lived only in the driver's argv;+`_relay_served_model` and `_relay_usage` find the turn's route by the placeholder bearer in the+turn's environment, so the record carried neither. The token now rides the environment as well.++**A conversation died after every deploy.** The agent's persisted spec carried the relay's+`base_url`, and the loopback relay binds a fresh port on every runner start: the first turn after+a restart dialled the old port (`Cannot connect to host 127.0.0.1:39265`). The base url rides the+environment like the key; measured across a swap, the follow-up answered from the history.++**A model switch was ignored.** The agent is frozen at the conversation's creation, its LLM spec+included, and the server offers no way to change it: a turn that asked for claude-sonnet-5 was+served gpt-5.4, the record naming the first and the relay the second. The turn's model is written+into the persisted state before the server loads the conversation, the same door the conversation+id uses; measured gpt-5.4, then claude-sonnet-5, then gpt-5.4 again, each served as asked. The+three muse switch failures in the first column (270-310 s of retries against a route that could+not serve the persisted id) were this.++**A disabled MCP tool was called.** The built-ins are withheld by omission from the spec; an MCP+tool is loaded from the server at agent start and was called all the same (`probe_sse` disabled,+its token in the answer). The SDK's own `filter_tools_regex` runs over every tool name after the+MCP tools are added; the disabled names are excluded there and are part of the conversation's+identity. Re-probed, the tool was not offered; the model then wrote its own SSE client in the+shell and dialled the public probe, which is the shell reaching a URL, the same reach `curl` has+on every base. The policy holds at the tool surface, as it does on kimi (Shell withheld, the+boot id read with the file tool) and here (Edit withheld, the file written with printf).++**A cancelled turn left its command running.** The terminal tool runs commands in tmux, whose+server daemonises with setsid, so the runner's process-group kill left the tmux server and the+agent's `sleep 240` alive and every turn's `/tmp/oh<port>` directory behind it (84 after an+hour). Every process a turn starts now carries `HR_TURN_ID` in its environment and the runner+sweeps what still carries it after the group kill, tmux directory included; the driver removes+its own on the normal path. And the directory is the turn's own (mkdtemp), not the port's: ports+are reused and turns run as different uids, and a directory left by an earlier turn answered+`Permission denied` on the next.++**litellm's own `max_tokens`.** For an id its registry knows as Anthropic's, the provider-native+`claude-haiku-4-5-20251001` a custom Anthropic connection resolves to, litellm sends both+`max_tokens` and `max_completion_tokens` (64,000 each) and Anthropic's OpenAI-compatible endpoint+refuses the pair. Captured with a sink inside the venv and against the live endpoint; every+other id carries the second field alone and every provider on the matrix takes it. The relay+drops the first on this backend's route, the kimi precedent.++**Retries in seconds.** The SDK's defaults (5 retries, 8 to 64 s waits) made a provider that+answered the same 503 every time a 270-310 s turn before the reason was reported. Two retries a+few seconds apart now, persisted with the agent.++**The driver's own ceiling.** An 1800 s deadline of the driver's own sat below the harness's+timeout (7200 s by default); it is the runner's global ceiling now, and a server that dies+mid-turn is noticed by asking the process rather than waiting it out.++**Cards.** The tool cards carried the SDK's registry names (`terminal`, `file_editor`,+`task_tracker`) and the raw observation record as JSON; they carry the catalog's names (Shell,+Edit, Todo), the action's arguments as the input and the observation's text as the output.++**In the default set**, for the reason aider is; the icon is OpenHands' own (MIT).++**The columns on the review image (`cand-a14761d`, hr-test, 2026-09-19).** Console scenario matrix,+50 ids × first / follow-up / switch / artifact / recycle, connections as the console routes them+(TokenRouter 38, Vercel 6, Anthropic 2, Custom OpenAI 2, Azure 1, OpenRouter 1):++```+first 50/50 follow-up 50/50 switch 49/50 artifact 49/50 recycle 49/50 = 247/250+```++The three: `gpt-5.4` on the switch to gpt-5.6-sol, TokenRouter's multi-account gpt-5 route+refusing a replayed encrypted reasoning item (the sentence the gateway already has for it);+`llama-3.3-70b` on the artifact after a switch, the server marking the conversation stuck once in+two runs (by hand it wrote the file in 24 s); `qwen3.8-27b` on the recycle recall, the model. The+first pass, on the branch as submitted plus the early fixes, was 237/246, and every miss between+the two was one of the defects above: the persisted model on the three muse switches, litellm's+`max_tokens` pair on claude-haiku through the Anthropic connection.++Plugin matrix 4/4 twice; `custom-harness.mjs` 4 of 5 (the miss the same encrypted-reasoning+refusal); conformance 75/75 alone against an openhands harness on gpt-5.4; fresh volume with+fourteen backends: the OpenHands venv installs in about a minute beside aider's. Cancel: nothing+of the turn survives the sweep. The agent doc reaches the model as context: asked, with no tool+allowed, for a secret word in the harness's instructions and the installed skills, it answered+both from the doc.diff --git a/gateway/app.py b/gateway/app.pyindex fdd75361..61d0bfb3 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -1082,6 +1082,15 @@ _INTEGRATION_WIRING: dict[tuple[str, str], str] = {("llmtr", "kimi"): "tokenrouter",("custom", "kimi"): "openai-api",("google", "kimi"): "openai-api",+ # openhands reaches every provider the same way: the driver points the agent-server's LLM at+ # the loopback relay, so whatever the relay fronts is what the agent talks to.+ ("anthropic", "openhands"): "anthropic", ("openai", "openhands"): "openai",+ ("azure-foundry", "openhands"): "azure",+ ("openrouter", "openhands"): "openai-api",+ ("tokenrouter", "openhands"): "tokenrouter", ("vercel", "openhands"): "tokenrouter",+ ("llmtr", "openhands"): "tokenrouter",+ ("custom", "openhands"): "openai-api",+ ("google", "openhands"): "openai-api",("anthropic", "qwen"): "anthropic", ("openai", "qwen"): "openai",("azure-foundry", "qwen"): "azure",("openrouter", "qwen"): "openai-api",@@ -1146,6 +1155,7 @@ _INTEGRATION_WIRING: dict[tuple[str, str], str] = {("harnessrouter", "opencode"): "tokenrouter", ("harnessrouter", "qwen"): "tokenrouter",("harnessrouter", "kimi"): "tokenrouter",("harnessrouter", "aider"): "tokenrouter",+ ("harnessrouter", "openhands"): "tokenrouter",("harnessrouter", "cline"): "tokenrouter", ("harnessrouter", "gemini"): "google",("harnessrouter", "goose"): "tokenrouter",}@@ -4611,7 +4621,8 @@ _CUSTOM_FORMAT_BACKENDS = {# OPENAI_BASE_PATH through the relay). Its own anthropic provider takes ANTHROPIC_HOST with no# base-path counterpart and is unprobed, so a custom ANTHROPIC endpoint stays off this set# until it is — the picker greys out what the router cannot actually run.- "openai": {"hermes", "opencode", "pi", "dsh", "qwen", "cline", "omp", "goose", "kimi", "aider"},+ "openai": {"hermes", "opencode", "pi", "dsh", "qwen", "cline", "omp", "goose", "kimi", "aider",+ "openhands"},"anthropic": {"claude", "opencode", "pi", "dsh", "omp"},# The OpenAI Responses API: what codex speaks, and only codex among the agent CLIs here."responses": {"codex"},@@ -6090,6 +6101,27 @@ _MODEL_CATALOG: dict[str, dict] = {"qwen3.8-flash", "qwen3.8-27b", "qwen3.7-max", "qwen3.7-plus", "glm-5.3","glm-5.3-flash", "mistral-medium-3.5", "step-3.7-flash", "hunyuan-4-preview","nemotron-3.5-lightning", "nemotron-3-super"]},+ # openhands: the same relay reach as kimi and qwen (litellm's openai provider through the+ # loopback relay), so the list is theirs. Measured 2026-09-18/19: the Vercel column ran 49 of+ # these ids (239 of 245 scenarios) and the Google column ran the eight gemini ids, so the list+ # is a measured one rather than an offered one. The id is sent with an `openai/` prefix by the+ # runner, which is load-bearing: without an explicit provider litellm infers one from the base+ # url, and a relay url inferred as Vercel produced `Missing credentials …+ # VERCEL_AI_GATEWAY_API_KEY` on a resumed turn.+ "openhands": {"default": "gpt-5.4",+ "models": [+ "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4",+ "gpt-5.4-mini", "gpt-5.2", "claude-fable-5-1", "claude-fable-5", "claude-opus-5",+ "claude-sonnet-5", "claude-opus-4.8", "claude-opus-4.7", "claude-sonnet-4.6",+ "claude-haiku-4.5", "gemini-3.8-flash", "gemini-3.7-flash", "gemini-3.6-flash",+ "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.1-pro-preview",+ "gemini-3.1-flash-lite", "gemini-3-flash-preview", "grok-4.6", "grok-4.5", "grok-4.3",+ "grok-4.20", "grok-build-0.1", "muse-spark-1.3", "muse-spark-1.2",+ "muse-spark-1.1", "muse-glimmer-30b", "llama-3.3-70b", "deepseek-v4.1-flash",+ "deepseek-v4-pro", "deepseek-v4-flash", "kimi-k3", "kimi-k2.7-code", "qwen3.8-max",+ "qwen3.8-flash", "qwen3.8-27b", "qwen3.7-max", "qwen3.7-plus", "glm-5.3",+ "glm-5.3-flash", "mistral-medium-3.5", "step-3.7-flash", "hunyuan-4-preview",+ "nemotron-3.5-lightning", "nemotron-3-super"]},"qwen": {"default": "qwen3.7-max","models": ["qwen3.7-max", "qwen3.8-max","gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5",@@ -6224,8 +6256,9 @@ RESPONSES_ONLY_MODELS = frozenset({"gpt-5.3-codex", "gpt-6-astra"})# kimi speaks chat/completions only: the runner defines its model with provider type `openai`# through the relay (Kimi Code CLI has an openai_responses type too, but it is not the one the runner# sets), so a Responses-API-only id would be a picker row that fails on send.-# aider speaks chat/completions through litellm's openai provider, so a Responses-API-only id-CHAT_ONLY_BACKENDS = ("qwen", "cline", "goose", "kimi", "aider")+# aider and openhands speak chat/completions through litellm's openai provider (the id is sent+# `openai/<id>`), so a Responses-API-only id would be a picker row that fails on send.+CHAT_ONLY_BACKENDS = ("qwen", "cline", "goose", "kimi", "aider", "openhands")_BARE_MODELS = {"", "claude", "codex", "anthropic", "bedrock", "openai", "hermes", "pi", "dsh", "deepseek", "omp"}# Models whose serving CHANNEL refuses image input outright. Measured, not assumed — probed# 2026-08-19 on the TokenRouter connection with a data-URI image in a user message:@@ -13399,6 +13432,30 @@ _BASE_CATALOG: dict[str, dict] = {# _KIMI_TOOLS tuple and the claim cannot drift into an overstatement."tool_enforcement": "hard",},+ "openhands": {+ "label": "OpenHands", "backend": "openhands", "status": "ready",+ # NOT delivered as a system prompt: the agent-server composes its own from the SDK's agent+ # definition and accepts no override, so these instructions reach the model through the+ # workspace's AGENTS.md, which its file tools read.+ "system_prompt": ("You are OpenHands, an autonomous coding agent. You work on a real git "+ "workspace with shell and file access, reading and editing files and "+ "running commands to complete the task end to end."),+ # The tools the runner gives the agent, by the names it gives them. Upstream's default+ # preset has a fourth, `browser_tool_set`, and it is NOT offered: it needs a Chromium this+ # image does not carry, and the server's own log says so (`Error preloading … Exception:+ # Chromium is …`). Listing a tool that cannot run is the overstatement UHP 4.3 forbids.+ "tools": [("Shell", "Shell"), ("Edit", "File Edit"), ("Todo", "Todo")],+ # "hard", and MEASURED with a control rather than asserted: on a fresh conversation with+ # Shell and Edit both withheld, "create a file and reply DONE" produced no file and NO TOOL+ # CALL AT ALL ("I don't currently have any filesystem or shell tool access"), while the same+ # request under the full list wrote the file through file_editor. Enforcement is by omission+ # from the agent's tool list — a tool the agent was never given cannot be called.+ #+ # ONE HONEST LIMIT, because a shell is a file writer: disabling Edit alone does not stop a+ # file from being written, since the agent reaches for `printf > file` instead. That is true+ # of every backend here that has a shell.+ "tool_enforcement": "hard",+ },"qwen": {"label": "Qwen Code", "backend": "qwen", "status": "ready","system_prompt": ("You are Qwen Code, an autonomous coding agent. You work on a real git "diff --git a/runner/openhands_driver.py b/runner/openhands_driver.pynew file mode 100644index 00000000..6bf3fdbc--- /dev/null+++ b/runner/openhands_driver.py@@ -0,0 +1,639 @@+"""One OpenHands turn, as a runner subprocess.++Spawned per turn by server.py, the same one-process-per-turn contract every other backend keeps:+the runner reads NDJSON off stdout and cancel is a process-group kill. Inside, this starts an+`openhands-agent-server` on loopback, drives ONE turn over its HTTP + WebSocket API, and exits.++WHY A SERVER AT ALL. The base runs OpenHands V1 through `openhands-agent-server`, the REST/WebSocket+interface its vendor maintains (OpenHands/agent-sdk). The CLI that used to be the obvious choice —+PyPI `openhands`, from OpenHands/openhands-cli — opens its README with "This project is no longer+actively maintained" and last released 1.16.0 on 2026-05-08. The agent server released 1.49.2 on+2026-09-17.++WHY ONE SERVER PER TURN rather than one resident server. Measured on the pinned 1.49.2: cold start+to a serving `/alive` is 3.3-4.1 s, and a conversation created by one server process is read back+intact by a DIFFERENT process on a different port over the same on-disk store (verified by killing+the first and querying the second). That is what makes the per-turn shape work at all, and it is+the shape this product needs: sandboxes are recycled between turns, so a resident server would hold+conversation state for workspaces that no longer exist. The cost is that 3.7 s on every turn.++The event protocol is dsh_driver's: one {"m": method, "p": payload} JSON object per line on stdout,+normalised by _openhands_to_claude in server.py.+"""+from __future__ import annotations++import contextlib+import json+import os+import pathlib+import re+import secrets+import shutil+import signal+import socket+import subprocess+import sys+import tempfile+import time+import urllib.error+import urllib.request+import uuid++_T0 = time.time()++def _conversation_id(tools: list[str], mcp: dict | None = None, withheld: list[str] | None = None) -> str:+ """The conversation id the runner MINTS, for aider's and goose's reason: it has to be+ reproducible from the workspace alone after a sandbox recycle. The API takes `conversation_id`+ on the create call (a request field, not a server-assigned one), so a uuid5 is all it takes — a+ uuid rather than a name because the field is typed `uuid.UUID`.++ THE TOOL POLICY IS PART OF THE IDENTITY, and that is not decoration. The agent is frozen at the+ conversation's FIRST creation: measured on 1.49.2, a second create for the same id carrying+ `tools: []` left the persisted agent holding `['terminal', 'file_editor']` and the turn wrote+ its file anyway, and there is no endpoint that updates an agent (`PATCH /conversations/{id}` is+ metadata — "like title"). Keying the id on the policy means a changed policy is a new+ conversation, created with the tools it asks for. The cost is that changing the policy starts a+ new thread; the alternative is running with a tool the operator has since disabled, which is the+ overstatement UHP 4.3 forbids and the direction this must never fail in.++ The declared MCP servers are in the key for the same reason: they are part of the agent, and an+ agent that cannot be updated cannot learn about a server added after it was made.+ """+ # The withheld MCP tool names are part of the identity for the same reason the tool list is:+ # the filter is a property of the frozen agent.+ return str(uuid.uuid5(uuid.NAMESPACE_URL,+ "https://harnessrouter.dev/openhands/harness?tools=" + ",".join(tools)+ + "&mcp=" + ",".join(sorted(mcp or {}))+ + "&withheld=" + ",".join(sorted(withheld or []))))+++def _emit(method: str, payload) -> None:+ sys.stdout.write(json.dumps({"m": method, "p": payload}, default=str) + "\n")+ sys.stdout.flush()+++def _free_port() -> int:+ """A port the kernel just handed out and nobody else holds. Bound and released rather than+ guessed, because turns of different sessions run side by side on one host."""+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:+ s.bind(("127.0.0.1", 0))+ return int(s.getsockname()[1])+++def _write_config(home: pathlib.Path, api_key: str) -> pathlib.Path:+ """The server's own config file, per turn.++ Every path is pointed under .harness/openhands/ so the conversation store travels in the+ checkpoint (and is excluded from produced files by the `.harness/` prefix), and VSCODE IS OFF:+ it defaults to on and binds port 8001, which one process per turn would collide on immediately.+ """+ cfg = {+ "session_api_keys": [api_key],+ "conversations_path": str(home / "conversations"),+ "workspace_path": str(home / "project"),+ "bash_events_dir": str(home / "bash_events"),+ "enable_vscode": False,+ # Tool preloading is Chromium preloading — the service's own docstring is "Service which+ # preloads chromium", and its start() constructs a BrowserToolExecutor. This image carries+ # no Chromium and this backend offers no browser tool, so on every server start it does the+ # work and then fails (`Error preloading … Exception: Chromium is …` in the server's log).+ # One server per turn means paying for that failure once per turn.+ "preload_tools": False,+ "allow_cors_origins": [],+ }+ path = home / "agent-server-config.json"+ path.write_text(json.dumps(cfg, indent=2))+ return path+++# The phase the driver is in, so a socket timeout says WHICH wait ended rather than just+# `TimeoutError: timed out` — four calls here can raise that exact exception with that exact+# message, and a reason that does not separate them is a reason nobody can act on. Measured on+# vercel|openhands|claude-sonnet-4.6, whose recycle failed in 250 s saying only "timed out".+_STEP = "starting"+++def _req(url: str, key: str, method: str = "GET", body: dict | None = None, timeout: float = 30.0):+ data = json.dumps(body).encode() if body is not None else None+ r = urllib.request.Request(url, data=data, method=method,+ headers={"X-Session-API-Key": key,+ "content-type": "application/json"})+ with urllib.request.urlopen(r, timeout=timeout) as resp:+ raw = resp.read().decode(errors="replace")+ return json.loads(raw) if raw.strip() else None+++# `AttributeError: 'X' object has no attribute 'y'` — the shape of the one line worth keeping out+# of a rich-framed traceback. Anchored at the start of the stripped line so a mention inside a log+# message does not win over the exception itself.+_EXC_LINE = re.compile(r"^[A-Za-z_][\w.]*(?:Error|Exception)\b\s*:")+# `[09/19/26 03:27:05] INFO …`, and the bare `INFO`/`ERROR` continuation rich writes under it: a+# new record, never the wrapped remainder of an exception message.+_LOG_LINE = re.compile(r"^\[\d\d/\d\d/\d\d |^(?:INFO|ERROR|WARNING|DEBUG)\s")+++def _exc_text(lines: list[str], i: int) -> str:+ """One exception line plus the continuation of its message, and nothing after that.++ rich wraps a long message onto the next lines and then draws the next frame or writes its next+ record, so the stop condition is the box-drawing, the chaining sentence and a new log line.+ Taking a fixed three lines instead put `The above exception was … ╭────` behind one reason and+ the `SIGTERM … Shutting down` noise behind the other; both were caught by the tests below."""+ out = [lines[i].strip()]+ for ln in lines[i + 1:i + 4]:+ t = ln.strip()+ if (not t or t[0] in "╭╰│─" or _LOG_LINE.match(t) or _EXC_LINE.match(t)+ or t.startswith(("The above exception", "During handling"))):+ break+ out.append(t)+ return " ".join(out)+++def _log_tail(path: pathlib.Path, limit: int = 1200) -> str:+ """Why the server failed, taken from what it wrote; its last lines only as a fallback.++ THE LAST LINES ARE USUALLY THE WRONG ONES. A turn that dies at second 3 and is then retried to+ exhaustion is terminated at second 190, so by the time this is read the tail of the file is+ `Received signal SIGTERM … Shutting down … Application shutdown complete` and the sentence that+ explains the failure is three minutes above it. Measured: the first version of this function+ put exactly that shutdown noise into the record, which is worse than the silence it replaced,+ because it reads like a reason. So the exception lines are looked for first."""+ try:+ text = path.read_text(errors="replace")+ except OSError:+ return ""+ lines = [ln for ln in text.splitlines() if ln.strip()]+ # BOTH ENDS OF THE CHAIN, because neither alone is the answer. A chained traceback prints the+ # root cause first and the exception that wrapped it last, so reading from the end returns+ # `ConversationRunError: Conversation run failed for id=…` — true, and useless — while the+ # sentence that names the defect is the first one. Reporting the pair costs one line and+ # survives a chain in either direction.+ found = [_exc_text(lines, i) for i, ln in enumerate(lines) if _EXC_LINE.match(ln.strip())]+ if found:+ out = found[0] if len(found) == 1 or found[-1] == found[0] else f"{found[0]} … {found[-1]}"+ return out[:limit]+ return " | ".join(lines[-12:])[-limit:]+++def _wait_alive(port: int, proc: subprocess.Popen, deadline: float) -> bool:+ """/alive needs no key and answers as soon as the app is mounted; measured 0.03 s ahead of the+ first authenticated call, so there is no second readiness gate worth waiting on."""+ while time.time() < deadline:+ if proc.poll() is not None:+ return False+ try:+ with urllib.request.urlopen(f"http://127.0.0.1:{port}/alive", timeout=2):+ return True+ except (urllib.error.URLError, OSError):+ time.sleep(0.1)+ return False+++def _agent_spec(job: dict) -> dict:+ """The agent, with NO CREDENTIAL IN IT. The key travels in the server's environment instead.++ MEASURED, and this is the whole reason for the shape: the conversation state persisted to disk+ carries the entire LLM spec — model, base_url, retries, timeouts — and `api_key: None`. The+ server keeps no key at rest, exactly as its docs claim. So a key passed here reaches the first+ turn and NOTHING after it: a later turn's server rebuilds the agent from that state, has no+ credential, and litellm's own retry/backoff then hides the failure for two minutes before the+ conversation lands in `error` with+ `Vercel_ai_gatewayException - Missing credentials. Please pass an api_key…`. Re-POSTing the+ create call with the agent does not fix it either; the history survives, the credential does not.++ Passing it in the environment makes it a property of THIS turn's process, which every turn sets+ afresh, so resume needs nothing persisted. `usage_id` names the row this turn's spend lands on+ and is not sent to the provider.+ """+ tools = [{"name": n} for n in _tools(job)]+ # MCP TOOLS ARE WITHHELD BY NAME TOO. The built-ins are omitted from the spec above; an MCP+ # tool is loaded from the server at agent start and is not in that list, so a disabled one+ # was called all the same (measured: probe_sse disabled, called, its token in the answer).+ # The SDK's own filter is a regex over every tool name after the MCP tools are added+ # (Agent.filter_tools_regex, base.py:153); a negative lookahead over the disabled names, the+ # bare name and the `server_tool` spelling a client may expose, is that filter.+ filter_regex = _filter_regex(_withheld_mcp(job))+ # NO BASE URL IN IT EITHER. The spec is persisted with the conversation, and the base url is+ # the loopback relay's, which binds a fresh port on every runner start: a conversation created+ # before a restart dialled the old port on its next turn and died on `Cannot connect to host+ # 127.0.0.1:39265` (hr-test, 2026-09-19, the first turn after a deploy). litellm reads+ # OPENAI_BASE_URL from the environment when the spec carries none, and the driver sets it for+ # this turn's server the way it sets the key, so every turn dials the relay it was given.+ # RETRIES BOUNDED IN SECONDS, NOT MINUTES. The SDK's defaults (5 retries, 8 s minimum wait,+ # 64 s maximum, multiplier 8) turn a provider that answers the same 503 every time into a+ # 270-310 s turn before the reason is reported (three switch scenarios, hr-test 2026-09-19);+ # every other base surfaces the same refusal in seconds. Two retries a few seconds apart+ # still cover a blip. Persisted with the agent like the rest of the spec.+ spec: dict = {"llm": {"model": job["model"], "base_url": None, "usage_id": "harness",+ "num_retries": 2, "retry_min_wait": 2, "retry_max_wait": 8,+ "retry_multiplier": 2},+ "tools": tools,+ # THE AGENT DOC IS CONTEXT, NOT A FILE THE MODEL MAY OR MAY NOT OPEN. The SDK+ # loads the workspace's AGENTS.md (and .agents/skills/) as repo skills only when+ # asked (AgentContext.load_project_skills, False by default), and it reads them+ # afresh on each server's first run, so every turn sees the harness's current+ # instructions, workspace contract and skills block. Without this the doc reached+ # the model only when it chose to `cat AGENTS.md` (it did in the smoke turns; a+ # model that does not never learns where deliverables go or which skills exist).+ "agent_context": {"load_project_skills": True}}+ # The declared MCP servers ride the agent itself — the SDK dials them, so this base needs no+ # bridge of its own. Sent only when there ARE servers: the agent is frozen at creation, and an+ # empty mcp_config is not the same statement as none.+ if job.get("mcp_config"):+ spec["mcp_config"] = job["mcp_config"]+ if filter_regex:+ spec["filter_tools_regex"] = filter_regex+ return spec+++def _withheld_mcp(job: dict) -> list[str]:+ """The disabled names that are not built-in tools: MCP tools, withheld by the SDK's filter."""+ return sorted({str(x) for x in (job.get("tools_disabled") or [])+ if str(x) not in _TOOL_NAMES and str(x) not in _TOOLS})+++def _filter_regex(disabled: list[str]) -> str:+ """A regex that admits every tool name except the disabled ones: the bare name, and the+ `<server>_<name>` and `<server>.<name>` spellings under which a client may expose an MCP+ tool. Empty when nothing is disabled, so the spec carries no filter at all."""+ names = [d.strip() for d in disabled if d and d.strip()]+ if not names:+ return ""+ alts = []+ for n in names:+ e = re.escape(n)+ alts.append(f"{e}$")+ alts.append(f"[^\\s]+[._]{e}$")+ return "^(?!(?:" + "|".join(alts) + "))"+++# The tools this base gives the agent, by the names openhands-tools registers. An agent created+# without this list gets NONE — measured: asked to write a file it answered "I can't create files in+# this environment because no filesystem tool is available".+#+# `browser_tool_set` is in upstream's default preset and is deliberately NOT here: it needs a+# Chromium this image does not carry, and its absence already shows up as `Error preloading …+# Exception: Chromium is …` in the server's own log. A tool that cannot run is not offered.+_TOOLS = ("terminal", "file_editor", "task_tracker")+# What the console calls them. The catalog lists the console names; the disable list arrives in+# those, and enforcement is by OMISSION from the agent's tool list, which is as hard as it gets:+# a tool the agent was never given cannot be called.+_TOOL_NAMES = {"Shell": "terminal", "Edit": "file_editor", "Todo": "task_tracker"}+++_CONSOLE_NAMES = {v: k for k, v in _TOOL_NAMES.items()}+++def _action_input(action: dict) -> dict:+ """The action's arguments as the card's input: the SDK's `kind` and bookkeeping fields dropped,+ a terminal action's command under `command` as every other base's shell card carries it."""+ return {k: v for k, v in action.items()+ if k not in ("kind", "thought", "security_risk", "summary") and v not in (None, "", [], {})}+++def _observation_text(obs: dict) -> str:+ """What the tool returned, as text: the observation's text blocks joined, the way the SDK's own+ visualiser reads them. The raw observation is a typed record (kind, content blocks with+ cache flags, the command, exit codes); rendered whole it put JSON on every result card."""+ parts = []+ for block in obs.get("content") or []:+ if isinstance(block, dict) and block.get("type") == "text":+ parts.append(str(block.get("text") or ""))+ text = "\n".join(p for p in parts if p)+ if text:+ return text+ return json.dumps({k: v for k, v in obs.items() if k != "content"}, default=str)+++def _tools(job: dict) -> list[str]:+ off = {str(x) for x in (job.get("tools_disabled") or [])}+ off |= {_TOOL_NAMES[x] for x in off if x in _TOOL_NAMES}+ return [t for t in _TOOLS if t not in off]+++def _set_turn_model(home: pathlib.Path, cid: str, model: str) -> bool:+ """The turn's model, written into the persisted agent before the server loads it.++ The agent is frozen at the conversation's creation, its LLM spec included, and the server+ offers no way to change it: a task that switched models kept calling the first one, the+ record saying claude-sonnet-5 while the relay served gpt-5.4 (hr-test, 2026-09-19). The+ conversation's store is a JSON file in this workspace that the server reads on first access,+ so the model rides the same door the conversation id does: the file is patched, then the+ server is asked. Only the model field changes; nothing else of the agent is touched."""+ path = home / "conversations" / cid.replace("-", "") / "base_state.json"+ try:+ doc = json.loads(path.read_text())+ except (OSError, ValueError):+ return False+ llm = (doc.get("agent") or {}).get("llm")+ if not isinstance(llm, dict) or llm.get("model") == model:+ return False+ llm["model"] = model+ path.write_text(json.dumps(doc))+ return True+++def _conversation(base: str, key: str, job: dict, cwd: str) -> tuple[str, bool]:+ """This turn's conversation: the minted id if the store already holds it, else created with it.++ Asking first is the goose lesson the 2026-09-13 decision generalised — the store answers whether+ the conversation is there, and the harness never infers it from its own argv.+ """+ cid = _conversation_id(_tools(job), job.get("mcp_config") or {}, _withheld_mcp(job))+ # before the server is asked, since it loads the conversation on first access+ _set_turn_model(pathlib.Path(cwd, ".harness", "openhands"), cid, job["model"])+ try:+ info = _req(f"{base}/api/conversations/{cid}", key)+ if info and info.get("id"):+ return cid, True+ except urllib.error.HTTPError as e:+ if e.code != 404:+ raise+ body: dict = {"conversation_id": cid,+ "workspace": {"working_dir": cwd},+ "agent": _agent_spec(job)}+ # THE OPERATOR'S STEP BUDGET. The server's own default is 500 iterations per run; a budget the+ # caller set and the backend ignored is the quiet lie this repo treats as a defect (kimi shipped+ # that bug at 1000 steps and turns ran for hours).+ budget = job.get("max_turns")+ if budget:+ body["max_iterations"] = max(1, int(budget))+ _req(f"{base}/api/conversations", key, method="POST", body=body, timeout=120)+ return cid, False+++# What a turn's end looks like on the wire. The server reports execution status as an EVENT+# (ConversationStateUpdateEvent), so one WebSocket carries both the content and the terminal+# signal and nothing has to poll the conversation alongside it.+_TERMINAL = {"finished", "error", "stuck", "idle"}+_FAILED = {"error", "stuck"}+++def _text_of(content) -> str:+ """A Message's content is a list of typed blocks; only text blocks are prose."""+ if isinstance(content, str):+ return content+ parts = []+ for block in content or []:+ if isinstance(block, dict) and block.get("type") == "text":+ parts.append(str(block.get("text") or ""))+ elif isinstance(block, str):+ parts.append(block)+ return "".join(parts)+++def _on_event(ev: dict, state: dict) -> None:+ """One SDK event -> zero or more NDJSON lines.++ Only the shapes this product renders are translated. StreamingDeltaEvent is deliberately NOT:+ the final MessageEvent carries the same text whole, and emitting both would render the answer+ twice.+ """+ kind = str(ev.get("kind") or ev.get("type") or "")+ if kind == "MessageEvent":+ msg = ev.get("llm_message") or ev.get("message") or {}+ if str(msg.get("role") or "") == "assistant":+ text = _text_of(msg.get("content"))+ if text.strip():+ state["final"] = text+ _emit("text", {"text": text})+ elif kind == "ActionEvent":+ action = ev.get("action") or {}+ if str(action.get("kind") or "") == "FinishAction":+ # How a turn ENDS when the agent has tools: the answer rides the finish action rather+ # than a trailing assistant message (measured — turns that answer in prose alone emit a+ # MessageEvent and no finish, so both paths are real). Rendering it as a tool call would+ # show the user a "finish" step and leave the turn with no answer at all.+ text = str(action.get("message") or "")+ if text.strip():+ state["final"] = text+ _emit("text", {"text": text})+ return+ tuid = str(ev.get("tool_call_id") or ev.get("id") or len(state.setdefault("calls", [])))+ state.setdefault("calls", []).append(tuid)+ state["last_call"] = tuid+ # The console's names for the tools, the ones the catalog lists and the policy is written+ # in; the SDK's registry names (terminal, file_editor, task_tracker) are the wire.+ name = str(ev.get("tool_name") or "Tool")+ action = ev.get("action") or {}+ card = _CONSOLE_NAMES.get(name, name)+ # the file editor's `view` is a read, not an edit: the console counts Edit cards as+ # files edited ("Edited 3 files" for one file created and two looked at)+ if name == "file_editor" and str(action.get("command") or "") == "view":+ card = "Read"+ _emit("tool_call", {"id": tuid, "name": card, "input": _action_input(action)})+ elif kind == "ObservationEvent":+ obs = ev.get("observation") or {}+ if str(obs.get("kind") or "") == "FinishObservation":+ # Its action was suppressed above, so rendering this would leave an orphan tool result+ # under a call id the transcript never showed. Measured in a real artifact turn.+ return+ tuid = str(ev.get("tool_call_id") or state.get("last_call") or "t0")+ _emit("tool_result", {"id": tuid, "output": _observation_text(obs),+ "is_error": bool(obs.get("is_error"))})+ elif kind in ("AgentErrorEvent", "ConversationErrorEvent"):+ # A REAL failure. Recorded, not rendered: it is the turn's reason, not part of its answer.+ #+ # READ code AND detail. This event carries neither `error` nor `message` — its fields are+ # `code` ("LLMServiceUnavailableError") and `detail`, which is where litellm puts the+ # provider's own sentence — so an extraction that read only `error`/`message` fell through+ # to the EVENT CLASS NAME and recorded that as the turn's reason. Three investigations here+ # began by opening the server's log for a sentence the record should already have carried.+ detail = str(ev.get("detail") or ev.get("error") or ev.get("message") or "")+ code = str(ev.get("code") or "")+ state["reported_error"] = True+ _emit("error", {"text": (f"{code}: {detail}" if code and detail+ else detail or code or kind)[:1500]})+ elif kind == "ConversationStateUpdateEvent":+ # The event is a generic key/value state update — `last_user_message_id` rides the same+ # shape — so the KEY has to be checked. Reading `value` alone once set the status to a+ # message uuid, which only failed to end the turn early because a uuid is not a status.+ if str(ev.get("key") or "") == "execution_status":+ value = ev.get("value")+ if isinstance(value, str) and value:+ state["status"] = value.lower()+++def _run_turn(base: str, ws_base: str, key: str, cid: str, prompt: str, state: dict,+ max_seconds: float, proc: subprocess.Popen | None = None) -> None:+ """Send the message and read the conversation's events until the turn ends.++ The WebSocket is opened BEFORE the message is sent: the run starts the moment the POST lands,+ and a socket opened afterwards would miss whatever the agent did first.+ """+ from websockets.sync.client import connect++ url = f"{ws_base}/sockets/events/{cid}"+ # KEEPALIVE OFF. The client library pings every 20 s and closes the socket when a pong does not+ # come back in time; measured on a resumed conversation, that fired mid-turn and the turn died+ # with `sent 1011 (internal error) keepalive ping timeout` after 178 s with no answer. Nothing+ # here needs the client to prove the link: the server pushes, and this loop already has its own+ # deadline. A liveness check that ends healthy turns is worse than no liveness check.+ global _STEP+ _STEP = "opening the event socket"+ with connect(url, additional_headers={"X-Session-API-Key": key},+ open_timeout=30, close_timeout=5, ping_interval=None) as ws:+ _STEP = "sending the message"+ _req(f"{base}/api/conversations/{cid}/events", key, method="POST",+ body={"role": "user", "content": [{"type": "text", "text": prompt}], "run": True},+ timeout=60)+ _STEP = "reading the conversation's events"+ deadline = time.time() + max_seconds+ while time.time() < deadline:+ try:+ raw = ws.recv(timeout=max(1.0, min(30.0, deadline - time.time())))+ except TimeoutError:+ # a server that died leaves the socket silent, not closed; asking the process is+ # what tells a dead server from a long tool call+ if proc is not None and proc.poll() is not None:+ state["server_died"] = True+ return+ continue+ try:+ ev = json.loads(raw)+ except (TypeError, ValueError):+ continue+ if isinstance(ev, dict):+ _on_event(ev, state)+ if state.get("status") in _TERMINAL and state.get("sent"):+ return+ # the run is only over once it has started: the status is `idle` until the first+ # step lands, and returning on that would end the turn before it began+ if state.get("status") == "running":+ state["sent"] = True+ state["timeout"] = True+++def main() -> int:+ job = json.loads(sys.argv[1])+ cwd = job.get("cwd") or os.getcwd()+ os.chdir(cwd)+ home = pathlib.Path(cwd, ".harness", "openhands")+ home.mkdir(parents=True, exist_ok=True)++ key = secrets.token_urlsafe(24)+ port = _free_port()+ cfg = _write_config(home, key)++ env = dict(os.environ)+ env["OPENHANDS_AGENT_SERVER_CONFIG_PATH"] = str(cfg)+ # THE PROVIDER CREDENTIAL, and the only place it lives (see _agent_spec). The id is sent with an+ # `openai/` prefix by the builder so litellm routes through its openai provider verbatim instead+ # of INFERRING one from the base url — the inference is what produced `Vercel_ai_gatewayException+ # … set the VERCEL_AI_GATEWAY_API_KEY`, a provider-specific variable nothing here would set.+ if job.get("api_key"):+ env["OPENAI_API_KEY"] = str(job["api_key"])+ if job.get("base_url"):+ env["OPENAI_BASE_URL"] = str(job["base_url"])+ # The SDK prints a multi-line banner to STDOUT on import, which is this driver's NDJSON channel+ # for the server's own process; off by its own switch rather than by filtering lines.+ env["OPENHANDS_SUPPRESS_BANNER"] = "1"+ # The server logs through rich, which sizes itself to COLUMNS when it has no tty and defaults+ # to 80 — and a traceback panel inside an 80-wide log line leaves a message column about 27+ # characters across, so the one sentence worth reading arrives cut into six pieces. The tail+ # this driver attaches to a reasonless failure is only worth attaching if it is legible.+ env["COLUMNS"] = "200"+ # THE TURN DIES WITHOUT THIS, and the reason is a unix socket path limit rather than anything+ # about agents. The terminal tool runs commands in tmux, and tmux's socket lives under+ # TMUX_TMPDIR — which the server defaults to a directory INSIDE the working directory+ # ("TMUX_TMPDIR not set; defaulting to per-server tmux directory", api.py). A workspace here is+ # /data/workspaces/hsess<32 hex>, so the socket lands at+ # /data/workspaces/hsess…/tmp/openhands-agent-server-<pid>/tmux-<uid>/openhands+ # at 106 characters, against the 108-byte sun_path limit — and tmux answers+ # `LibTmuxException: new-session: error connecting to … (File name too long)`. The agent then+ # retries the tool it cannot start, which is what turned a 10 s turn into 235 s and then into+ # 4,000 s. Measured through the gateway; a driver run from a short cwd never sees it.+ # A directory of THIS turn's own, not one named for the port: ports are reused, turns run+ # as different uids, and a directory left by an earlier turn on the same port answered+ # `couldn't create directory /tmp/oh58657/tmux-20167 (Permission denied)` (hr-test,+ # 2026-09-19). mkdtemp makes a fresh one owned by this uid; the name stays short for the+ # socket path limit above, and starts with /tmp/oh so the runner's sweep recognises it.+ env["TMUX_TMPDIR"] = tempfile.mkdtemp(prefix="oh", dir="/tmp")++ python = os.environ.get("HR_OPENHANDS_PYTHON", sys.executable)+ # The server's own output goes to a FILE, not to a pipe and not to nothing. A pipe nobody+ # drains fills its buffer and blocks the server mid-turn; DEVNULL throws away the one place a+ # 500 explains itself. Kept under .harness/ so it is neither a produced file nor a thing the+ # user sees, and its tail rides any failure this driver reports.+ logf = home / "agent-server.log"+ proc = subprocess.Popen(+ [python, "-m", "openhands.agent_server", "--host", "127.0.0.1", "--port", str(port)],+ cwd=cwd, env=env, stdout=logf.open("wb"), stderr=subprocess.STDOUT,+ start_new_session=False)++ base, ws_base = f"http://127.0.0.1:{port}", f"ws://127.0.0.1:{port}"+ state: dict = {}+ tail_before_stop = ""+ try:+ global _STEP+ _STEP = "waiting for the agent-server to answer /alive"+ if not _wait_alive(port, proc, time.time() + 120):+ _emit("error", {"text": f"agent-server did not start: {_log_tail(logf) or 'no output'}"})+ _emit("result", {"final": "", "ok": False, "seconds": round(time.time() - _T0, 2)})+ return 1+ _STEP = "opening the conversation"+ cid, resumed = _conversation(base, key, job, cwd)+ _emit("init", {"model": job["model"], "conversation_id": cid, "resumed": resumed})+ _STEP = "running the turn"+ # No cap of this driver's own below the runner's: the runner kills the turn at the+ # harness's timeout (7200 s by default, up to MAX_TURN_SECONDS), and a second, lower+ # ceiling here ended a legitimate long turn as "timed out" while the operator's setting+ # said otherwise. The value is the runner's global ceiling, so this loop only ends what+ # the runner would have ended anyway.+ _run_turn(base, ws_base, key, cid, job["prompt"], state,+ float(os.environ.get("HR_OPENHANDS_TURN_SECONDS", "21600")), proc=proc)+ except Exception as exc: # noqa: BLE001 — the reason belongs in the record, not in a traceback+ tail = _log_tail(logf)+ _emit("error", {"text": f"{type(exc).__name__}: {exc} (while {_STEP})"+ + (f" — agent-server said: {tail}" if tail else "")})+ finally:+ # THE LOG IS READ BEFORE THE SERVER IS STOPPED. Read after, its last lines are the+ # shutdown (`Received signal SIGTERM … shutting down`), which the reasonless-failure+ # fallback below then reported as the reason (llama-3.3-70b, hr-test 2026-09-19: a+ # conversation the server marked stuck was recorded as "websocket disconnected … SIGTERM").+ tail_before_stop = _log_tail(logf)+ with contextlib.suppress(Exception):+ proc.send_signal(signal.SIGTERM)+ proc.wait(timeout=10)+ with contextlib.suppress(Exception):+ proc.kill()+ # the turn's tmux socket directory, on the normal path; a killed turn's is removed by+ # the runner's sweep, which finds it through the marker the tmux server carries+ with contextlib.suppress(Exception):+ subprocess.run(["tmux", "-L", "openhands", "kill-server"], env=env, timeout=5,+ stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)+ shutil.rmtree(env["TMUX_TMPDIR"], ignore_errors=True)++ status = state.get("status") or ""+ ok = (bool(state.get("final")) and status not in _FAILED and not state.get("timeout")+ and not state.get("server_died"))+ if state.get("server_died") and not state.get("reported_error"):+ _emit("error", {"text": "agent-server exited mid-turn: " + (tail_before_stop or "no output")})+ state["reported_error"] = True+ if status in _FAILED and not state.get("reported_error"):+ # The server's own verdict on the conversation is the reason, in its word: `stuck` is+ # the agent repeating itself past the server's detector, `error` a run that ended in one.+ # The log's exception line rides along when there is one; the shutdown noise never.+ exc_line = tail_before_stop if _EXC_LINE.match((tail_before_stop or "").strip()) else ""+ _emit("error", {"text": f"the agent-server marked the conversation {status}"+ + (f": {exc_line}" if exc_line else "")})+ state["reported_error"] = True+ if not ok and not state.get("reported_error"):+ # A FAILED TURN CAN CARRY NO REASON AT ALL, and that is the server's design rather than a+ # gap here: event_service publishes an error event only for an exception that is NOT a+ # ConversationRunError, on the assumption that run()/arun() already emitted its own — and an+ # exception raised out of arun's error handling is precisely the case where nobody did. The+ # status flips to error and the websocket carries nothing else. Measured on the google+ # column, where every gemini follow-up died of `AttributeError:+ # 'PromptTokensDetailsWrapper' object has no attribute 'cache_creation_tokens'`, a sentence+ # that reached the server's log and no other place, leaving the record to say only "the+ # turn ended error" for eleven scenarios across five models.+ if tail_before_stop:+ _emit("error", {"text": f"agent-server said: {tail_before_stop}"})+ _emit("result", {"final": state.get("final") or "", "ok": ok, "status": status,+ "seconds": round(time.time() - _T0, 2)})+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/runner/server.py b/runner/server.pyindex 634ee55f..167ffbd7 100644--- a/runner/server.py+++ b/runner/server.py@@ -286,12 +286,26 @@ def _goose_session_present(cwd: str, cmd: list[str], session_id: str) -> bool:## A backend absent from this table cannot lose a session, or has not been measured — either way it# never reports one lost. Adding a backend here is registration point 5.+def _openhands_session_present(cwd: str, cmd: list[str], session_id: str) -> bool:+ """Ask the agent-server's own store whether this conversation is there.++ It cannot be read off argv: the driver mints the id and passes it whatever the store holds, and+ the server creates a conversation for an id it does not know. The store is a directory named for+ the id with the dashes removed, holding base_state.json and an events log — the shape the driver+ read back after killing one server and querying another."""+ home = pathlib.Path(cwd) / ".harness" / "openhands" / "conversations"+ if not home.is_dir():+ return False+ return any((d / "base_state.json").is_file() for d in home.iterdir() if d.is_dir())++_SESSION_PRESENT = {"claude": _argv_session_present,"opencode": _argv_session_present,"goose": _goose_session_present,"kimi": _argv_session_present,"aider": _aider_session_present,+ "openhands": _openhands_session_present,}@@ -459,6 +473,7 @@ OMP_DEFAULT_MODEL = os.environ.get("OMP_DEFAULT_MODEL", "gpt-5.4")GOOSE_DEFAULT_MODEL = os.environ.get("GOOSE_DEFAULT_MODEL", "gpt-5.4")KIMI_DEFAULT_MODEL = os.environ.get("KIMI_DEFAULT_MODEL", "kimi-k3")AIDER_DEFAULT_MODEL = os.environ.get("AIDER_DEFAULT_MODEL", "gpt-5.4")+OPENHANDS_DEFAULT_MODEL = os.environ.get("OPENHANDS_DEFAULT_MODEL", "gpt-5.4")CODEX_REASONING_EFFORT = os.environ.get("CODEX_REASONING_EFFORT", "medium")# The window Codex plans compaction against. Its own catalog says 272k for every gpt-5.x; a larger# number here made it compact late and let a long thread overflow the real window first.@@ -1214,7 +1229,7 @@ def _agent_doc_path(cwd: str, backend: str) -> pathlib.Path:# aider has no instruction-file convention of its own (no AGENTS.md discovery, no# CLAUDE.md): the file is written here and the driver puts it into aider's system message."AGENTS.md" if backend in ("codex", "hermes", "pi", "dsh", "opencode", "cline", "omp",- "goose", "kimi", "aider")+ "goose", "kimi", "aider", "openhands")else "CLAUDE.md")@@ -2811,6 +2826,36 @@ def _stringify_tool_content(body: bytes) -> bytes:return body+def _stringify_assistant_content(body: bytes) -> bytes:+ """Assistant-role message content: array-of-parts -> plain string, in one chat-completions body.++ The tool-role twin above, one role over. OpenAI accepts both shapes and the OpenHands SDK sends+ the array form for every assistant turn it replays, which Vercel's mistral endpoint refuses —+ and refuses MISLEADINGLY: `400 Assistant message must have either content or tool_calls, but+ not none.` about a message whose content is right there. Isolated against the live endpoint+ (2026-09-18): the identical request answers 200 with `content: "M1"` and 400 with+ `content: [{"type": "text", "text": "M1"}]`.++ It only bites once a conversation HAS an assistant turn, so a first turn passes and every one+ after it fails — which is exactly how it presented, four of five scenarios on+ vercel|openhands|mistral-medium-3.5. Text parts are all an assistant message carries here, so+ the flatten is lossless; applied only after a provider says exactly that."""+ try:+ obj = json.loads(body)+ changed = False+ for m in obj.get("messages") or []:+ if (isinstance(m, dict) and m.get("role") == "assistant"+ and isinstance(m.get("content"), list)):+ m["content"] = "".join(p.get("text", "") for p in m["content"]+ if isinstance(p, dict))+ changed = True+ if changed:+ return json.dumps(obj, separators=(",", ":")).encode()+ except Exception: # noqa: BLE001 — a body we cannot parse is a body we must not alter+ pass+ return body++def _set_reasoning_effort_none(body: bytes) -> bytes:"""Set `reasoning_effort: "none"` in one chat-completions body.@@ -3370,6 +3415,8 @@ class _HermesRelayHandler(http.server.BaseHTTPRequestHandler):body = _rename_max_tokens(body)if flags.get("stringify_tool_content"):body = _stringify_tool_content(body)+ if flags.get("stringify_assistant_content"):+ body = _stringify_assistant_content(body)if flags.get("drop_stream_options"):body = _drop_stream_options(body)if flags.get(f"reasoning_effort_none:{_body_model}"):@@ -3415,6 +3462,14 @@ class _HermesRelayHandler(http.server.BaseHTTPRequestHandler):body = stringifiedheaders["content-length"] = str(len(body))continue+ assistant = _stringify_assistant_content(body) if body is not None else None+ if (attempt < 2 and e.code == 400+ and b"Assistant message must have either content" in data+ and assistant is not None and assistant != body):+ flags["stringify_assistant_content"] = True+ body = assistant+ headers["content-length"] = str(len(body))+ continueeffort = _set_reasoning_effort_none(body) if body is not None else Noneif (attempt < 2 and e.code == 400 and b"reasoning_effort" in dataand b"'none'" in data and effort is not None and effort != body):@@ -5602,6 +5657,120 @@ _aider_to_claude.eof = _aider_eof # type: ignore[attr-defined]# ── kimi ─────────────────────────────────────────────────────────────────────────+OPENHANDS_PROVIDERS = {"anthropic", "openai", "azure", "openai-api", "tokenrouter"}+# A field litellm sends on its own initiative, the kimi precedent: for an id its registry knows as+# Anthropic's (the provider-native `claude-haiku-4-5-20251001` a custom connection resolves to)+# it puts BOTH `max_tokens` and `max_completion_tokens` on the request, the same 64,000 in each,+# and Anthropic's OpenAI-compatible endpoint answers "Setting 'max_tokens' and+# 'max_completion_tokens' at the same time is not supported" (captured with a sink in the venv+# and against the live endpoint, 2026-09-19; every other id carries the second field alone, and+# every provider on the matrix takes it). The harness never asked for either; the one every+# provider takes stays.+_OPENHANDS_DROP_FIELDS = ("max_tokens",)+OPENHANDS_PYTHON = os.environ.get("HR_OPENHANDS_PYTHON",+ "/data/agent-tools/openhands-venv/bin/python")+OPENHANDS_DRIVER = os.path.join(os.path.dirname(os.path.abspath(__file__)), "openhands_driver.py")+++def _openhands_mcp_config(mcp_servers: list[dict] | None) -> dict:+ """The declared servers as the SDK's `Agent.mcp_config`: {name: MCPServer}.++ This base needs no bridge — unlike aider, which ships no MCP client at all — because the agent+ server's own SDK takes the servers on the agent and dials them itself. Its MCPServer accepts+ `url`/`transport`/`headers` and the stdio trio `command`/`args`/`env`, so the harness's+ declaration maps across one field at a time and nothing is invented here.++ THE DECLARED TRANSPORT TRAVELS, the rule #191's review set for kimi: the harness says what a+ server speaks and the url's spelling decides nothing. The SDK's own values are+ stdio / http / streamable-http / sse, and anything else is dropped rather than guessed at —+ a server dialled with the wrong protocol cannot answer, and a config the SDK rejects would+ fail the whole turn rather than the one server.+ """+ out: dict = {}+ for i, sv in enumerate(mcp_servers or []):+ if not isinstance(sv, dict):+ continue+ name = _skill_dir_name(sv.get("name") or sv.get("id") or f"server{i}")+ url = (sv.get("url") or "").strip()+ entry: dict = {}+ if url:+ entry["url"] = url+ transport = str(sv.get("transport") or "").lower()+ if transport in ("stdio", "http", "streamable-http", "sse"):+ entry["transport"] = transport+ hdrs = sv.get("headers")+ if isinstance(hdrs, dict) and hdrs:+ entry["headers"] = {str(k): str(v) for k, v in hdrs.items()}+ elif sv.get("command"):+ cmd = sv["command"]+ argv = cmd if isinstance(cmd, list) else [str(cmd)]+ entry["transport"] = "stdio"+ entry["command"] = argv[0]+ entry["args"] = [str(x) for x in argv[1:]] + [str(x) for x in (sv.get("args") or [])]+ envv = sv.get("env")+ if isinstance(envv, dict) and envv:+ entry["env"] = {str(k): str(v) for k, v in envv.items()}+ if sv.get("cwd"):+ entry["cwd"] = str(sv["cwd"])+ else:+ continue+ out[name] = entry+ return out+++def _build_openhands(provider: str, auth: Auth, model: str, prompt: str, cwd: str, env: dict,+ resume_session_id: str | None = None, mcp_servers: list[dict] | None = None,+ tools_disabled: list[str] | None = None,+ max_turns: int | None = None) -> list[str]:+ """OpenHands V1, driven through `openhands-agent-server` (OpenHands/agent-sdk, MIT).++ NOT the CLI. PyPI `openhands` is OpenHands/openhands-cli, whose README opens with "This project+ is no longer actively maintained" and whose last release is 1.16.0 of 2026-05-08; the agent+ server released 1.49.2 on 2026-09-17. The turn process is runner/openhands_driver.py, which+ starts a server on loopback, drives ONE turn over its HTTP + WebSocket API and exits — the same+ one-process-per-turn contract as every other backend, and the codex app-server precedent.++ THE MODEL ID IS SENT WITH AN `openai/` PREFIX and the key rides the driver's environment rather+ than the conversation. Both are forced by what the server persists: base_state.json carries the+ whole LLM spec with `api_key: None`, so a key passed on the create call reaches the first turn+ and nothing after it, and without an explicit provider litellm INFERS one from the base url —+ which is how a relay url produced `Vercel_ai_gatewayException … set the VERCEL_AI_GATEWAY_API_KEY`+ on a resumed turn. Every turn rides the loopback relay for the qwen reason: the real key never+ enters the agent's environment and the provider's own `model` passes through for the+ served-model check."""+ pr = provider or "openai-api"+ if pr not in OPENHANDS_PROVIDERS:+ raise HTTPException(400,+ f"unknown openhands provider '{pr}' (one of {sorted(OPENHANDS_PROVIDERS)})")+ if not auth.base_url:+ raise HTTPException(400, "openhands needs a base_url (none configured)")+ # GUARDED ON THE KEY, as every other builder is. The relay holds the real credential and hands+ # the turn a token in its place; with nothing to hold it registers a route whose upstream key+ # is empty and the provider refuses the forwarded request — measured on the google integration,+ # whose `Please pass a valid API key` came back through a relay that had none to send.+ if auth.api_key:+ relay_base, relay_tok = _hermes_relay_route(auth.base_url, auth.api_key,+ drop_fields=_OPENHANDS_DROP_FIELDS)+ auth = auth.model_copy(update={"base_url": relay_base, "api_key": relay_tok})+ # The relay token rides the turn's ENVIRONMENT as well as the job: _relay_served_model and+ # _relay_usage find the turn's route by the placeholder bearer in env, and a token that lived+ # only in the driver's argv left every openhands turn with no served model and no usage+ # (measured: usage None on three turns whose provider calls the relay had counted).+ env["OPENAI_API_KEY"] = auth.api_key or ""+ env["OPENAI_BASE_URL"] = auth.base_url+ job = {"cwd": cwd, "model": f"openai/{model}", "prompt": prompt,+ "base_url": auth.base_url, "api_key": auth.api_key,+ "tools_disabled": list(tools_disabled or []),+ # Declared MCP servers reach the agent itself; a parameter accepted and then dropped is+ # the defect aider's bridge already taught this repo, so the test suite pins the whole+ # chain rather than this line.+ "mcp_config": _openhands_mcp_config(mcp_servers),+ # the server's own default is 500 iterations per run; an operator's budget that the+ # backend drops is the quiet lie kimi shipped at 1000 steps+ "max_turns": max_turns}+ return [OPENHANDS_PYTHON, OPENHANDS_DRIVER, json.dumps(job)]++def _kimi_to_claude(obj: dict, state: dict) -> list[dict]:"""Map ONE `kimi -p … --output-format stream-json` line to zero+ canonical claude events.@@ -5728,6 +5897,84 @@ _kimi_to_claude.eof = _kimi_eof # type: ignore[attr-defined]# Registry — providers/default_model/normalize per backend. The cmd build + run loop is dispatched# in turn(): claude/codex run through _run_turn_bg over stdout JSONL; hermes has its own driver# (_run_hermes_bg — DB-polling, no stdout events), so it carries no normalizer.+# ── openhands ────────────────────────────────────────────────────────────────────+# The turn process is runner/openhands_driver.py, which re-emits what it observes on the+# agent-server's WebSocket as NDJSON in the dsh_driver shape. The driver has already decided what+# is prose, what is a tool call and what is a failure — it sees typed SDK events, not text — so+# this maps one shape to another and judges nothing.+_OPENHANDS_SESSION_NAME = "harness"+++def _openhands_to_claude(obj: dict, state: dict) -> list[dict]:+ m = obj.get("m")+ p = obj.get("p") if isinstance(obj.get("p"), dict) else {}+ if not state.get("_oh_init"):+ # _run_turn_bg records the conversation id ONLY from a system/init event, and that recorded+ # id is what makes the next turn a follow-up rather than a new thread.+ state["_oh_init"] = True+ return ([{"type": "system", "subtype": "init", "session_id": _OPENHANDS_SESSION_NAME,+ "model": state.get("model")}]+ + _openhands_event(obj, state, m, p))+ return _openhands_event(obj, state, m, p)+++def _openhands_event(obj: dict, state: dict, m, p) -> list[dict]:+ if m == "text":+ txt = str(p.get("text") or "")+ if not txt.strip():+ return []+ state["final"] = txt+ return [{"type": "assistant", "message": {"content": [{"type": "text", "text": txt}]}}]+ if m == "tool_call":+ state["_oh_last_call"] = str(p.get("id") or "t0")+ return [{"type": "assistant", "message": {"content": [+ {"type": "tool_use", "id": state["_oh_last_call"], "name": str(p.get("name") or "Tool"),+ "input": p.get("input") or {}}]}}]+ if m == "tool_result":+ out = p.get("output")+ return [{"type": "user", "message": {"content": [+ {"type": "tool_result",+ "tool_use_id": str(p.get("id") or state.get("_oh_last_call") or "t0"),+ "is_error": bool(p.get("is_error")) or bool(isinstance(out, dict) and out.get("is_error")),+ "content": json.dumps(out, default=str) if not isinstance(out, str) else out}]}}]+ if m == "error":+ # Reached the conversation's error channel, which the model's prose cannot reach. Recorded,+ # NOT rendered: it is the turn's failure reason, not part of its answer.+ state["_oh_error"] = str(p.get("text") or "")+ return []+ if m == "warning":+ state.setdefault("_oh_warnings", []).append(str(p.get("text") or ""))+ return []+ if m == "init":+ state["_oh_conversation"] = str(p.get("conversation_id") or "")+ return []+ if m == "result":+ err = state.get("_oh_error") or ""+ ok = bool(p.get("ok")) and not err+ final = str(p.get("final") or state.get("final") or "")+ if ok:+ state["final"] = final+ # usage is {} deliberately: per the 2026-09-13 decision no harness PR builds its own usage+ # pipeline, and _relay_usage stamps these rows.+ return [{"type": "result", "subtype": "success" if ok else "error", "is_error": not ok,+ "result": final if ok else (err or f"the turn ended {p.get('status') or 'unknown'}"),+ "usage": {}}]+ return []+++def _openhands_eof(state: dict, rc: int) -> list[dict]:+ """The driver emits its own result event, so this fires only when the process died before+ reaching it — a crash, a kill, an import failure."""+ err = state.get("_oh_error") or ""+ if rc == 0 and not err:+ return [{"type": "result", "subtype": "success", "is_error": False,+ "result": state.get("final", ""), "usage": {}}]+ return [{"type": "result", "subtype": "error", "is_error": True, "result": err, "usage": {}}]+++_openhands_to_claude.eof = _openhands_eof # type: ignore[attr-defined]++BACKENDS = {"claude": {"providers": sorted(CLAUDE_PROVIDERS), "default_model": CLAUDE_DEFAULT_MODEL,"normalize": _claude_passthrough},@@ -5768,6 +6015,9 @@ BACKENDS = {"normalize": _kimi_to_claude},"aider": {"providers": sorted(AIDER_PROVIDERS), "default_model": AIDER_DEFAULT_MODEL,"normalize": _aider_to_claude},+ "openhands": {"providers": sorted(OPENHANDS_PROVIDERS),+ "default_model": OPENHANDS_DEFAULT_MODEL,+ "normalize": _openhands_to_claude},}@@ -5820,11 +6070,53 @@ _turn_by_key: dict[str, str] = {} # idempotency_key -> turn_id (dedup a retrie_turns_lock = threading.Lock()-def _kill_proc_tree(proc: subprocess.Popen) -> None:+# Every process a turn starts carries the turn's id in its environment (set on the CLI's env+# and inherited by everything below it), so what the process group misses can still be found.+_TURN_MARK = "HR_TURN_ID"+++def _sweep_turn_processes(turn_id: str) -> int:+ """Kill every process still carrying this turn's marker, and remove the tmux socket+ directory such a process names. The group kill misses a process that put itself in a new+ session: openhands' terminal tool runs commands in tmux, whose server daemonises with+ setsid, so a cancelled or timed-out turn left the tmux server AND the agent's command+ running (`sleep 240` alive after cancel, hr-test 2026-09-19), and every turn's+ /tmp/oh<port> directory behind it. The marker is what makes the turn's processes findable+ whatever they did to their process group; /proc is read as the runner, which is root here."""+ if not turn_id:+ return 0+ want = f"{_TURN_MARK}={turn_id}".encode()+ killed = 0+ dirs: set[str] = set()+ me = os.getpid()+ for entry in os.listdir("/proc") if os.path.isdir("/proc") else []:+ if not entry.isdigit() or int(entry) == me:+ continue+ try:+ environ = pathlib.Path("/proc", entry, "environ").read_bytes()+ except OSError:+ continue+ if want not in environ.split(b"\0"):+ continue+ for kv in environ.split(b"\0"):+ if kv.startswith(b"TMUX_TMPDIR="):+ dirs.add(kv.split(b"=", 1)[1].decode(errors="replace"))+ try:+ os.kill(int(entry), signal.SIGKILL)+ killed += 1+ except OSError:+ pass+ for d in dirs:+ if d.startswith("/tmp/oh"):+ shutil.rmtree(d, ignore_errors=True)+ return killed+++def _kill_proc_tree(proc: subprocess.Popen, turn_id: str = "") -> None:"""SIGKILL the CLI's whole process GROUP (Popen uses start_new_session). Killing onlythe CLI leaves its shell children (e.g. a `sleep`) holding the inherited stdout pipe,which keeps the reader loop blocked until the child exits — a cancel/timeout then- appears to hang for the child's full duration."""+ appears to hang for the child's full duration. Then the stragglers by marker."""try:os.killpg(os.getpgid(proc.pid), signal.SIGKILL)except Exception: # noqa: BLE001@@ -5832,18 +6124,25 @@ def _kill_proc_tree(proc: subprocess.Popen) -> None:proc.kill()except Exception: # noqa: BLE001pass+ if turn_id:+ try:+ _sweep_turn_processes(turn_id)+ except Exception: # noqa: BLE001+ passdef _kill_capped(proc: subprocess.Popen, rec: dict) -> None:rec["capped"] = True- _kill_proc_tree(proc)+ _kill_proc_tree(proc, str(rec.get("turn_id") or ""))def _run_turn_bg(turn_id: str, cmd: list[str], env: dict, cwd: str, normalize, model: str,timeout_seconds: int | None = None, partial: bool = False) -> None:rec = _turns[turn_id]+ rec["turn_id"] = turn_idstate = {"model": model, "final": "", "partial": partial, "cwd": cwd, "started": time.time()}result_ev = None+ env = {**env, _TURN_MARK: turn_id}try:# start_new_session: own process group so cancel/timeout can killpg the CLI AND its# shell children (see _kill_proc_tree) instead of orphaning a pipe-holding child.@@ -5856,7 +6155,7 @@ def _run_turn_bg(turn_id: str, cmd: list[str], env: dict, cwd: str, normalize, mrec["pid"] = proc.pidrec["proc"] = proc # live handle so POST /turn/{id}/cancel can kill on demandif rec.get("cancelled"):- _kill_proc_tree(proc) # Stop raced the spawn — kill immediately, not at pipe EOF+ _kill_proc_tree(proc, turn_id) # Stop raced the spawn — kill immediately, not at pipe EOF# Hard wall-clock cap — the caller's timeout_seconds (harness config / request override),# bounded by the global MAX_TURN_SECONDS ceiling (resource abuse backstop).cap = min(timeout_seconds, MAX_TURN_SECONDS) if timeout_seconds else MAX_TURN_SECONDS@@ -6999,6 +7298,12 @@ def turn(req: TurnReq, identifier: str = "") -> dict:cmd = _build_aider(req.provider, auth, model, req.prompt, cwd, env,mcp_servers=req.mcp_servers, tools_disabled=req.tools_disabled,skills_read=aider_read, max_turns=req.max_turns)+ elif backend == "openhands":+ model = model or OPENHANDS_DEFAULT_MODEL+ cmd = _build_openhands(req.provider, auth, model, req.prompt, cwd, env,+ resume_session_id=req.resume_session_id,+ mcp_servers=req.mcp_servers,+ tools_disabled=req.tools_disabled, max_turns=req.max_turns)elif backend == "gemini":model = model or GEMINI_DEFAULT_MODELcmd = _build_gemini(req.provider, auth, model, req.prompt, cwd, env,@@ -7122,7 +7427,7 @@ def cancel_turn(turn_id: str) -> dict:rec["cancelled"] = Trueproc = rec.get("proc")if proc is not None:- _kill_proc_tree(proc)+ _kill_proc_tree(proc, turn_id)return {"turn_id": turn_id, "status": "cancelling", "cancelled": True}diff --git a/runner/tests/test_aider_driver.py b/runner/tests/test_aider_driver.pyindex e8628be9..5ed6c790 100644--- a/runner/tests/test_aider_driver.py+++ b/runner/tests/test_aider_driver.py@@ -544,7 +544,6 @@ def test_the_chat_history_is_restored_on_every_turn():"""aider's only continuation mechanism. It travels in the checkpoint under .harness/, which iswhat lets a follow-up after a sandbox recycle still know what was said; on a first turn the filedoes not exist and aider starts fresh."""- import json as _json_, _, _, job = _build()# the driver owns the argv; assert the flag it buildssrc = pathlib.Path(__file__).resolve().parents[1].joinpath("aider_driver.py").read_text()diff --git a/runner/tests/test_openhands_backend.py b/runner/tests/test_openhands_backend.pynew file mode 100644index 00000000..d8bd5339--- /dev/null+++ b/runner/tests/test_openhands_backend.py@@ -0,0 +1,476 @@+"""The openhands backend (OpenHands V1 through openhands-agent-server 1.49.2, MIT).++Every test below pins something measured against a real agent-server on the pinned version, not a+reading of its docs. The four that decided the design:++ the agent is FROZEN at the conversation's first creation — a second create carrying `tools: []`+ left the persisted agent holding ['terminal', 'file_editor'] and the turn wrote its file+ the credential is NEVER persisted — base_state.json holds the whole LLM spec with `api_key: None`,+ so a resumed turn had no key and litellm's backoff hid that for two minutes+ the turn's answer can arrive as a FinishAction rather than a trailing assistant message+ disabling a tool is enforced by OMISSION — with Shell and Edit both withheld the same request+ that wrote a file under the full tool list produced no file and no tool call at all+"""+import json+import tempfile+import pathlib+import sys++sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))+import openhands_driver as drv # noqa: E402+++# ── the conversation identity carries the tool policy ──+def test_the_same_policy_is_the_same_conversation():+ assert drv._conversation_id(["terminal", "file_editor"]) == \+ drv._conversation_id(["terminal", "file_editor"])+++def test_a_changed_policy_is_a_different_conversation():+ """MEASURED: the agent is frozen at first creation and no endpoint updates it, so a policy that+ only reached a create call the server ignored would run with tools the operator disabled.+ Keying the id on the policy makes the new policy arrive the one way it can — a new+ conversation. Verified live: with Shell and Edit withheld the id changed, the file was not+ written, and restoring the full policy resumed the ORIGINAL conversation with its history."""+ full = drv._conversation_id(["terminal", "file_editor", "task_tracker"])+ none = drv._conversation_id([])+ assert full != none+ # and going back is going back: the id is a pure function of the policy+ assert drv._conversation_id(["terminal", "file_editor", "task_tracker"]) == full+++def test_the_id_is_a_uuid_because_the_field_is_typed_one():+ import uuid+ uuid.UUID(drv._conversation_id(["terminal"]))+++# ── the tool list, and what disabling means ──+def test_the_browser_set_is_not_offered():+ """It is in upstream's default preset and needs a Chromium this image does not carry; the+ server's own log says `Error preloading … Exception: Chromium is …`. A tool that cannot run is+ not offered."""+ assert "browser_tool_set" not in drv._TOOLS+ assert set(drv._tools({})) == set(drv._TOOLS)+++def test_a_disabled_tool_is_withheld_by_its_console_name():+ assert "terminal" not in drv._tools({"tools_disabled": ["Shell"]})+ assert "file_editor" not in drv._tools({"tools_disabled": ["Edit"]})+++def test_a_disabled_tool_is_withheld_by_its_own_name_too():+ assert "terminal" not in drv._tools({"tools_disabled": ["terminal"]})+++def test_disabling_one_tool_leaves_the_others():+ left = drv._tools({"tools_disabled": ["Shell"]})+ assert "file_editor" in left and "task_tracker" in left+++# ── the credential never rides in the conversation ──+def test_the_agent_spec_carries_no_key_and_no_base_url():+ """MEASURED: base_state.json persists model, base_url, retries and timeouts, and `api_key:+ None`. A key passed here reaches the first turn and nothing after it. The base url is the+ loopback relay's, which binds a fresh port on every runner start: persisted, a conversation+ created before a restart dialled the old port on its next turn (`Cannot connect to host+ 127.0.0.1:39265`, hr-test 2026-09-19). Both ride the environment of each turn's server."""+ spec = drv._agent_spec({"model": "openai/gpt-5.4", "base_url": "http://relay/v1",+ "api_key": "sk-secret"})+ assert "sk-secret" not in json.dumps(spec)+ assert "http://relay/v1" not in json.dumps(spec) and spec["llm"]["base_url"] is None+++def test_the_agent_spec_carries_the_tools():+ spec = drv._agent_spec({"model": "m", "tools_disabled": ["Shell"]})+ names = [t["name"] for t in spec["tools"]]+ assert "terminal" not in names and "file_editor" in names+++# ── the server's own config, written per turn ──+def test_every_path_is_under_the_harness_dir_and_vscode_is_off(tmp_path):+ """VSCode defaults ON and binds 8001; one server process per turn would collide on it at once.+ The stores go under .harness/ so they travel in the checkpoint and are not produced files."""+ cfg = json.loads(drv._write_config(tmp_path, "key").read_text())+ assert cfg["enable_vscode"] is False+ assert cfg["session_api_keys"] == ["key"]+ for field in ("conversations_path", "workspace_path", "bash_events_dir"):+ assert str(tmp_path) in cfg[field], field+++# ── events ──+def _collect(ev, state=None):+ out, state = [], state if state is not None else {}+ real, drv._emit = drv._emit, lambda m, p: out.append((m, p))+ try:+ drv._on_event(ev, state)+ finally:+ drv._emit = real+ return out, state+++def test_an_assistant_message_is_the_answer():+ out, state = _collect({"kind": "MessageEvent",+ "llm_message": {"role": "assistant",+ "content": [{"type": "text", "text": "OH-PROBE-1"}]}})+ assert out == [("text", {"text": "OH-PROBE-1"})]+ assert state["final"] == "OH-PROBE-1"+++def test_a_user_message_is_not():+ out, _ = _collect({"kind": "MessageEvent",+ "llm_message": {"role": "user",+ "content": [{"type": "text", "text": "do it"}]}})+ assert out == []+++def test_a_finish_action_is_the_answer_and_not_a_tool_call():+ """MEASURED: a turn that uses tools ends with its answer on the finish action, while a turn+ that only talks emits a MessageEvent and no finish. Rendering finish as a tool call showed the+ user a `finish` step and left the turn with no answer."""+ out, state = _collect({"kind": "ActionEvent", "tool_call_id": "c1",+ "action": {"kind": "FinishAction", "message": "DONE"}})+ assert out == [("text", {"text": "DONE"})]+ assert state["final"] == "DONE"+++def test_the_finish_observation_is_not_an_orphan_result():+ """Its action is suppressed above, so rendering this would leave a tool result under a call id+ the transcript never showed. Seen in a real artifact turn."""+ out, _ = _collect({"kind": "ObservationEvent", "tool_call_id": "c1",+ "observation": {"kind": "FinishObservation"}})+ assert out == []+++def test_a_real_tool_call_and_its_result_are_a_pair():+ state = {}+ call, _ = _collect({"kind": "ActionEvent", "tool_call_id": "c9", "tool_name": "terminal",+ "action": {"kind": "TerminalAction", "command": "echo hi"}}, state)+ res, _ = _collect({"kind": "ObservationEvent", "tool_call_id": "c9",+ "observation": {"kind": "TerminalObservation", "exit_code": 0}}, state)+ # the console's name for the tool (the catalog lists Shell, Edit, Todo; the SDK's registry+ # names are the wire), and the action's arguments as the card's input+ assert call[0][0] == "tool_call" and call[0][1]["name"] == "Shell"+ assert call[0][1]["input"] == {"command": "echo hi"}+ assert res[0][0] == "tool_result" and res[0][1]["id"] == call[0][1]["id"] == "c9"+++def test_the_result_card_carries_the_observations_text_not_its_record():+ """The raw observation is a typed record (kind, content blocks with cache flags, exit codes);+ rendered whole it put JSON on every result card. The text blocks are what the tool said."""+ obs = {"kind": "TerminalObservation", "exit_code": 0, "command": "python hello.py",+ "content": [{"cache_prompt": False, "type": "text", "text": "openhands\n"}], "is_error": False}+ res, _ = _collect({"kind": "ObservationEvent", "tool_call_id": "c1", "observation": obs}, {})+ assert res[0][1]["output"] == "openhands\n" and res[0][1]["is_error"] is False+ # no text blocks at all: the record minus the empty content, so nothing is lost+ res, _ = _collect({"kind": "ObservationEvent", "tool_call_id": "c2",+ "observation": {"kind": "X", "exit_code": 1, "content": [], "is_error": True}}, {})+ assert json.loads(res[0][1]["output"]) == {"kind": "X", "exit_code": 1, "is_error": True}+ assert res[0][1]["is_error"] is True+++def test_the_relay_token_rides_the_turns_environment_so_the_served_model_and_usage_are_found():+ """_relay_served_model and _relay_usage find the turn's route by the placeholder bearer in+ env; a token that lived only in the driver's argv left every turn with no served model and+ no usage (measured: usage None on three turns the relay had counted)."""+ from server import Auth, _build_openhands+ d = tempfile.mkdtemp(); env: dict = {}+ cmd = _build_openhands("openai-api", Auth(api_key="sk-real", base_url="https://up.example/v1"),+ "gpt-5.4", "hi", d, env)+ job = json.loads(cmd[-1])+ assert env["OPENAI_API_KEY"].startswith("hr-relay-") and env["OPENAI_API_KEY"] == job["api_key"]+ assert env["OPENAI_BASE_URL"] == job["base_url"]+++def test_only_the_execution_status_update_sets_the_status():+ """The event is a generic key/value pair and `last_user_message_id` rides the same shape.+ Reading `value` alone once set the status to a message uuid."""+ _, state = _collect({"kind": "ConversationStateUpdateEvent",+ "key": "last_user_message_id", "value": "b0d94974-206c-4317-8274-45b"})+ assert "status" not in state+ _, state = _collect({"kind": "ConversationStateUpdateEvent",+ "key": "execution_status", "value": "running"})+ assert state["status"] == "running"+++def test_an_error_event_is_recorded_not_rendered():+ """LLMServiceUnavailableError is the turn's reason, not part of its answer."""+ out, _ = _collect({"kind": "ConversationErrorEvent", "code": "LLMServiceUnavailableError",+ "detail": "Missing credentials"})+ assert [m for m, _ in out] == ["error"]+++def test_a_streaming_delta_is_not_rendered_twice():+ """The final MessageEvent carries the same text whole."""+ out, _ = _collect({"kind": "StreamingDeltaEvent", "delta": "OH-"})+ assert out == []+++# ── the relay repair this column found ──+def test_an_assistant_messages_block_list_flattens_to_a_string():+ """MEASURED against the live endpoint (2026-09-18): the identical chat/completions request+ answers 200 with `content: "M1"` on the assistant turn and 400 with+ `content: [{"type": "text", "text": "M1"}]`, and the 400 reads `Assistant message must have+ either content or tool_calls, but not none.` about a message whose content is right there.+ The OpenHands SDK sends the array form for every replayed assistant turn, so a first turn+ passes and every one after it fails: four of five scenarios on+ vercel|openhands|mistral-medium-3.5."""+ from server import _stringify_assistant_content+ body = json.dumps({"model": "m", "messages": [+ {"role": "user", "content": [{"type": "text", "text": "hi"}]},+ {"role": "assistant", "content": [{"type": "text", "text": "M1"}]},+ {"role": "tool", "content": [{"type": "text", "text": "out"}]},+ ]}).encode()+ out = json.loads(_stringify_assistant_content(body))+ assert out["messages"][1]["content"] == "M1"+ # the other roles are left exactly as they were: user arrays are accepted everywhere, and the+ # tool role has its own repair with its own trigger+ assert out["messages"][0]["content"] == [{"type": "text", "text": "hi"}]+ assert out["messages"][2]["content"] == [{"type": "text", "text": "out"}]+++def test_a_body_with_nothing_to_flatten_is_returned_untouched():+ """Byte-identical, so the retry loop can tell 'no repair applies' from 'repaired'."""+ from server import _stringify_assistant_content+ body = json.dumps({"model": "m", "messages": [+ {"role": "assistant", "content": "already a string"}]}).encode()+ assert _stringify_assistant_content(body) == body+++def test_an_unparseable_body_is_never_altered():+ from server import _stringify_assistant_content+ assert _stringify_assistant_content(b"not json") == b"not json"+++# ── MCP: declared servers reach the agent ──+def test_a_url_server_carries_the_transport_the_harness_declared():+ """The rule #191's review set for kimi, one backend over: the harness says what a server+ speaks and the url's spelling decides nothing."""+ from server import _openhands_mcp_config+ cfg = _openhands_mcp_config([+ {"name": "events", "transport": "sse", "url": "https://example.test/events"},+ {"name": "api", "transport": "http", "url": "https://example.test/mcp"},+ ])+ assert cfg["events"] == {"url": "https://example.test/events", "transport": "sse"}+ assert cfg["api"] == {"url": "https://example.test/mcp", "transport": "http"}+++def test_a_transport_the_sdk_does_not_know_is_dropped_rather_than_guessed():+ """Its own values are stdio/http/streamable-http/sse. A config the SDK rejects fails the whole+ turn, not the one server, so an unknown word is left out and the SDK decides."""+ from server import _openhands_mcp_config+ cfg = _openhands_mcp_config([{"name": "x", "transport": "carrier-pigeon",+ "url": "https://example.test/mcp"}])+ assert cfg["x"] == {"url": "https://example.test/mcp"}+++def test_a_stdio_server_reaches_the_agent_as_command_and_args():+ from server import _openhands_mcp_config+ cfg = _openhands_mcp_config([{"name": "local", "command": ["node", "srv.js"],+ "args": ["--flag"], "env": {"K": "v"}}])+ assert cfg["local"]["transport"] == "stdio"+ assert cfg["local"]["command"] == "node"+ assert cfg["local"]["args"] == ["srv.js", "--flag"]+ assert cfg["local"]["env"] == {"K": "v"}+++def test_declared_headers_travel():+ from server import _openhands_mcp_config+ cfg = _openhands_mcp_config([{"name": "api", "url": "https://example.test/mcp",+ "headers": {"X-K": "v"}}])+ assert cfg["api"]["headers"] == {"X-K": "v"}+++def test_the_config_actually_reaches_the_agent():+ """The defect aider's bridge taught this repo: a block generated by a function nobody called.+ Pinned end to end rather than at the seam."""+ spec = drv._agent_spec({"model": "m", "mcp_config": {"deepwiki": {"url": "https://x/mcp"}}})+ assert spec["mcp_config"] == {"deepwiki": {"url": "https://x/mcp"}}+ assert "mcp_config" not in drv._agent_spec({"model": "m"})+++def test_declaring_a_server_is_a_different_agent():+ """The agent is frozen at creation, so a server added later cannot reach the one already made;+ the identity carries the servers for the same reason it carries the tool policy."""+ bare = drv._conversation_id(["terminal"], {})+ with_mcp = drv._conversation_id(["terminal"], {"deepwiki": {"url": "https://x/mcp"}})+ assert bare != with_mcp+ assert drv._conversation_id(["terminal"], {}) == bare+++# ── a failure the server did not publish still has to reach the record ──+#+# The agent-server publishes an error event only for an exception that is NOT a+# ConversationRunError, on the assumption that run()/arun() already emitted its own; an exception+# raised out of arun's error handling is exactly the case where nobody did. The status flips to+# error, nothing else crosses the WebSocket, and the only copy of the reason is the server's log.+# Measured on the google column: eleven scenarios recorded "the turn ended error" and nothing more.+_CRASH_LOG = """\+[09/19/26 03:24:11] INFO Loaded 3 tools from spec base.py:564+[09/19/26 03:24:12] ERROR Error during conversation run event_service.py:1314+╭───────────────────── Traceback (most recent call last) ─────────────────────╮+│ /x/openhands/sdk/llm/utils/telemetry.py:259 in _cache_buckets │+╰─────────────────────────────────────────────────────────────────────────────╯+AttributeError: 'PromptTokensDetailsWrapper' object has no attribute 'cache_creation_tokens'++The above exception was the direct cause of the following exception:++╭───────────────────── Traceback (most recent call last) ─────────────────────╮+│ /x/openhands/agent_server/event_service.py:1310 in _run_and_publish │+╰─────────────────────────────────────────────────────────────────────────────╯+ConversationRunError: Conversation run failed for id=2ec3e3d0+[09/19/26 03:27:05] INFO Event websocket disconnected sockets.py:362+[09/19/26 03:27:05] INFO Received signal SIGTERM (15), shutting down... __main__.py:186+[09/19/26 03:27:05] INFO Shutting down server.py:282+[09/19/26 03:27:05] INFO Waiting for application shutdown. on.py:67+[09/19/26 03:27:05] INFO Application shutdown complete. on.py:76+[09/19/26 03:27:05] INFO Finished server process [5590] server.py:113+"""+++def test_the_reason_beats_the_shutdown_noise(tmp_path):+ """MEASURED, and the first version of _log_tail got this wrong: the turn dies in seconds and is+ then retried to exhaustion, so the file's last lines are the SIGTERM three minutes later. A+ plain tail put that into the record, which reads like a reason and is worse than silence."""+ log = tmp_path / "agent-server.log"+ log.write_text(_CRASH_LOG)+ out = drv._log_tail(log)+ assert "cache_creation_tokens" in out+ assert "SIGTERM" not in out and "Shutting down" not in out+++def test_both_ends_of_the_chain_are_reported(tmp_path):+ """A chained traceback prints the root cause first and its wrapper last, so reading from either+ end alone loses something: the wrapper names no defect, the root names no operation."""+ log = tmp_path / "agent-server.log"+ log.write_text(_CRASH_LOG)+ out = drv._log_tail(log)+ assert out.startswith("AttributeError:")+ assert "ConversationRunError:" in out+++def test_the_frame_is_not_part_of_the_message(tmp_path):+ """rich wraps a long message and then draws the next frame; taking a fixed number of lines put+ `The above exception was … ╭────` behind every reason."""+ log = tmp_path / "agent-server.log"+ log.write_text(_CRASH_LOG)+ out = drv._log_tail(log)+ assert "The above exception" not in out+ assert "╭" not in out and "│" not in out+++def test_a_log_with_no_exception_falls_back_to_its_tail(tmp_path):+ """A server killed without ever raising still owes the record whatever it did say."""+ log = tmp_path / "agent-server.log"+ log.write_text("starting\nlistening on 127.0.0.1:9\nkilled\n")+ assert "killed" in drv._log_tail(log)+++def test_a_missing_log_is_not_an_error(tmp_path):+ """The fallback runs on a path the server may never have created."""+ assert drv._log_tail(tmp_path / "nope.log") == ""+++def test_the_driver_has_no_ceiling_of_its_own_below_the_runners():+ """The runner kills a turn at the harness's timeout (7200 s by default); a second, lower+ ceiling in the driver (1800 s) ended a legitimate long turn as timed out while the operator's+ setting said otherwise. The default is the runner's global ceiling, and a server that dies+ mid-turn is noticed by asking the process rather than waiting the ceiling out."""+ src = pathlib.Path(__file__).resolve().parents[1].joinpath("openhands_driver.py").read_text()+ assert 'os.environ.get("HR_OPENHANDS_TURN_SECONDS", "21600")' in src+ assert 'if proc is not None and proc.poll() is not None:' in src+++def test_a_disabled_mcp_tool_is_withheld_by_the_sdks_own_filter():+ """The built-ins are withheld by omission from the spec; an MCP tool is loaded from the server+ at agent start and was called all the same when disabled (probe_sse, hr-test 2026-09-19, its+ token in the answer). Agent.filter_tools_regex runs over every tool name after the MCP tools+ are added; the disabled names, bare and under a client's server_tool spelling, are excluded,+ and they are part of the conversation's identity like the tool list."""+ import re+ spec = drv._agent_spec({"model": "m", "tools_disabled": ["Shell", "probe_sse"],+ "mcp_config": {"probe": {"url": "u"}}})+ rx = re.compile(spec["filter_tools_regex"])+ assert not rx.match("probe_sse") and not rx.match("probe_probe_sse") and not rx.match("probe.probe_sse")+ assert rx.match("other_tool") and rx.match("probe_sse_2")+ assert "filter_tools_regex" not in drv._agent_spec({"model": "m", "tools_disabled": ["Shell"]})+ a = drv._conversation_id(["file_editor"], {"probe": {}}, ["probe_sse"])+ b = drv._conversation_id(["file_editor"], {"probe": {}}, [])+ assert a != b+++def test_a_model_switch_reaches_a_resumed_conversation(tmp_path):+ """The agent is frozen at creation, LLM spec included; a task that switched models kept+ calling the first one, the record saying claude-sonnet-5 while the relay served gpt-5.4+ (hr-test 2026-09-19). The turn's model is written into the persisted state before the server+ loads it; nothing else of the agent changes; a missing store is left alone."""+ home = tmp_path / ".harness" / "openhands"+ cid = "2ec3e3d0-d5ac-57bb-8f39-5285cc427a6d"+ d = home / "conversations" / cid.replace("-", ""); d.mkdir(parents=True)+ state = {"id": cid, "agent": {"llm": {"model": "openai/gpt-5.4", "usage_id": "harness", "base_url": None},+ "tools": [{"name": "terminal"}], "kind": "Agent"}, "max_iterations": 400}+ (d / "base_state.json").write_text(json.dumps(state))+ assert drv._set_turn_model(home, cid, "openai/claude-sonnet-5") is True+ after = json.loads((d / "base_state.json").read_text())+ assert after["agent"]["llm"]["model"] == "openai/claude-sonnet-5"+ assert after["agent"]["tools"] == [{"name": "terminal"}] and after["max_iterations"] == 400+ assert drv._set_turn_model(home, cid, "openai/claude-sonnet-5") is False # already that model+ assert drv._set_turn_model(home, "no-such-conversation", "m") is False+ src = pathlib.Path(__file__).resolve().parents[1].joinpath("openhands_driver.py").read_text()+ assert '_set_turn_model(pathlib.Path(cwd, ".harness", "openhands"), cid, job["model"])' in src+++def test_the_tmux_socket_directory_is_the_turns_own():+ """Ports are reused and turns run as different uids: a directory named for the port and left+ by an earlier turn answered Permission denied on the next (hr-test 2026-09-19)."""+ src = pathlib.Path(__file__).resolve().parents[1].joinpath("openhands_driver.py").read_text()+ assert 'env["TMUX_TMPDIR"] = tempfile.mkdtemp(prefix="oh", dir="/tmp")' in src+ assert 'f"/tmp/oh{port}"' not in src+++def test_the_field_litellm_invents_for_a_known_claude_id_never_reaches_the_provider():+ """For `openai/claude-haiku-4-5-20251001` litellm sends max_tokens AND max_completion_tokens+ and Anthropic's OpenAI-compatible endpoint refuses the pair (400, 2026-09-19); the relay drops+ the first on this backend's route, the kimi precedent."""+ from server import Auth, _HERMES_RELAY, _build_openhands+ d = tempfile.mkdtemp(); env: dict = {}+ _build_openhands("openai-api", Auth(api_key="sk-real", base_url="https://api.anthropic.com"),+ "claude-haiku-4-5-20251001", "hi", d, env)+ route = _HERMES_RELAY["routes"][env["OPENAI_API_KEY"]]+ assert route[2]["drop_fields"] == ("max_tokens",)+++def test_provider_retries_are_bounded_in_seconds():+ """The SDK's defaults turned a provider that answered the same 503 every time into a 270 s+ turn before the reason was reported; every other base fails in seconds."""+ llm = drv._agent_spec({"model": "m"})["llm"]+ assert (llm["num_retries"], llm["retry_min_wait"], llm["retry_max_wait"], llm["retry_multiplier"]) == (2, 2, 8, 2)+++def test_the_agent_doc_is_loaded_as_context_on_every_turn():+ """The SDK reads the workspace's AGENTS.md as a repo skill only when load_project_skills is+ set, afresh on each server's first run; without it the doc reached the model only when it+ chose to cat the file."""+ spec = drv._agent_spec({"model": "m"})+ assert spec["agent_context"] == {"load_project_skills": True}+++def test_the_servers_verdict_is_the_reason_and_the_log_is_read_before_the_stop():+ """A conversation the server marked stuck was recorded as "websocket disconnected … SIGTERM":+ the log was read after the driver stopped the server, so its last lines were the shutdown.+ The tail is read first, and a failed status is reported in the server's own word."""+ src = pathlib.Path(__file__).resolve().parents[1].joinpath("openhands_driver.py").read_text()+ fin = src.index(" finally:\n # THE LOG IS READ BEFORE THE SERVER IS STOPPED")+ assert src.index("tail_before_stop = _log_tail(logf)", fin) < src.index("proc.send_signal(signal.SIGTERM)", fin)+ assert 'f"the agent-server marked the conversation {status}"' in src+++def test_a_file_editor_view_is_a_read_card():+ """The console counts Edit cards as files edited: one file created and two looked at read+ "Edited 3 files". A view is a read."""+ call, _ = _collect({"kind": "ActionEvent", "tool_call_id": "v1", "tool_name": "file_editor",+ "action": {"kind": "FileEditorAction", "command": "view", "path": "/w/a.md"}}, {})+ assert call[0][1]["name"] == "Read" and call[0][1]["input"] == {"command": "view", "path": "/w/a.md"}+ call, _ = _collect({"kind": "ActionEvent", "tool_call_id": "v2", "tool_name": "file_editor",+ "action": {"kind": "FileEditorAction", "command": "create", "path": "/w/a.md", "file_text": "x"}}, {})+ assert call[0][1]["name"] == "Edit"+diff --git a/runner/tests/test_turn_process_sweep.py b/runner/tests/test_turn_process_sweep.pynew file mode 100644index 00000000..945bec95--- /dev/null+++ b/runner/tests/test_turn_process_sweep.py@@ -0,0 +1,46 @@+"""A turn's processes carry the turn's id in their environment, so what the process-group kill+misses can still be found: openhands' terminal tool runs commands in tmux, whose server+daemonises with setsid, and a cancelled turn left it and the agent's `sleep 240` running+(hr-test, 2026-09-19)."""+import os+import pathlib+import subprocess+import sys+import time++import pytest++sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))+import server as rs # noqa: E402++[email protected](not os.path.isdir("/proc"), reason="reads /proc, Linux only")+def test_a_process_that_left_the_group_is_still_found_by_the_turns_marker(tmp_path):+ marker = "turn-sweep-" + str(os.getpid())+ tmux_dir = tmp_path / "ohsock"; tmux_dir.mkdir()+ # a child spawned in THIS group that then puts itself in a new session, as tmux's server does+ # (not start_new_session=True: a session leader's own setsid() is EPERM, and the child died+ # before the sweep looked, which is how the first version of this test failed in CI)+ child = subprocess.Popen([sys.executable, "-c", "import os,time; os.setsid(); time.sleep(60)"],+ env={**os.environ, rs._TURN_MARK: marker, "TMUX_TMPDIR": str(tmux_dir)})+ time.sleep(0.5)+ assert child.poll() is None, "the child must be alive and in its own session when the sweep runs"+ assert os.getsid(child.pid) == child.pid+ other = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(60)"],+ env={**os.environ, rs._TURN_MARK: "another-turn"}, start_new_session=True)+ try:+ killed = rs._sweep_turn_processes(marker)+ assert killed >= 1+ child.wait(timeout=5)+ assert child.returncode is not None+ assert other.poll() is None # a different turn's process is untouched+ assert rs._sweep_turn_processes("") == 0 # no marker, no sweep+ finally:+ other.kill()+++def test_the_cli_env_carries_the_marker_and_the_kill_sites_pass_the_turn_id():+ src = pathlib.Path(__file__).resolve().parents[1].joinpath("server.py").read_text()+ assert "env = {**env, _TURN_MARK: turn_id}" in src+ assert '_kill_proc_tree(proc, turn_id)' in src+ assert '_kill_proc_tree(proc, str(rec.get("turn_id") or ""))' in srcdiff --git a/scripts/support-matrix/custom-harness.mjs b/scripts/support-matrix/custom-harness.mjsindex 92986b2f..a15a4642 100644--- a/scripts/support-matrix/custom-harness.mjs+++ b/scripts/support-matrix/custom-harness.mjs@@ -14,7 +14,7 @@ import { chromium } from 'playwright';import crypto from 'node:crypto';const BASE = process.env.BASE;-const BASES = (process.env.BASES || 'codex,claude-code,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider').split(','); // every built-in harness, all thirteen+const BASES = (process.env.BASES || 'codex,claude-code,hermes,pi,dsh,opencode,qwen,gemini,cline,omp,goose,kimi,aider,openhands').split(','); // every built-in harness, all fourteenconst RESULTS = process.env.RESULTS || 'results-custom.json';// A harness's other kind of tool is an MCP server. A self-contained instance hosts only the// database and media servers, one needing a database and the other costing real money per call, sodiff --git a/scripts/support-matrix/plugins/run-matrix.py b/scripts/support-matrix/plugins/run-matrix.pyindex 7e343e02..1b39d00a 100755--- a/scripts/support-matrix/plugins/run-matrix.py+++ b/scripts/support-matrix/plugins/run-matrix.py@@ -35,7 +35,7 @@ HERE = pathlib.Path(__file__).parentFIXTURE = HERE / "fixture"# Every base the catalog serves. Since #180/#182 every one of them takes a stdio server (pi's# adapter and dsh's client spawn it themselves), so no base is expected to refuse any column.-BASES = ["claude-code", "codex", "hermes", "goose", "gemini", "qwen", "opencode", "cline", "omp", "pi", "dsh", "kimi", "aider"]+BASES = ["claude-code", "codex", "hermes", "goose", "gemini", "qwen", "opencode", "cline", "omp", "pi", "dsh", "kimi", "aider", "openhands"]NO_STDIO: set[str] = set()# The public probe the remote columns call: its SSE end answers PROBE-SSE-<id>, its streamable-HTTP# end PROBE-HTTP-<id>. Both are the same fixed server, so a wrong answer is the base, not the probe.diff --git a/ui/public/logos/openhands.png b/ui/public/logos/openhands.pngnew file mode 100644index 00000000..31d5801aBinary files /dev/null and b/ui/public/logos/openhands.png differdiff --git a/ui/src/components/HarnessLogo.tsx b/ui/src/components/HarnessLogo.tsxindex b0364087..8aa10406 100644--- a/ui/src/components/HarnessLogo.tsx+++ b/ui/src/components/HarnessLogo.tsx@@ -18,6 +18,7 @@ const LOGO: Record<string, string> = {goose: '/logos/goose.png', // the flying goose from goose-docs.ai (logo_light.png, cropped to the mark)kimi: '/logos/kimi.png', // the official Kimi mark (the K app icon from kimi.ai/code), supplied by Richard 2026-09-17aider: '/logos/aider.png', // aider's own app icon (aider.chat/assets/icons/apple-touch-icon.png, from the Apache-2.0 repo's website assets)+ openhands: '/logos/openhands.png', // OpenHands' own app icon (public/apple-touch-icon.png in the MIT OpenHands/OpenHands repository)};export function HarnessLogo({ id, size = 26 }: { id: string; size?: number }) {diff --git a/ui/src/components/HarnessSettings.tsx b/ui/src/components/HarnessSettings.tsxindex 9a12269b..db30a3af 100644--- a/ui/src/components/HarnessSettings.tsx+++ b/ui/src/components/HarnessSettings.tsx@@ -273,7 +273,7 @@ export function HarnessSettings({ id, embedded = false, onNavigate }: {<section className="form-section"><div><h3>Agent instructions</h3><p>Persistent role, conventions, constraints, and output contract loaded on every Task.</p></div><div className="field-stack">- <div className="field"><label htmlFor="hsInstructions">{['codex', 'hermes', 'omp', 'pi', 'opencode', 'dsh', 'qwen', 'cline', 'goose', 'kimi', 'aider'].includes(base?.id || draft?.base || '') ? 'AGENTS.md' : 'CLAUDE.md'}</label>+ <div className="field"><label htmlFor="hsInstructions">{['codex', 'hermes', 'omp', 'pi', 'opencode', 'dsh', 'qwen', 'cline', 'goose', 'kimi', 'aider', 'openhands'].includes(base?.id || draft?.base || '') ? 'AGENTS.md' : 'CLAUDE.md'}</label><textarea id="hsInstructions" rows={7} disabled={readOnly}value={oob ? oob.systemPrompt : (draft?.systemPrompt || '')}onChange={(e) => upd({ systemPrompt: e.target.value })} />diff --git a/ui/src/lib/harness.ts b/ui/src/lib/harness.tsindex 330fa50b..f823bb5a 100644--- a/ui/src/lib/harness.ts+++ b/ui/src/lib/harness.ts@@ -20,7 +20,7 @@ export interface OobHarness {defaultModel?: string; // the backend default, NOT necessarily models[0]moreModels?: number; // "+N" pillstatus: 'ready' | 'soon';- backend: 'claude' | 'codex' | 'hermes' | 'pi' | 'dsh' | 'opencode' | 'qwen' | 'gemini' | 'cline' | 'omp' | 'goose' | 'kimi' | 'aider' | null; // gateway backend; null = coming soon+ backend: 'claude' | 'codex' | 'hermes' | 'pi' | 'dsh' | 'opencode' | 'qwen' | 'gemini' | 'cline' | 'omp' | 'goose' | 'kimi' | 'aider' | 'openhands' | null; // gateway backend; null = coming soonsystemPrompt: string; // the harness's built-in system prompt (shown read-only)tools: string[]; // built-in tools (read-only)skills: string[]; // built-in skills (read-only)@@ -146,6 +146,14 @@ export const OOB: OobHarness[] = [models: ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.2', 'claude-fable-5-1', 'claude-fable-5', 'claude-opus-5', 'claude-sonnet-5', 'claude-opus-4.8', 'claude-opus-4.7', 'claude-sonnet-4.6', 'claude-haiku-4.5', 'gemini-3.8-flash', 'gemini-3.7-flash', 'gemini-3.6-flash', 'gemini-3.5-flash', 'gemini-3.5-flash-lite', 'gemini-3.1-pro-preview', 'gemini-3.1-flash-lite', 'gemini-3-flash-preview', 'grok-4.6', 'grok-4.5', 'grok-4.3', 'grok-4.20', 'grok-build-0.1', 'muse-spark-1.3', 'muse-spark-1.2', 'muse-spark-1.1', 'muse-glimmer-30b', 'llama-3.3-70b', 'deepseek-v4.1-flash', 'deepseek-v4-pro', 'deepseek-v4-flash', 'kimi-k3', 'kimi-k2.7-code', 'qwen3.8-max', 'qwen3.8-flash', 'qwen3.8-27b', 'qwen3.7-max', 'qwen3.7-plus', 'glm-5.3', 'glm-5.3-flash', 'mistral-medium-3.5', 'step-3.7-flash', 'hunyuan-4-preview', 'nemotron-3.5-lightning', 'nemotron-3-super'], defaultModel: 'gpt-5.4', moreModels: 0,systemPrompt: 'You are Aider, an autonomous coding agent. You work on a real git workspace, editing files and proposing shell commands to complete the task end to end.',tools: [], skills: [] },+ { id: 'openhands', name: 'OpenHands', version: 'v1.49.2', backend: 'openhands', status: 'ready',+ // Placeholder only, like every list above: the gateway's catalog wins once fetched. Measured+ // on openhands-agent-server 1.49.2, five console scenarios per id: Vercel 239 of 245 over 49+ // of these, Google 40 of 40 over the eight gemini ids; the gateway's _MODEL_CATALOG["openhands"]+ // and docs/support-matrix-notes.md carry the record.+ models: ['gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-5.5', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.2', 'claude-fable-5-1', 'claude-fable-5', 'claude-opus-5', 'claude-sonnet-5', 'claude-opus-4.8', 'claude-opus-4.7', 'claude-sonnet-4.6', 'claude-haiku-4.5', 'gemini-3.8-flash', 'gemini-3.7-flash', 'gemini-3.6-flash', 'gemini-3.5-flash', 'gemini-3.5-flash-lite', 'gemini-3.1-pro-preview', 'gemini-3.1-flash-lite', 'gemini-3-flash-preview', 'grok-4.6', 'grok-4.5', 'grok-4.3', 'grok-4.20', 'grok-build-0.1', 'muse-spark-1.3', 'muse-spark-1.2', 'muse-spark-1.1', 'muse-glimmer-30b', 'llama-3.3-70b', 'deepseek-v4.1-flash', 'deepseek-v4-pro', 'deepseek-v4-flash', 'kimi-k3', 'kimi-k2.7-code', 'qwen3.8-max', 'qwen3.8-flash', 'qwen3.8-27b', 'qwen3.7-max', 'qwen3.7-plus', 'glm-5.3', 'glm-5.3-flash', 'mistral-medium-3.5', 'step-3.7-flash', 'hunyuan-4-preview', 'nemotron-3.5-lightning', 'nemotron-3-super'], defaultModel: 'gpt-5.4', moreModels: 0,+ systemPrompt: 'You are OpenHands, an autonomous coding agent. You work on a real git workspace with shell and file access, reading and editing files and running commands to complete the task end to end.',+ tools: [], skills: [] },];export const oobById = (id: string) => OOB.find((o) => o.id === id) || null;