Skip to content

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

OpenHands: a refused tool call no longer fails a turn the model recovered from, and a failed turn says why (#440)

github-actions[bot]79e0dbfa8e59
diff --git a/runner/openhands_driver.py b/runner/openhands_driver.py
index a0c6ab7c..7c2d994a 100644
--- a/runner/openhands_driver.py
+++ b/runner/openhands_driver.py
@@ -422,6 +422,15 @@ def _on_event(ev: dict, state: dict) -> None:
# 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 {}
+ if not action:
+ # A call the SDK could not make (arguments that failed the tool's validation, a tool it
+ # does not have) carries no action; the card shows what the model sent instead, and
+ # the refusal arrives as this call's result. Arguments that were not JSON at all are
+ # replaced by the SDK with its own marker, which is not the model's and stays off.
+ with contextlib.suppress(Exception):
+ sent = json.loads(str((ev.get("tool_call") or {}).get("arguments") or ""))
+ if isinstance(sent, dict) and not sent.get("_openhands_malformed_tool_call"):
+ action = sent
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)
@@ -437,7 +446,19 @@ def _on_event(ev: dict, state: dict) -> None:
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"):
+ elif kind == "AgentErrorEvent":
+ # THE ANSWER TO THE MODEL'S CALL, NOT THE TURN'S FAILURE. The SDK sends this to the model
+ # as the result of the call it made, under that call's id (arguments that failed the tool's
+ # validation, a tool it does not have, a tool that raised), and the model carries on.
+ # Reported as the turn's error, a turn the model recovered from was recorded failed:
+ # qwen3.7-plus gave task_tracker a status of 'pending', read the refusal, and made both
+ # files it was asked for (2026-10-09). So it is that call's result, as the model saw it,
+ # and it is kept as the reason should the conversation itself end in error.
+ text = str(ev.get("error") or ev.get("detail") or ev.get("message") or kind)
+ state["agent_error"] = text[:1500]
+ tuid = str(ev.get("tool_call_id") or state.get("last_call") or "t0")
+ _emit("tool_result", {"id": tuid, "output": text, "is_error": True})
+ elif kind == "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
@@ -460,6 +481,31 @@ def _on_event(ev: dict, state: dict) -> None:
state["status"] = value.lower()
+_REASON_WAIT_S = 1.5
+
+
+def _read_the_reason(ws, state: dict) -> None:
+ """THE REASON COMES AFTER THE VERDICT. The SDK sets a failed status, which is published at once,
+ and only then publishes the ConversationErrorEvent saying why (MaxIterationsReached and
+ MaxBudgetReached, local_conversation 1.49.2). A loop that ends on the status never read the
+ reason, and the record said only "the agent-server marked the conversation error" while the
+ server's log said "Agent reached maximum iterations limit (8)" (gemini-3.8-flash, 2026-10-09).
+ So the socket is read on, briefly, until the reason arrives; a status with no reason to follow
+ (stuck) costs the wait and nothing else."""
+ end = time.time() + _REASON_WAIT_S
+ while time.time() < end and not state.get("reported_error"):
+ try:
+ raw = ws.recv(timeout=max(0.1, end - time.time()))
+ except Exception: # noqa: BLE001 — a quiet or closed socket: there is no reason to read
+ return
+ try:
+ ev = json.loads(raw)
+ except (TypeError, ValueError):
+ continue
+ if isinstance(ev, dict):
+ _on_event(ev, state)
+
+
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.
@@ -502,6 +548,8 @@ def _run_turn(base: str, ws_base: str, key: str, cid: str, prompt: str, state: d
if isinstance(ev, dict):
_on_event(ev, state)
if state.get("status") in _TERMINAL and state.get("sent"):
+ if state["status"] in _FAILED and not state.get("reported_error"):
+ _read_the_reason(ws, state)
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
@@ -624,9 +672,11 @@ def main() -> int:
# 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.
+ # Without one, the model's last refused call is the likeliest cause, so it is the reason.
exc_line = tail_before_stop if _EXC_LINE.match((tail_before_stop or "").strip()) else ""
+ why = exc_line or state.get("agent_error") or ""
_emit("error", {"text": f"the agent-server marked the conversation {status}"
- + (f": {exc_line}" if exc_line else "")})
+ + (f": {why}" if why 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
diff --git a/runner/server.py b/runner/server.py
index 452ccb27..479a0f8e 100644
--- a/runner/server.py
+++ b/runner/server.py
@@ -4161,6 +4161,13 @@ def _usage_fields(u) -> dict:
cached = n(det.get("cached_tokens")) if isinstance(det, dict) else 0
return {"input_tokens": max(n(u.get("prompt_tokens")) - cached, 0),
"output_tokens": n(u.get("completion_tokens")), "cache_read_tokens": cached}
+ if "input_tokens" in u and isinstance(u.get("input_tokens_details"), dict):
+ # The Responses API: Messages' names with chat's meaning. input_tokens is GROSS and the
+ # cached part sits under input_tokens_details (OpenAI, 2026-10-09: 4021 in, 3840 of them
+ # cached). Read as Anthropic's, every cached token was counted as fresh input.
+ cached = n(u["input_tokens_details"].get("cached_tokens"))
+ return {"input_tokens": max(n(u.get("input_tokens")) - cached, 0),
+ "output_tokens": n(u.get("output_tokens")), "cache_read_tokens": cached}
if "input_tokens" in u or "output_tokens" in u:
out = {}
for src, dst in (("input_tokens", "input_tokens"), ("output_tokens", "output_tokens"),
@@ -4179,11 +4186,14 @@ def _usage_fields(u) -> dict:
def _usage_in_doc(doc) -> dict:
"""The usage a response document or stream event carries, if any. Anthropic's stream puts the
input side on message_start (under message.usage) and the output side on message_delta, so a
- call's usage is the union of what its events said, later values replacing earlier ones."""
+ call's usage is the union of what its events said, later values replacing earlier ones. The
+ Responses API's stream carries it inside the response, on response.completed: read only at the
+ top level, every streamed Responses call passed the relay uncounted (hermes and goose, 2026-10-09)."""
if not isinstance(doc, dict):
return {}
for u in (doc.get("usage"), doc.get("usageMetadata"),
- (doc.get("message") or {}).get("usage") if isinstance(doc.get("message"), dict) else None):
+ (doc.get("message") or {}).get("usage") if isinstance(doc.get("message"), dict) else None,
+ (doc.get("response") or {}).get("usage") if isinstance(doc.get("response"), dict) else None):
got = _usage_fields(u)
if got:
return got
diff --git a/runner/tests/test_openhands_backend.py b/runner/tests/test_openhands_backend.py
index 13f34a7c..8325ef70 100644
--- a/runner/tests/test_openhands_backend.py
+++ b/runner/tests/test_openhands_backend.py
@@ -218,6 +218,102 @@ def test_an_error_event_is_recorded_not_rendered():
assert [m for m, _ in out] == ["error"]
+def test_an_agent_error_is_the_calls_result_and_does_not_fail_the_turn():
+ """The SDK (1.49.2 _emit_tool_error) shows a call it could not make as an ActionEvent with no
+ action, then hands the model an AgentErrorEvent under the same call id, and the model carries
+ on. qwen3.7-plus gave task_tracker a status of 'pending', made both files it was asked for, and
+ the turn was recorded failed because this event was reported as the turn's error (2026-10-09)."""
+ from server import _openhands_to_claude
+ state: dict = {}
+ refused = "Error validating tool 'task_tracker': task_list.1.status Input should be 'todo'"
+ lines = []
+ for ev in ({"kind": "ActionEvent", "tool_call_id": "c1", "tool_name": "task_tracker", "action": None,
+ "tool_call": {"id": "c1", "name": "task_tracker",
+ "arguments": json.dumps({"command": "plan", "task_list": [{"status": "pending"}]})}},
+ {"kind": "AgentErrorEvent", "tool_name": "task_tracker", "tool_call_id": "c1", "error": refused},
+ {"kind": "MessageEvent", "llm_message": {"role": "assistant", "content": [{"type": "text", "text": "Both files are made."}]}}):
+ out, state = _collect(ev, state)
+ lines += out
+ assert [m for m, _ in lines] == ["tool_call", "tool_result", "text"]
+ assert lines[1][1] == {"id": "c1", "output": refused, "is_error": True}
+ assert not state.get("reported_error") and state["agent_error"] == refused
+ runner: dict = {}
+ events = []
+ for m, p in lines + [("result", {"final": "Both files are made.", "ok": True, "status": "finished"})]:
+ events += _openhands_to_claude({"m": m, "p": p}, runner)
+ assert events[-1]["subtype"] == "success" and events[-1]["result"] == "Both files are made."
+ assert any(b.get("type") == "tool_result" and b.get("is_error") and b.get("tool_use_id") == "c1"
+ for e in events for b in (e.get("message") or {}).get("content") or [])
+
+
+def _turn_over(events: list, monkeypatch) -> tuple[list, dict]:
+ """_run_turn against a socket that delivers `events` in order, then stays quiet."""
+ import types
+
+ class _Socket:
+ def __init__(self):
+ self.queue = [json.dumps(e) for e in events]
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+ def recv(self, timeout=None):
+ if self.queue:
+ return self.queue.pop(0)
+ raise TimeoutError
+
+ client = types.ModuleType("websockets.sync.client")
+ client.connect = lambda *a, **k: _Socket()
+ for name, mod in (("websockets", types.ModuleType("websockets")),
+ ("websockets.sync", types.ModuleType("websockets.sync")),
+ ("websockets.sync.client", client)):
+ monkeypatch.setitem(sys.modules, name, mod)
+ monkeypatch.setattr(drv, "_req", lambda *a, **k: {})
+ out, state = [], {}
+ monkeypatch.setattr(drv, "_emit", lambda m, p: out.append((m, p)))
+ drv._run_turn("http://s", "ws://s", "k", "c1", "hi", state, max_seconds=5)
+ return out, state
+
+
+def test_a_failed_status_waits_for_the_reason_that_follows_it(monkeypatch):
+ """The SDK publishes the failed status first and the ConversationErrorEvent saying why second
+ (MaxIterationsReached). Ending on the status left the record with "the agent-server marked the
+ conversation error" while the server's log had the reason (gemini-3.8-flash, 2026-10-09)."""
+ out, state = _turn_over([
+ {"kind": "ConversationStateUpdateEvent", "key": "execution_status", "value": "running"},
+ {"kind": "ConversationStateUpdateEvent", "key": "execution_status", "value": "error"},
+ {"kind": "ConversationErrorEvent", "code": "MaxIterationsReached",
+ "detail": "Agent reached maximum iterations limit (8)."},
+ ], monkeypatch)
+ assert state["status"] == "error" and state.get("reported_error")
+ assert out == [("error", {"text": "MaxIterationsReached: Agent reached maximum iterations limit (8)."})]
+
+
+def test_a_finished_turn_ends_on_its_status(monkeypatch):
+ """Only a failed status has a reason to wait for; a finished turn does not read on."""
+ out, state = _turn_over([
+ {"kind": "ConversationStateUpdateEvent", "key": "execution_status", "value": "running"},
+ {"kind": "ConversationStateUpdateEvent", "key": "execution_status", "value": "finished"},
+ {"kind": "MessageEvent", "llm_message": {"role": "assistant", "content": [{"type": "text", "text": "late"}]}},
+ ], monkeypatch)
+ assert state["status"] == "finished" and out == []
+
+
+def test_a_call_the_sdk_could_not_make_shows_what_the_model_sent():
+ """Such a call carries no action, so its card showed no input at all. Arguments that were not
+ JSON are replaced by the SDK's own marker, which is not the model's and stays off the card."""
+ call, _ = _collect({"kind": "ActionEvent", "tool_call_id": "c2", "tool_name": "terminal", "action": None,
+ "tool_call": {"id": "c2", "arguments": '{"command": "ls", "timeout": "soon"}'}}, {})
+ assert call[0][1]["name"] == "Shell" and call[0][1]["input"] == {"command": "ls", "timeout": "soon"}
+ call, _ = _collect({"kind": "ActionEvent", "tool_call_id": "c3", "tool_name": "terminal", "action": None,
+ "tool_call": {"id": "c3", "arguments": json.dumps(
+ {"_openhands_malformed_tool_call": True, "error": "Expecting value"})}}, {})
+ assert call[0][1]["input"] == {}
+
+
def test_a_streaming_delta_is_not_rendered_twice():
"""The final MessageEvent carries the same text whole."""
out, _ = _collect({"kind": "StreamingDeltaEvent", "delta": "OH-"})
diff --git a/runner/tests/test_relay_usage.py b/runner/tests/test_relay_usage.py
index b37dacc1..7f7f585f 100644
--- a/runner/tests/test_relay_usage.py
+++ b/runner/tests/test_relay_usage.py
@@ -51,6 +51,23 @@ def test_an_openai_stream_reports_usage_only_on_its_last_chunk():
assert call == {"input_tokens": 10, "output_tokens": 2, "cache_read_tokens": 0}
+def test_a_responses_answer_is_netted_and_its_stream_is_read_inside_the_response():
+ """The Responses API names its fields as Messages does and means them as chat does: input_tokens
+ is gross, the cached part under input_tokens_details. A stream carries the usage only inside the
+ response, on response.completed. Measured on OpenAI 2026-10-09 (4021 in, 3840 cached); before,
+ a streamed Responses call counted nothing and a whole answer counted every cached token fresh."""
+ usage = {"input_tokens": 4021, "input_tokens_details": {"cache_write_tokens": 0, "cached_tokens": 3840},
+ "output_tokens": 5, "output_tokens_details": {"reasoning_tokens": 0}, "total_tokens": 4026}
+ want = {"input_tokens": 181, "output_tokens": 5, "cache_read_tokens": 3840}
+ assert rs._usage_in_doc({"id": "resp_1", "object": "response", "usage": usage}) == want
+ call: dict = {}
+ for line in (b'data: {"type":"response.created","response":{"id":"resp_1","usage":null}}',
+ b'data: {"type":"response.output_text.delta","delta":"OK"}',
+ b'data: {"type":"response.completed","response":{"id":"resp_1","usage":' + json.dumps(usage).encode() + b'}}'):
+ call.update(rs._usage_in_sse_line(line))
+ assert call == want
+
+
def test_a_turn_is_many_calls_and_the_route_sums_them():
flags: dict = {}
rs._usage_add(flags, {"input_tokens": 10, "output_tokens": 2, "cache_read_tokens": 0})