Skip to content
Python

Persist the upstream host a router reports on each reply (served_by)

Devika Verma08e6ab2c7dac
diff --git a/coworker/engine.py b/coworker/engine.py
index 08fc6520..47492d12 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -604,6 +604,8 @@ class TurnEngine:
effort_record = _effort_record(turn, self.model_settings.get("reasoning_effort"))
if effort_record:
payload["reasoning_effort"] = effort_record
+ if turn.served_by:
+ payload["served_by"] = turn.served_by
yield Event(EventType.ASSISTANT_MESSAGE, payload)
if not turn.tool_calls:
@@ -2121,6 +2123,7 @@ class TurnEngine:
"finish_reason",
"max_output_tokens",
"reasoning_effort",
+ "served_by",
"replay",
)
# Auto-compaction (OPE-27): everything before the boundary is represented by the
@@ -2271,6 +2274,9 @@ def _assistant_message(
# The reasoning-effort mapping for this reply (OPE-176). Display sidecar like
# `usage`: stripped before every provider call.
message["reasoning_effort"] = effort_record
+ if turn.served_by:
+ # The upstream host a router reported for this reply (display sidecar).
+ message["served_by"] = turn.served_by
if turn.reasoning:
# Display-only thinking text — rendered by the GUI, stripped for every provider
# (`_outbound_messages`); provider-private replay blocks go via `extras` instead.
diff --git a/coworker/providers/base.py b/coworker/providers/base.py
index 6799b4b6..c197793b 100644
--- a/coworker/providers/base.py
+++ b/coworker/providers/base.py
@@ -82,6 +82,10 @@ class AssistantTurn:
# level was configured or the provider has no such knob. Persisted on the
# assistant message as the `reasoning_effort` sidecar.
effort: Optional[dict[str, Any]] = None
+ # The upstream host that served this reply, when a router names it (OpenRouter's
+ # top-level `provider`, e.g. "Together"). Persisted as the `served_by` sidecar so a
+ # run pinned to one host can prove the pin held on every reply.
+ served_by: Optional[str] = None
@property
def has_tool_calls(self) -> bool:
diff --git a/coworker/providers/openai_provider.py b/coworker/providers/openai_provider.py
index 0ec70c6c..3203981c 100644
--- a/coworker/providers/openai_provider.py
+++ b/coworker/providers/openai_provider.py
@@ -148,6 +148,13 @@ def _effort_record(plan: Optional[EffortPlan], kwargs: dict[str, Any]) -> Option
return plan.record()
+def _served_by(obj: Any) -> Optional[str]:
+ """OpenRouter (and compatible routers) put the upstream host's name in a top-level
+ `provider` field on responses and stream chunks; the OpenAI SDK keeps unknown fields."""
+ value = getattr(obj, "provider", None)
+ return str(value) if isinstance(value, str) and value else None
+
+
def _output_limit(kwargs: dict[str, Any]) -> Optional[int]:
"""The completion ceiling actually sent, after `_param_fix_retry` may have renamed
`max_tokens` to `max_completion_tokens` or dropped it (server default -> None)."""
@@ -259,6 +266,7 @@ class OpenAIProvider(ProviderClient):
usage=_usage_from(getattr(response, "usage", None)),
output_limit=_output_limit(kwargs),
effort=self._note_effort(model, plan, kwargs),
+ served_by=_served_by(response),
)
def capabilities(self, model: str) -> ModelCapabilities:
@@ -318,6 +326,7 @@ class OpenAIProvider(ProviderClient):
tool_accum: dict[int, dict[str, str]] = {}
finish_reason = None
usage: Optional[TokenUsage] = None
+ served: Optional[str] = None
# Up to three param-fix retries: effort, the max_tokens rename, and the
# max_tokens over-limit drop can ALL need fixing on one call.
@@ -330,6 +339,7 @@ class OpenAIProvider(ProviderClient):
else:
chunks = client.chat.completions.create(**kwargs)
for chunk in chunks:
+ served = _served_by(chunk) or served
chunk_usage = _usage_from(getattr(chunk, "usage", None))
if chunk_usage is not None:
usage = chunk_usage
@@ -385,6 +395,7 @@ class OpenAIProvider(ProviderClient):
usage=usage,
output_limit=_output_limit(kwargs),
effort=self._note_effort(model, plan, kwargs),
+ served_by=served,
)
)
diff --git a/tests/test_served_by.py b/tests/test_served_by.py
new file mode 100644
index 00000000..9970cd3b
--- /dev/null
+++ b/tests/test_served_by.py
@@ -0,0 +1,92 @@
+"""OpenAI-compatible routers (OpenRouter) name the upstream host that served a reply in a
+top-level `provider` field. Keep it on the turn and persist it as the `served_by` sidecar,
+so a run pinned to one host can prove the pin held on every reply."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import aisuite as ai
+from coworker.engine import TurnEngine, _assistant_message
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import AssistantTurn, ModelCapabilities, OpenAIProvider, ProviderClient
+from coworker.tools import ToolRegistry
+
+
+class _FakeOpenAI:
+ def __init__(self, *, response=None, stream_chunks=None):
+ self.calls: list[dict] = []
+
+ def create(**kwargs):
+ self.calls.append(kwargs)
+ return stream_chunks if kwargs.get("stream") else response
+
+ self.chat = SimpleNamespace(completions=SimpleNamespace(create=create))
+
+
+def test_openai_complete_keeps_the_serving_host():
+ response = SimpleNamespace(
+ choices=[SimpleNamespace(message=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")],
+ usage=None,
+ provider="Together",
+ )
+ turn = OpenAIProvider(client=_FakeOpenAI(response=response)).complete(
+ model="moonshotai/kimi-k3", messages=[{"role": "user", "content": "x"}]
+ )
+ assert turn.served_by == "Together"
+
+
+def test_openai_stream_keeps_the_serving_host_from_any_chunk():
+ chunks = [
+ SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hi", tool_calls=None), finish_reason=None)], usage=None),
+ SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="!", tool_calls=None), finish_reason="stop")], usage=None, provider="Together"),
+ ]
+ chunks_out = list(
+ OpenAIProvider(client=_FakeOpenAI(stream_chunks=chunks)).stream(
+ model="moonshotai/kimi-k3", messages=[{"role": "user", "content": "x"}]
+ )
+ )
+ assert chunks_out[-1].turn.served_by == "Together"
+
+
+def test_plain_endpoints_leave_it_unset():
+ response = SimpleNamespace(
+ choices=[SimpleNamespace(message=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")],
+ usage=None,
+ )
+ turn = OpenAIProvider(client=_FakeOpenAI(response=response)).complete(
+ model="m", messages=[{"role": "user", "content": "x"}]
+ )
+ assert turn.served_by is None
+ assert "served_by" not in _assistant_message(turn)
+
+
+class _ServedProvider(ProviderClient):
+ def complete(self, *, model, messages, tools=None, **settings):
+ return AssistantTurn(text="done", finish_reason="stop", served_by="Together")
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def test_engine_persists_served_by_and_strips_it_outbound(tmp_path):
+ registry = ToolRegistry()
+ registry.register_all(ai.toolkits.files(root=str(tmp_path), allow_write=True))
+ engine = TurnEngine(
+ provider=_ServedProvider(),
+ registry=registry,
+ permissions=PermissionEngine(workspace_root=tmp_path),
+ model="openrouter:moonshotai/kimi-k3",
+ )
+
+ async def _collect():
+ return [ev async for ev in engine.run("hello")]
+
+ events = asyncio.run(_collect())
+ assistant = next(ev for ev in events if ev.type == EventType.ASSISTANT_MESSAGE)
+ assert assistant.data["served_by"] == "Together"
+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")
+ assert persisted["served_by"] == "Together"
+ assert all("served_by" not in m for m in engine._outbound_messages())