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
The Gemini CLI's helper calls run on the turn's model, the runner gets the canonical id, a failed turn shows its reason (#116)
github-actions[bot]095fa1e02405
diff --git a/docs/support-matrix-notes.md b/docs/support-matrix-notes.mdindex 7bcd5c11..a8df20bf 100644--- a/docs/support-matrix-notes.md+++ b/docs/support-matrix-notes.md@@ -113,3 +113,16 @@ prefix and the key; the CLI keeps its own model id, so the pinned resolutions ancheck are unchanged. OpenRouter and Vercel expose only the OpenAI shape and cannot drive the CLIwithout a translating relay. The TokenRouter column for the gemini backend follows below.+## The Gemini CLI's helper calls run on the turn's model (2026-09-07)++A long Gemini CLI turn (a deck written over five minutes on gemini-3.8-flash, on both trees) ended+failed with its own answer shown as the reason, and its record named a second model. The CLI's+housekeeping calls (model routing, plan mode, context compression, the next-speaker and loop checks)+go to a "flash" or "pro" classifier tier that defaults to gemini-3-flash-preview or+gemini-3-pro-preview, and those calls land in the turn's stats beside the answer model; the served-+model check read them as a switch. Headless gemini-cli has no fallback handler, so the fallback chains+suspected first were never the switch. Both classifier tiers now pin to the turn's own model, so every+model the CLI calls in a turn is the one asked for; the gemini backend takes the canonical id from the+gateway and the relay names it for the provider on the native path (TokenRouter's google/<id>); and a+failed turn's reason is the runner's error before its result.+diff --git a/gateway/app.py b/gateway/app.pyindex ad19fa8c..ca57c8a7 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -6172,7 +6172,14 @@ async def _resp_execute(translator: _RespTranslator, *, org: str, member: str, s"credential cannot be brokered; refused")})continuebody = {"backend": conn.get("backend", backend), "provider": conn.get("provider"),- "model": (conn.get("model") if conn.get("_model_resolved") else _map_model(conn, model_req)),+ # The gemini backend takes the canonical id: gemini-cli's resolution tables and the runner's+ # served-model check key by it, and the provider's own name for it (TokenRouter's+ # google/<id>) rides beside it for the native path. A turn handed "google/gemini-3.8-flash"+ # ran, but its stats and pins no longer matched the id asked for (2026-09-07).+ "model": (model_req if backend == "gemini" and model_req+ else (conn.get("model") if conn.get("_model_resolved") else _map_model(conn, model_req))),+ "native_model": ((conn.get("model") if conn.get("_model_resolved") else _map_model(conn, model_req))+ if backend == "gemini" and model_req else None),"prompt": runner_prompt, "max_turns": max_step,"timeout_seconds": timeout_s,"auth": sandbox_auth, "resume_session_id": resume, "files": files_in,@@ -6327,7 +6334,11 @@ async def _resp_execute(translator: _RespTranslator, *, org: str, member: str, s"error": "turn hit its wall-clock cap"})else:rec["tried"].append({"connection": name, "status": st,- "error": (s.get("result") or s.get("error") or "")[:200]})+ # The runner's `error` is the reason (the provider's refusal, the result+ # event's message); its `result` is the answer so far, which a failed turn+ # may still carry. Reason first: a Gemini CLI turn that failed as a+ # substitution showed its finished answer as the error (2026-09-07).+ "error": (s.get("error") or s.get("result") or "")[:200]})break_last_err = str(rec["tried"][-1].get("error") or "") if rec["tried"] else ""if (not terminal and rec["tried"] and rec["tried"][-1].get("connection") == namediff --git a/gateway/tests/test_gemini_backend.py b/gateway/tests/test_gemini_backend.pyindex dd1d2207..5e710a02 100644--- a/gateway/tests/test_gemini_backend.py+++ b/gateway/tests/test_gemini_backend.py@@ -47,3 +47,9 @@ def test_tokenrouter_drives_the_gemini_backend_for_the_ids_it_serves():assert "gemini-3.8-flash" in gw._integration_models(tr) and "gemini-2.5-flash" not in gw._integration_models(tr)# an id TokenRouter has no channel for falls through to the Google integration when the map named TokenRouter for itassert gw._integration_driving([tr, google], "gemini", "gemini-2.5-flash", "Google AI Studio") is google+++def test_the_failed_turn_reason_is_the_runners_error_before_its_result():+ src = Path(gw.__file__).read_text()+ assert '"error": (s.get("error") or s.get("result") or "")[:200]' in src+ assert '"native_model": ((conn.get("model") if conn.get("_model_resolved") else _map_model(conn, model_req))' in srcdiff --git a/runner/server.py b/runner/server.pyindex 530f250f..b0324523 100644--- a/runner/server.py+++ b/runner/server.py@@ -2477,8 +2477,12 @@ class _HermesRelayHandler(http.server.BaseHTTPRequestHandler):headers.setdefault("accept", "*/*")if flags.get("google_native"):# Google's native API on a provider that serves it (TokenRouter: models/google/<id>:- # generateContent, measured 2026-09-07): the path goes through as the CLI made it, the model- # already named the way the connection's vendor table does, and the key rides x-goog-api-key.+ # generateContent, measured 2026-09-07). The CLI asks for the canonical id, which its tables+ # and the served-model check key by; the relay names it the way the provider does on the+ # path, as the hosted broker does, and the key rides x-goog-api-key.+ m, nm = str(flags.get("model") or ""), str(flags.get("native_model") or "")+ if m and nm and nm != m:+ tail = tail.replace(f"/models/{m}:", f"/models/{nm}:", 1)headers["x-goog-api-key"] = key# Compare the PATH only: anthropic clients append query strings (claude-code sends# /v1/messages?beta=true on streaming requests), and matching the raw tail let those@@ -2757,7 +2761,7 @@ def _relay_base_with_version(base_url: str) -> str:return base + "/v1"-def _gemini_relay_route(host_root: str, api_key: str) -> tuple[str, str]:+def _gemini_relay_route(host_root: str, api_key: str, model: str = "", native_model: str = "") -> tuple[str, str]:"""Register one gemini turn's upstream for Google's native API on a provider that serves it: thehost root, no version segment, since the CLI appends /v1beta/models/<id>:... itself and names themodel the way the gateway resolved it through the connection's vendor table (google/<id> on@@ -2769,7 +2773,8 @@ def _gemini_relay_route(host_root: str, api_key: str) -> tuple[str, str]:threading.Thread(target=srv.serve_forever, daemon=True).start()_HERMES_RELAY["server"], _HERMES_RELAY["port"] = srv, srv.server_address[1]tok = "hr-relay-" + uuid.uuid4().hex- _HERMES_RELAY["routes"][tok] = (host_root.rstrip("/"), api_key, {"google_native": True})+ _HERMES_RELAY["routes"][tok] = (host_root.rstrip("/"), api_key,+ {"google_native": True, "model": model, "native_model": native_model})return f"http://127.0.0.1:{_HERMES_RELAY['port']}/v1", tok@@ -3030,20 +3035,26 @@ def _gemini_settings(home: pathlib.Path, mcp_servers: list[dict] | None, model:continueservers[name] = entrypinned = sorted(set(GEMINI_MODELS) | ({model} if model else set()))- # No fallback either: on a quota or transient error gemini-cli's fallback handler picks the next- # policy of the model's chain (its default preview chain ends in gemini-3-flash-preview as the- # last resort), and in headless mode that switch is silent; a 5-minute turn on gemini-3.8-flash- # finished its work on gemini-3-flash-preview that way (2026-09-07 02:10Z). Every chain the CLI- # can resolve for this turn is one policy, the turn's own model: with no other candidate the- # handler has nothing to switch to and the provider's error ends the turn, honestly. Retries- # stay on the same model (sticky_retry on transient and unknown failures).+ # No fallback either: every chain the CLI can resolve for this turn is one policy, the turn's+ # own model, so its fallback handler has no candidate to switch to and the provider's error ends+ # the turn honestly (retries stay on the same model: sticky_retry on transient and unknown+ # failures). Measured after this landed: headless gemini-cli has no fallback handler, so the+ # chains were never the switch; the second model the 2026-09-07 02:10Z turn showed was the+ # classifier tier below. The chains stay as the guard they are.own = [{"model": model or GEMINI_DEFAULT_MODEL, "isLastResort": True, "maxAttempts": 3,"actions": {"terminal": "prompt", "transient": "prompt", "not_found": "prompt", "unknown": "prompt"},"stateTransitions": {"terminal": "terminal", "transient": "sticky_retry", "not_found": "terminal", "unknown": "sticky_retry"}}]cfg: dict = {"security": {"auth": {"selectedType": "gemini-api-key"}},# the ids are honest: -m resolves through this table, and each entry pins an id to itself"experimental": {"dynamicModelConfiguration": True},+ # The CLI's own housekeeping calls (model routing, plan mode, context compression, the+ # next-speaker and loop checks) go to a "flash" or "pro" classifier tier that defaults to+ # gemini-3-flash-preview or gemini-3-pro-preview, and those calls land in the turn's stats+ # beside the answer model: a five-minute turn on gemini-3.8-flash showed+ # "gemini-3-flash-preview" too and failed as a substitution (2026-09-07, both trees).+ # Every model the CLI calls in a turn is the one asked for: both tiers pin to it."modelConfigs": {"modelIdResolutions": {m: {"default": m, "contexts": []} for m in pinned},+ "classifierIdResolutions": {t: {"default": model or GEMINI_DEFAULT_MODEL, "contexts": []} for t in ("flash", "pro")},"modelChains": {k: own for k in ("preview", "default", "lite", "auto-preview", "auto-default")}}}if servers:cfg["mcpServers"] = servers@@ -3051,7 +3062,8 @@ def _gemini_settings(home: pathlib.Path, mcp_servers: list[dict] | None, model:def _build_gemini(provider: str, auth: Auth, model: str, prompt: str, cwd: str, env: dict,- resume_session_id: str | None = None, mcp_servers: list[dict] | None = None) -> list[str]:+ resume_session_id: str | None = None, mcp_servers: list[dict] | None = None,+ native_model: str | None = None) -> list[str]:pr = provider or "google"if pr not in GEMINI_PROVIDERS:raise HTTPException(400, f"unknown gemini provider '{pr}' (one of {sorted(GEMINI_PROVIDERS)})")@@ -3066,7 +3078,7 @@ def _build_gemini(provider: str, auth: Auth, model: str, prompt: str, cwd: str,# loopback relay, which owns the prefix and the real key; the CLI keeps its own model id, so# the pinned resolutions and the served-model check below are unchanged.root = urllib.parse.urlsplit(auth.base_url)- relay_base, relay_tok = _gemini_relay_route(f"{root.scheme}://{root.netloc}", auth.api_key)+ relay_base, relay_tok = _gemini_relay_route(f"{root.scheme}://{root.netloc}", auth.api_key, model, native_model or "")env["GOOGLE_GEMINI_BASE_URL"] = relay_baseenv["GEMINI_API_KEY"] = relay_tokelse:@@ -4708,6 +4720,7 @@ class TurnReq(BaseModel):backend: str = "claude" # claude | codex | hermes | pi | dshprovider: str | None = None # see BACKENDS[...].providersmodel: str | None = None+ native_model: str | None = None # gemini: the provider's own name for `model` on the native path (TokenRouter's google/<id>)prompt: strmax_turns: int = 400timeout_seconds: int | None = None # per-turn wall-clock cap (bounded by MAX_TURN_SECONDS)@@ -4862,7 +4875,8 @@ def turn(req: TurnReq, identifier: str = "") -> dict:elif backend == "gemini":model = model or GEMINI_DEFAULT_MODELcmd = _build_gemini(req.provider, auth, model, req.prompt, cwd, env,- resume_session_id=req.resume_session_id, mcp_servers=req.mcp_servers)+ resume_session_id=req.resume_session_id, mcp_servers=req.mcp_servers,+ native_model=req.native_model)elif backend == "cline":model = model or CLINE_DEFAULT_MODELcmd = _build_cline(req.provider, auth, model, req.prompt, cwd, env,diff --git a/runner/tests/test_gemini_build.py b/runner/tests/test_gemini_build.pyindex d5810f04..9d7a9317 100644--- a/runner/tests/test_gemini_build.py+++ b/runner/tests/test_gemini_build.py@@ -254,18 +254,31 @@ def test_a_failed_result_never_reads_as_the_answer_and_a_substitution_names_the_assert both[0]["result"] == "the CLI ran gemini-3-flash-preview instead of gemini-3.8-flash (the CLI ended with unknown: [API Error: quota])"-def test_a_tokenrouter_connection_points_the_cli_at_the_relay_which_carries_the_key():- """TokenRouter serves Google's native API (models/google/<id>:generateContent, the key in- x-goog-api-key; measured 2026-09-07). The gateway names the model through the vendor table, so- the CLI already asks for google/<id>; the relay re-roots the path at the host and carries the key."""+def test_a_tokenrouter_connection_points_the_cli_at_the_relay_which_names_the_model_and_carries_the_key():+ """TokenRouter serves Google's native API under its own name for the model (models/google/<id>:,+ the key in x-goog-api-key; measured 2026-09-07). The CLI asks for the canonical id, which its+ tables and the served-model check key by; the relay names it for the provider on the path."""d = tempfile.mkdtemp(); env: dict = {}- _build_gemini("google", Auth(api_key="tr-real", base_url="https://api.tokenrouter.com/v1"), "google/gemini-3.8-flash", "hi", d, env)+ _build_gemini("google", Auth(api_key="tr-real", base_url="https://api.tokenrouter.com/v1"), "gemini-3.8-flash", "hi", d, env, native_model="google/gemini-3.8-flash")assert env["GOOGLE_GEMINI_BASE_URL"].startswith("http://127.0.0.1:") and env["GOOGLE_GEMINI_BASE_URL"].endswith("/v1")assert env["GEMINI_API_KEY"] != "tr-real"base, key, flags = _HERMES_RELAY["routes"][env["GEMINI_API_KEY"]]- assert base == "https://api.tokenrouter.com" and key == "tr-real" and flags == {"google_native": True}+ assert base == "https://api.tokenrouter.com" and key == "tr-real"+ assert flags == {"google_native": True, "model": "gemini-3.8-flash", "native_model": "google/gemini-3.8-flash"}cfg = json.loads(pathlib.Path(d, ".harness", "home", ".gemini", "settings.json").read_text())- assert cfg["modelConfigs"]["modelIdResolutions"]["google/gemini-3.8-flash"] == {"default": "google/gemini-3.8-flash", "contexts": []}+ assert cfg["modelConfigs"]["modelIdResolutions"]["gemini-3.8-flash"] == {"default": "gemini-3.8-flash", "contexts": []}d2 = tempfile.mkdtemp(); env2: dict = {}_build_gemini("google", Auth(api_key="AIza-t", base_url="https://generativelanguage.googleapis.com/v1beta/openai"), "gemini-3.8-flash", "hi", d2, env2)assert "GOOGLE_GEMINI_BASE_URL" not in env2 and env2["GEMINI_API_KEY"] == "AIza-t" # Google direct, as before+++def test_the_helper_model_tiers_are_the_turns_own_model():+ """The CLI's routing, plan, compression and loop checks use its flash or pro classifier tier; a+ turn's stats then name that helper model too, which read as a substitution (2026-09-07)."""+ _, d, _ = _argv()+ cls = json.loads(pathlib.Path(d, ".harness", "home", ".gemini", "settings.json").read_text())["modelConfigs"]["classifierIdResolutions"]+ assert cls == {"flash": {"default": "gemini-3.6-flash", "contexts": []}, "pro": {"default": "gemini-3.6-flash", "contexts": []}}+ # a helper model that still shows beside the answer model is a substitution, and fails the turn+ stats = {"input_tokens": 10, "output_tokens": 2, "cached": 0, "models": {"gemini-3.8-flash": {}, "gemini-3-flash-preview": {}}}+ out = _gemini_to_claude({"type": "result", "status": "success", "stats": stats}, {"model": "gemini-3.8-flash", "final": "done"})+ assert out[0]["is_error"] is True and out[0]["result"] == "the CLI ran gemini-3-flash-preview instead of gemini-3.8-flash"