Python
Persist finish_reason on assistant messages (OPE-173)
Devika Vermaa6677e00caf9
diff --git a/coworker/engine.py b/coworker/engine.pyindex e492443c..f181c7fc 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -559,6 +559,9 @@ class TurnEngine:payload["reasoning"] = turn.reasoningif turn.usage is not None:payload["usage"] = {"model": self.model, **turn.usage.as_dict()}+ if turn.finish_reason:+ # How the reply ended (OPE-173): `stop` / `tool_calls` / `length`.+ payload["finish_reason"] = turn.finish_reasonyield Event(EventType.ASSISTANT_MESSAGE, payload)if not turn.tool_calls:@@ -1982,10 +1985,10 @@ class TurnEngine:"""# Strip the display-only sidecars — `source` (connector cards), `_display`# (e.g. filter-hidden counts), `ts` (append-time timestamps), `reasoning`- # (thinking text), and `usage` (token counts) — copying only messages that carry- # one. Whole `notice` messages (error/interrupted/model-switch markers) are- # display-only too: dropped entirely.- _SIDECARS = ("source", "_display", "ts", "reasoning", "usage")+ # (thinking text), `usage` (token counts), and `finish_reason` (how the reply+ # ended) — copying only messages that carry one. Whole `notice` messages+ # (error/interrupted/model-switch markers) are display-only too: dropped entirely.+ _SIDECARS = ("source", "_display", "ts", "reasoning", "usage", "finish_reason")# Auto-compaction (OPE-27): everything before the boundary is represented by the# compacted block. Outbound-only — the canonical history stays intact — and the# block+tail are byte-stable between turns, so prompt caching keeps working.@@ -2095,6 +2098,15 @@ def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict# stripped before provider calls. Tagged with the model that produced it so# per-model rollups survive mid-session model switches.message["usage"] = {"model": model, **turn.usage.as_dict()}+ if turn.finish_reason:+ # How the reply ended, in the engine's normalised vocabulary (`stop` /+ # `tool_calls` / `length`; unknown provider values pass through). Persisted+ # so a saved session can tell "chose to stop" from "hit the output limit"+ # without re-deriving it from token counts (OPE-173). Omitted — never null —+ # for partial turns and providers that report no stop reason. Stripped before+ # every provider call (`_outbound_messages`). The provider's raw value, where+ # it differs, lives in that provider's sidecar (e.g. `_anthropic.stop_reason`).+ message["finish_reason"] = turn.finish_reasonif 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/anthropic_provider.py b/coworker/providers/anthropic_provider.pyindex 0cf0e08e..0e4d59c4 100644--- a/coworker/providers/anthropic_provider.py+++ b/coworker/providers/anthropic_provider.py@@ -376,9 +376,20 @@ def _reasoning_text(thinking_blocks: list[dict[str, Any]]) -> Optional[str]:return text or None-def _thinking_extras(thinking_blocks: list[dict[str, Any]]) -> dict[str, Any]:- """Raw blocks → the `_anthropic` sidecar convert_messages replays (empty when none)."""- return {"_anthropic": {"blocks": thinking_blocks}} if thinking_blocks else {}+def _anthropic_extras(+ thinking_blocks: list[dict[str, Any]], stop_reason: Any = None+) -> dict[str, Any]:+ """The `_anthropic` sidecar persisted on the assistant message (empty when nothing+ to keep): raw thinking blocks, which convert_messages replays verbatim, and the raw+ `stop_reason` (OPE-173) so values the engine's finish_reason map collapses —+ `pause_turn`, `stop_sequence` → "stop" — stay recoverable from a saved session.+ convert_messages only reads `blocks`; other providers strip the whole key."""+ sidecar: dict[str, Any] = {}+ if thinking_blocks:+ sidecar["blocks"] = thinking_blocks+ if stop_reason:+ sidecar["stop_reason"] = stop_reason+ return {"_anthropic": sidecar} if sidecar else {}class AnthropicProvider(ProviderClient):@@ -526,7 +537,7 @@ class AnthropicProvider(ProviderClient):finish_reason=_STOP_REASON_MAP.get(stop_reason, stop_reason),raw=response,reasoning=_reasoning_text(thinking_blocks),- extras=_thinking_extras(thinking_blocks),+ extras=_anthropic_extras(thinking_blocks, stop_reason),usage=_usage_from(getattr(response, "usage", None)),)@@ -647,7 +658,7 @@ class AnthropicProvider(ProviderClient):tool_calls=tool_calls,finish_reason=_STOP_REASON_MAP.get(stop_reason, stop_reason),reasoning=_reasoning_text(thinking_blocks),- extras=_thinking_extras(thinking_blocks),+ extras=_anthropic_extras(thinking_blocks, stop_reason),usage=usage,))diff --git a/tests/test_finish_reason.py b/tests/test_finish_reason.pynew file mode 100644index 00000000..c1b877dd--- /dev/null+++ b/tests/test_finish_reason.py@@ -0,0 +1,189 @@+"""OPE-173: the provider's stop reason is persisted on the assistant message.++The engine already receives `AssistantTurn.finish_reason` (`stop` / `tool_calls` /+`length`, normalised per provider) and uses it transiently (`_turn_truncated`). These+tests pin down that it is also (a) written to the saved message as a sidecar, (b) carried+on the ASSISTANT_MESSAGE event, (c) stripped before any provider call, and (d) that the+Anthropic provider keeps its raw `stop_reason` in the `_anthropic` sidecar so values the+normalisation collapses (`pause_turn`, `stop_sequence` → `stop`) are not lost.+"""++from __future__ import annotations++import asyncio+from contextlib import contextmanager+from types import SimpleNamespace++import aisuite as ai+import pytest+from coworker.engine import TurnEngine, _assistant_message+from coworker.events import EventType+from coworker.permissions import PermissionEngine+from coworker.providers import (+ AnthropicProvider,+ AssistantTurn,+ ModelCapabilities,+ ProviderClient,+ ToolCall,+)+from coworker.tools import ToolRegistry+++# -- engine plumbing ----------------------------------------------------------------+++class _OneTurnProvider(ProviderClient):+ def __init__(self, turn: AssistantTurn):+ self._turn = turn++ def complete(self, *, model, messages, tools=None, **settings):+ return self._turn++ def capabilities(self, model):+ return ModelCapabilities()+++def _run_engine(tmp_path, turn: AssistantTurn):+ registry = ToolRegistry()+ registry.register_all(ai.toolkits.files(root=str(tmp_path), allow_write=True))+ engine = TurnEngine(+ provider=_OneTurnProvider(turn),+ registry=registry,+ permissions=PermissionEngine(workspace_root=tmp_path),+ model="gpt-5.5",+ )++ async def _collect():+ return [ev async for ev in engine.run("hello")]++ return engine, asyncio.run(_collect())++[email protected]("finish_reason", ["stop", "length"])+def test_engine_persists_finish_reason_on_message_and_event(tmp_path, finish_reason):+ turn = AssistantTurn(text="partial answer", finish_reason=finish_reason)+ engine, events = _run_engine(tmp_path, turn)++ assistant = next(ev for ev in events if ev.type == EventType.ASSISTANT_MESSAGE)+ assert assistant.data["finish_reason"] == finish_reason++ persisted = next(m for m in engine.messages if m.get("role") == "assistant")+ assert persisted["finish_reason"] == finish_reason+++def test_outbound_messages_strip_finish_reason_sidecar(tmp_path):+ engine, _ = _run_engine(tmp_path, AssistantTurn(text="done", finish_reason="stop"))+ assert any("finish_reason" in m for m in engine.messages)+ assert all("finish_reason" not in m for m in engine._outbound_messages())+++def test_assistant_message_omits_finish_reason_when_unknown():+ """Partial turns (interrupt / provider error mid-stream) and providers that never+ report a stop reason must not write a `finish_reason: null` key."""+ message = _assistant_message(AssistantTurn(text="half a reply"))+ assert "finish_reason" not in message+++def test_assistant_message_keeps_finish_reason_with_tool_calls():+ turn = AssistantTurn(+ tool_calls=[ToolCall(id="c1", name="read_file", arguments={"path": "x"})],+ finish_reason="tool_calls",+ )+ message = _assistant_message(turn, model="m")+ assert message["finish_reason"] == "tool_calls"+ assert message["tool_calls"][0]["function"]["name"] == "read_file"+++# -- Anthropic raw stop reason ------------------------------------------------------+++class _FakeClient:+ def __init__(self, response=None, events=None):+ self.kwargs: dict = {}++ def create(**kwargs):+ self.kwargs = kwargs+ if kwargs.get("stream"):+ return iter(events or [])+ return response++ @contextmanager+ def stream(**kwargs):+ self.kwargs = kwargs+ yield SimpleNamespace(get_final_message=lambda: response)++ self.messages = SimpleNamespace(create=create, stream=stream)+ self.beta = SimpleNamespace(messages=SimpleNamespace(create=create, stream=stream))+++def _text_response(text="hello", stop_reason="end_turn"):+ return SimpleNamespace(+ content=[SimpleNamespace(type="text", text=text)],+ stop_reason=stop_reason,+ )+++ "stop_reason,expected",+ [+ ("end_turn", "stop"),+ ("max_tokens", "length"),+ ("pause_turn", "stop"), # collapsed by the map — only the sidecar keeps it+ ("stop_sequence", "stop"),+ ],+)+def test_anthropic_complete_keeps_raw_stop_reason_in_sidecar(stop_reason, expected):+ provider = AnthropicProvider(+ client=_FakeClient(response=_text_response(stop_reason=stop_reason))+ )+ turn = provider.complete(model="m", messages=[{"role": "user", "content": "x"}])+ assert turn.finish_reason == expected+ assert turn.extras["_anthropic"]["stop_reason"] == stop_reason+++def test_anthropic_stream_keeps_raw_stop_reason_in_sidecar():+ events = [+ SimpleNamespace(+ type="content_block_start",+ index=0,+ content_block=SimpleNamespace(type="text", text=""),+ ),+ SimpleNamespace(+ type="content_block_delta",+ index=0,+ delta=SimpleNamespace(type="text_delta", text="cut off mid"),+ ),+ SimpleNamespace(+ type="message_delta", delta=SimpleNamespace(stop_reason="max_tokens")+ ),+ ]+ provider = AnthropicProvider(client=_FakeClient(events=events))+ chunks = list(+ provider.stream(model="m", messages=[{"role": "user", "content": "x"}])+ )+ turn = chunks[-1].turn+ assert turn.finish_reason == "length"+ assert turn.extras["_anthropic"]["stop_reason"] == "max_tokens"+++def test_anthropic_sidecar_with_stop_reason_replays_cleanly():+ """A persisted assistant message carrying `_anthropic.stop_reason` but no thinking+ blocks must convert back to the wire shape without error or extra blocks."""+ fake = _FakeClient(response=_text_response())+ provider = AnthropicProvider(client=fake)+ history = [+ {"role": "user", "content": "x"},+ {+ "role": "assistant",+ "content": "earlier reply",+ "_anthropic": {"stop_reason": "end_turn"},+ "finish_reason": "stop", # would be stripped by the engine; belt and braces+ },+ {"role": "user", "content": "y"},+ ]+ provider.complete(model="m", messages=history)+ sent = fake.kwargs["messages"]+ assistant = next(m for m in sent if m["role"] == "assistant")+ assert assistant["content"] == [{"type": "text", "text": "earlier reply"}]+ assert "finish_reason" not in assistant+ assert "_anthropic" not in assistant