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
TokenRouter serves the Gemini CLI backend on Google's native API (#115)
github-actions[bot]cc880c206e1f
diff --git a/docs/support-matrix-notes.md b/docs/support-matrix-notes.mdindex 5dcc6ab0..7bcd5c11 100644--- a/docs/support-matrix-notes.md+++ b/docs/support-matrix-notes.md@@ -100,3 +100,16 @@ later ones the connection of every turn record.gemini-3.5-flash on every turn, the CLI's own rewrite); the backend lists the seven ids served asthemselves.+## The gemini backend through TokenRouter (2026-09-07)++TokenRouter serves Google's native API when the model carries its vendor prefix:+`POST https://api.tokenrouter.com/v1beta/models/google/gemini-3.8-flash:generateContent` (and+`:streamGenerateContent?alt=sse`) with the key in `x-goog-api-key` answers in Google's own shape;+without the prefix, and for the ids it has no channel for (gemini-3.1-flash-lite, 2.5-pro, 2.5-flash,+2.5-flash-lite), it refuses "No available channel". So the seven Gemini ids in TokenRouter's table run+on the Gemini CLI through the platform key. In owner trust the CLI reaches the provider itself, so a+TokenRouter connection points GOOGLE_GEMINI_BASE_URL at the loopback relay, which owns the vendor+prefix and the key; the CLI keeps its own model id, so the pinned resolutions and the served-model+check are unchanged. OpenRouter and Vercel expose only the OpenAI shape and cannot drive the CLI+without a translating relay. The TokenRouter column for the gemini backend follows below.+diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex fb127bf5..04b6d18b 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -187,7 +187,7 @@ Scenarios: first turn, follow-up in the same session, switch model mid-session,| Harness | Model | First | Follow-up | Switch | Artifact | Recycle | Served by | Notes ||---|---|---|---|---|---|---|---|---|-| gemini | gemini-2.5-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | served as gemini-3.5-flash (finding below) |+| gemini | gemini-2.5-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | || gemini | gemini-2.5-flash-lite | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | || gemini | gemini-2.5-pro | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | || gemini | gemini-3-flash-preview | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | |@@ -195,18 +195,11 @@ Scenarios: first turn, follow-up in the same session, switch model mid-session,| gemini | gemini-3.1-pro-preview | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | || gemini | gemini-3.5-flash | pass | pass | pass (gemini-3.8-flash) | pass | pass | Google AI Studio | || gemini | gemini-3.5-flash-lite | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | |-| gemini | gemini-3.6-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | served as gemini-3.5-flash (finding below) |-| gemini | gemini-3.7-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | served as gemini-3.5-flash (finding below) |-| gemini | gemini-3.8-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | served as gemini-3.5-flash (finding below) |+| gemini | gemini-3.6-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | |+| gemini | gemini-3.7-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | |+| gemini | gemini-3.8-flash | pass | pass | pass (gemini-3.5-flash) | pass | pass | Google AI Studio | |-11 pairs, 35 of 35 scenario runs passed; 4 pairs served by another connection or as another model are findings, not counted.--Findings, pairs served by a connection other than the one under test or as a model other than the id asked for:--- gemini x gemini-2.5-flash: served as gemini-3.5-flash (the CLI reports the model it ran)-- gemini x gemini-3.6-flash: served as gemini-3.5-flash (the CLI reports the model it ran)-- gemini x gemini-3.7-flash: served as gemini-3.5-flash (the CLI reports the model it ran)-- gemini x gemini-3.8-flash: served as gemini-3.5-flash (the CLI reports the model it ran)+11 pairs, 55 of 55 scenario runs passed.## Provider: gemini-google@@ -485,6 +478,24 @@ Findings, pairs served by a connection other than the one under test or as a mod5 pairs, 6 of 8 scenario runs passed.+## Provider: omp-google++| Harness | Model | First | Follow-up | Switch | Artifact | Recycle | Served by | Notes |+|---|---|---|---|---|---|---|---|---|+| omp | gemini-2.5-flash | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-2.5-flash-lite | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-2.5-pro | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3-flash-preview | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.1-flash-lite | n/a | n/a | n/a | n/a | n/a | ? | retested once; first try: artifact no file card (files: none); Create a file named hello-omp.txt containing exactly |+| omp | gemini-3.1-pro-preview | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.5-flash | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.5-flash-lite | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.6-flash | pass | pass | pass (gemini-3.8-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.7-flash | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |+| omp | gemini-3.8-flash | pass | pass | pass (gemini-3.6-flash) | pass | pass | Google AI Studio | |++11 pairs, 50 of 50 scenario runs passed.+## Provider: openai| Harness | Model | First | Follow-up | Switch | Artifact | Recycle | Served by | Notes |diff --git a/gateway/app.py b/gateway/app.pyindex 400982a1..ad19fa8c 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -1080,6 +1080,11 @@ _INTEGRATION_WIRING: dict[tuple[str, str], str] = {# reason it is absent from _CUSTOM_FORMAT_BACKENDS: a custom integration is OpenAI- or# Anthropic-shaped.("google", "gemini"): "google",+ # TokenRouter serves Google's native API under the vendor prefix (models/google/<id>:, key in+ # x-goog-api-key; measured 2026-09-07) for the seven Gemini ids its table carries, so it drives+ # the gemini backend too; the runner still builds gemini as provider google and routes the CLI+ # through its relay when the connection is TokenRouter.+ ("tokenrouter", "gemini"): "google",}diff --git a/gateway/tests/test_gemini_backend.py b/gateway/tests/test_gemini_backend.pyindex 2603e110..dd1d2207 100644--- a/gateway/tests/test_gemini_backend.py+++ b/gateway/tests/test_gemini_backend.py@@ -37,3 +37,13 @@ def test_the_served_model_rides_the_result_onto_the_record():tr._handle("result", {"text": "PONG", "usage": {"input_tokens": 1, "output_tokens": 1}, "is_error": False, "model": "gemini-3.5-flash"})assert tr.served_model == "gemini-3.5-flash"assert tr.record()["served_model"] == "gemini-3.5-flash" if hasattr(tr, "record") else True+++def test_tokenrouter_drives_the_gemini_backend_for_the_ids_it_serves():+ assert gw._INTEGRATION_WIRING[("tokenrouter", "gemini")] == "google"+ tr = {"name": "My TokenRouter", "provider": "tokenrouter", "config": {"api_key": "t", "base_url": "https://api.tokenrouter.com/v1"}}+ google = {"name": "Google AI Studio", "provider": "google", "config": {"api_key": "g"}}+ assert gw._integration_driving([tr, google], "gemini", "gemini-3.8-flash", "My TokenRouter") is tr+ 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 it+ assert gw._integration_driving([tr, google], "gemini", "gemini-2.5-flash", "Google AI Studio") is googlediff --git a/runner/server.py b/runner/server.pyindex e4ccf1f3..530f250f 100644--- a/runner/server.py+++ b/runner/server.py@@ -2454,6 +2454,8 @@ class _HermesRelayHandler(http.server.BaseHTTPRequestHandler):def _upstream(self) -> tuple[str, str] | None:tok = (self.headers.get("authorization") or "").removeprefix("Bearer ").strip()+ if not tok:+ tok = (self.headers.get("x-goog-api-key") or "").strip() # gemini-cli's header for its keyreturn _HERMES_RELAY["routes"].get(tok)def _forward(self, body: bytes | None) -> None:@@ -2468,11 +2470,16 @@ class _HermesRelayHandler(http.server.BaseHTTPRequestHandler):returnbase, key, flags = routetail = self.path.removeprefix("/v1") if self.path.startswith("/v1/") else self.path- drop = {"host", "content-length", "authorization", "connection",+ drop = {"host", "content-length", "authorization", "x-goog-api-key", "connection","accept-encoding", "transfer-encoding"}headers = {k: v for k, v in self.headers.items() if k.lower() not in drop}headers["authorization"] = f"Bearer {key}"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.+ 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# fall through to a generic forward against a host with no such route.@@ -2750,6 +2757,22 @@ 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]:+ """Register one gemini turn's upstream for Google's native API on a provider that serves it: the+ host root, no version segment, since the CLI appends /v1beta/models/<id>:... itself and names the+ model the way the gateway resolved it through the connection's vendor table (google/<id> on+ TokenRouter). The same shape as the hosted broker's native path: re-rooted at the provider's host,+ the key in x-goog-api-key. → (GOOGLE_GEMINI_BASE_URL for the CLI, placeholder key)."""+ with _HERMES_RELAY["lock"]:+ if _HERMES_RELAY["server"] is None:+ srv = http.server.ThreadingHTTPServer(("127.0.0.1", 0), _HermesRelayHandler)+ 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})+ return f"http://127.0.0.1:{_HERMES_RELAY['port']}/v1", tok++def _hermes_relay_route(base_url: str, api_key: str) -> tuple[str, str]:"""Register one turn's upstream; → (relay base_url, placeholder bearer for the CLI)."""with _HERMES_RELAY["lock"]:@@ -3037,7 +3060,17 @@ def _build_gemini(provider: str, auth: Auth, model: str, prompt: str, cwd: str,home = pathlib.Path(cwd) / ".harness" / "home"home.mkdir(parents=True, exist_ok=True)env["HOME"] = str(home) # sessions/skills/settings live INSIDE the workspace- env["GEMINI_API_KEY"] = auth.api_key+ if auth.base_url and _STRICT_GEMINI_HOST in auth.base_url:+ # A TokenRouter connection: it serves Google's native API under the vendor prefix (measured+ # 2026-09-07 for the seven Gemini ids its table carries), so the CLI is pointed at the+ # 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)+ env["GOOGLE_GEMINI_BASE_URL"] = relay_base+ env["GEMINI_API_KEY"] = relay_tok+ else:+ env["GEMINI_API_KEY"] = auth.api_key_gemini_settings(home, mcp_servers, model)cmd = ["gemini", "-p", prompt, "-o", "stream-json", "-m", model,# Load-bearing, same risk class as qwen's --yolo: gemini-cli gates tool use behind adiff --git a/runner/tests/test_gemini_build.py b/runner/tests/test_gemini_build.pyindex ff819ead..d5810f04 100644--- a/runner/tests/test_gemini_build.py+++ b/runner/tests/test_gemini_build.py@@ -9,7 +9,7 @@ import tempfilesys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))from server import (Auth, _agent_doc_path, _build_gemini, _gemini_to_claude, # noqa: E402- _gemini_usage, _norm_token_usage, BACKENDS, GEMINI_MODELS)+ _gemini_usage, _norm_token_usage, BACKENDS, GEMINI_MODELS, _HERMES_RELAY)def _argv(**kw):@@ -252,3 +252,20 @@ def test_a_failed_result_never_reads_as_the_answer_and_a_substitution_names_the_both = _gemini_to_claude({"type": "result", "status": "error", "stats": {**st, "models": {"gemini-3.8-flash": {}, "gemini-3-flash-preview": {}}},"error": {"type": "unknown", "message": "[API Error: quota]"}}, {"model": "gemini-3.8-flash", "final": "I built the deck."})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."""+ 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)+ 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}+ 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": []}+ 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