Python
Add a reasoning_effort setting translated per provider and recorded per reply (OPE-176)
Devika Verma1746c9ae20ea
diff --git a/coworker/agent.py b/coworker/agent.pyindex 8ea2100e..29fde87a 100644--- a/coworker/agent.py+++ b/coworker/agent.py@@ -269,6 +269,9 @@ def build_engine(# An explicit `max_tokens` from the caller wins over the config value.if config.max_output_tokens is not None and "max_tokens" not in (model_settings or {}):model_settings = {**(model_settings or {}), "max_tokens": config.max_output_tokens}+ # OPE-176: the reasoning-effort level takes the same route; providers translate it.+ if config.reasoning_effort and "reasoning_effort" not in (model_settings or {}):+ model_settings = {**(model_settings or {}), "reasoning_effort": config.reasoning_effort}executor = LocalExecutor(cwd=ws) if ws is not None else Nonetodo = TodoList()context = AgentContext(diff --git a/coworker/config.py b/coworker/config.pyindex 60cb69e3..f98f2c76 100644--- a/coworker/config.py+++ b/coworker/config.py@@ -29,6 +29,11 @@ from .secrets import state_dirDEFAULT_ALLOWED_COMMANDS: list[str] = []+# Reasoning-effort levels (OPE-176), mirroring Anthropic's vocabulary; each provider+# maps a level to what its wire accepts (coworker/providers/effort.py).+EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high", "xhigh", "max")++@dataclassclass Config:model: str = "gpt-5.6-sol"@@ -40,6 +45,12 @@ class Config:# Bedrock 4,096). Anthropic recommends ~64,000 at high effort. Environment override:# COWORKER_MAX_OUTPUT_TOKENS. Explicit `build_engine(model_settings=...)` wins.max_output_tokens: Optional[int] = None+ # How hard the model should think per reply: one of EFFORT_LEVELS. Unset = send no+ # effort parameter at all (Anthropic's API default is high; Together's default for+ # Kimi K3 is max), so existing requests are unchanged. Held constant for a whole+ # session — changing it mid-conversation restarts the prompt cache. Environment+ # override: COWORKER_REASONING_EFFORT.+ reasoning_effort: Optional[str] = Noneallowed_commands: list[str] = field(default_factory=lambda: list(DEFAULT_ALLOWED_COMMANDS))@@ -88,6 +99,7 @@ _FIELDS = {"mode","max_iterations","max_output_tokens",+ "reasoning_effort","allowed_commands","auto_allow","allowed_domains",@@ -139,6 +151,21 @@ def workspace_allowed_commands(workspace: str | Path) -> list[str]:MAX_OUTPUT_TOKENS_ENV = "COWORKER_MAX_OUTPUT_TOKENS"+REASONING_EFFORT_ENV = "COWORKER_REASONING_EFFORT"+++def _effort_level(value: Any, source: str) -> Optional[str]:+ """`reasoning_effort` must be one of EFFORT_LEVELS (case-insensitive); empty = unset."""+ if value is None:+ return None+ text = str(value).strip().lower()+ if not text:+ return None+ if text not in EFFORT_LEVELS:+ raise ValueError(+ f"reasoning_effort must be one of {', '.join(EFFORT_LEVELS)}, got {value!r} ({source})"+ )+ return textdef _positive_int(value: Any, source: str) -> Optional[int]:@@ -186,4 +213,8 @@ def load_config(except ValueError:parsed = rawcfg.max_output_tokens = _positive_int(parsed, MAX_OUTPUT_TOKENS_ENV)+ cfg.reasoning_effort = _effort_level(cfg.reasoning_effort, "config.toml")+ raw_effort = os.environ.get(REASONING_EFFORT_ENV)+ if raw_effort is not None and raw_effort.strip():+ cfg.reasoning_effort = _effort_level(raw_effort, REASONING_EFFORT_ENV)return cfgdiff --git a/coworker/engine.py b/coworker/engine.pyindex 92ea9dc2..6383bcdf 100644--- a/coworker/engine.py+++ b/coworker/engine.py@@ -576,7 +576,13 @@ class TurnEngine:if not self._turn_truncated:self._continuations = 0_sanitize_mangled_calls(turn)- self.messages.append(_assistant_message(turn, model=self.model))+ self.messages.append(+ _assistant_message(+ turn,+ model=self.model,+ effort_setting=self.model_settings.get("reasoning_effort"),+ )+ )payload: dict[str, Any] = {"text": turn.text,"tool_calls": [tc.name for tc in turn.tool_calls],@@ -591,6 +597,9 @@ class TurnEngine:if turn.output_limit:# The output ceiling the provider sent (OPE-177).payload["max_output_tokens"] = turn.output_limit+ effort_record = _effort_record(turn, self.model_settings.get("reasoning_effort"))+ if effort_record:+ payload["reasoning_effort"] = effort_recordyield Event(EventType.ASSISTANT_MESSAGE, payload)if not turn.tool_calls:@@ -2097,6 +2106,7 @@ class TurnEngine:"usage","finish_reason","max_output_tokens",+ "reasoning_effort","replay",)# Auto-compaction (OPE-27): everything before the boundary is represented by the@@ -2200,7 +2210,24 @@ class TurnEngine:return out-def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict[str, Any]:+def _effort_record(turn: AssistantTurn, setting: Optional[str]) -> Optional[dict[str, Any]]:+ """What the run record says about reasoning effort for this reply (OPE-176): the+ provider's own mapping when it reported one; otherwise, when a level was configured,+ an explicit "requested but not reported" so the setting is never silently lost."""+ if turn.effort:+ return dict(turn.effort)+ if setting:+ return {+ "requested": setting,+ "effective": None,+ "note": "provider did not report an effort parameter (no knob on this path)",+ }+ return None+++def _assistant_message(+ turn: AssistantTurn, model: Optional[str] = None, effort_setting: Optional[str] = None+) -> dict[str, Any]:message: dict[str, Any] = {"role": "assistant","content": turn.text or "",@@ -2225,6 +2252,11 @@ def _assistant_message(turn: AssistantTurn, model: Optional[str] = None) -> dict# `length` finish can be read against the limit that produced it. Display# sidecar like `usage`: stripped before every provider call.message["max_output_tokens"] = turn.output_limit+ effort_record = _effort_record(turn, effort_setting)+ if effort_record:+ # The reasoning-effort mapping for this reply (OPE-176). Display sidecar like+ # `usage`: stripped before every provider call.+ message["reasoning_effort"] = effort_recordif 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 7d26de17..6187ccca 100644--- a/coworker/providers/anthropic_provider.py+++ b/coworker/providers/anthropic_provider.py@@ -25,6 +25,7 @@ import jsonimport refrom typing import Any, Optional+from .effort import EffortPlan, anthropic_effort, mentions_effortfrom .base import (AssistantTurn,ModelCapabilities,@@ -380,6 +381,14 @@ def _reasoning_text(thinking_blocks: list[dict[str, Any]]) -> Optional[str]:return text or None+def _effort_record(plan: Optional[EffortPlan], fallback_note: Optional[str]) -> Optional[dict[str, Any]]:+ if plan is None:+ return None+ if fallback_note:+ return plan.without_param(fallback_note).record()+ return plan.record()++def _anthropic_extras(thinking_blocks: list[dict[str, Any]], stop_reason: Any = None) -> dict[str, Any]:@@ -415,6 +424,9 @@ class AnthropicProvider(ProviderClient):self._secrets = secretsself.default_model = default_modelself.thinking_budget = thinking_budget or 0+ # Models whose endpoint rejected `output_config.effort` this run (OPE-176): the+ # parameter is not sent to them again; the record says so.+ self._effort_rejected: set[str] = set()def _ensure_client(self) -> Any:if self._client is None:@@ -437,6 +449,7 @@ class AnthropicProvider(ProviderClient):messages: list[dict[str, Any]],tools: Optional[list[dict[str, Any]]],settings: dict[str, Any],+ effort: Optional[EffortPlan] = None,) -> dict[str, Any]:system, converted = convert_messages(messages)if "stop" in settings and "stop_sequences" not in settings:@@ -453,6 +466,10 @@ class AnthropicProvider(ProviderClient):# 4.6+/Claude 5 family: adaptive only (budget_tokens 400s on 4.7+);# display opt-in or the trace text arrives empty.filtered["thinking"] = {"type": "adaptive", "display": "summarized"}+ if effort is not None and effort.params:+ # OPE-176: a configured level becomes `output_config.effort` (adaptive models)+ # or the thinking budget (budget-mode models); the floor below still applies.+ filtered.update(effort.params)thinking = filtered.get("thinking") or {}if thinking.get("type") == "enabled":# Budget must fit under max_tokens.@@ -493,8 +510,9 @@ class AnthropicProvider(ProviderClient):tools: Optional[list[dict[str, Any]]] = None,**settings: Any,) -> AssistantTurn:+ plan = self._effort_plan(model, settings)kwargs = self._request_kwargs(- model=model, messages=messages, tools=tools, settings=settings+ model=model, messages=messages, tools=tools, settings=settings, effort=plan)client = self._ensure_client()# Stream-and-accumulate, not a plain create: the SDK REFUSES non-streaming@@ -504,16 +522,20 @@ class AnthropicProvider(ProviderClient):# for every Anthropic model (found by the 2026-08-31 eval run; fail-closed,# so verdicts fell back to asking a human). get_final_message() returns the# same Message shape create() would.- if _needs_refusal_fallback(model):- with client.beta.messages.stream(- **kwargs,- betas=[_FALLBACK_BETA],- fallbacks=[{"model": _FALLBACK_MODEL}],- ) as stream:- response = stream.get_final_message()- else:- with client.messages.stream(**kwargs) as stream:- response = stream.get_final_message()+ def _final(kw: dict[str, Any]) -> Any:+ if _needs_refusal_fallback(model):+ with client.beta.messages.stream(+ **kw,+ betas=[_FALLBACK_BETA],+ fallbacks=[{"model": _FALLBACK_MODEL}],+ ) as stream:+ return stream.get_final_message()+ with client.messages.stream(**kw) as stream:+ return stream.get_final_message()++ response, kwargs, fallback_note = self._call_with_effort_fallback(+ model, kwargs, _final+ )text_parts: list[str] = []tool_calls: list[ToolCall] = []@@ -556,11 +578,44 @@ class AnthropicProvider(ProviderClient):extras=_anthropic_extras(thinking_blocks, stop_reason),usage=_usage_from(getattr(response, "usage", None)),output_limit=kwargs.get("max_tokens"),+ effort=_effort_record(plan, fallback_note),)def capabilities(self, model: str) -> ModelCapabilities:return capabilities_for(model)+ # -- reasoning effort (OPE-176) ---------------------------------------------------++ def _effort_plan(self, model: str, settings: dict[str, Any]) -> Optional[EffortPlan]:+ level = settings.get("reasoning_effort")+ if not level:+ return None+ if model in self._effort_rejected:+ return EffortPlan(+ str(level),+ None,+ {},+ "endpoint rejected output_config.effort earlier in this run; not sent",+ )+ return anthropic_effort(model, str(level), budget_mode=_uses_budget_thinking(model))++ def _call_with_effort_fallback(self, model: str, kwargs: dict[str, Any], fn: Any):+ """Run `fn(kwargs)`; if the endpoint rejects the effort parameter (HTTP 400 naming+ it), drop it, remember the model, and run once more. Returns (result, kwargs+ actually used, fallback note or None). Any other error propagates unchanged."""+ try:+ return fn(kwargs), kwargs, None+ except Exception as exc:+ if "output_config" in kwargs and mentions_effort(exc):+ self._effort_rejected.add(model)+ retry = {k: v for k, v in kwargs.items() if k != "output_config"}+ return (+ fn(retry),+ retry,+ "endpoint rejected output_config.effort; resent without it",+ )+ raise+def stream(self,*,@@ -569,19 +624,22 @@ class AnthropicProvider(ProviderClient):tools: Optional[list[dict[str, Any]]] = None,**settings: Any,):+ plan = self._effort_plan(model, settings)kwargs = self._request_kwargs(- model=model, messages=messages, tools=tools, settings=settings+ model=model, messages=messages, tools=tools, settings=settings, effort=plan)kwargs["stream"] = Trueclient = self._ensure_client()- if _needs_refusal_fallback(model):- events = client.beta.messages.create(- **kwargs,- betas=[_FALLBACK_BETA],- fallbacks=[{"model": _FALLBACK_MODEL}],- )- else:- events = client.messages.create(**kwargs)+ def _open(kw: dict[str, Any]) -> Any:+ if _needs_refusal_fallback(model):+ return client.beta.messages.create(+ **kw,+ betas=[_FALLBACK_BETA],+ fallbacks=[{"model": _FALLBACK_MODEL}],+ )+ return client.messages.create(**kw)++ events, kwargs, fallback_note = self._call_with_effort_fallback(model, kwargs, _open)text_parts: list[str] = []tool_accum: dict[int, dict[str, str]] = {}@@ -678,5 +736,6 @@ class AnthropicProvider(ProviderClient):extras=_anthropic_extras(thinking_blocks, stop_reason),usage=usage,output_limit=kwargs.get("max_tokens"),+ effort=_effort_record(plan, fallback_note),))diff --git a/coworker/providers/base.py b/coworker/providers/base.pyindex 694b3d8c..6799b4b6 100644--- a/coworker/providers/base.py+++ b/coworker/providers/base.py@@ -77,6 +77,11 @@ class AssistantTurn:# provider left it to the server. Persisted on the assistant message as the# `max_output_tokens` sidecar so a run record states its ceiling (OPE-177).output_limit: Optional[int] = None+ # The reasoning-effort mapping used for this request (OPE-176):+ # {requested, effective, param?, note?} — see providers/effort.py. None when no+ # 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@propertydef has_tool_calls(self) -> bool:diff --git a/coworker/providers/effort.py b/coworker/providers/effort.pynew file mode 100644index 00000000..d7cf5b10--- /dev/null+++ b/coworker/providers/effort.py@@ -0,0 +1,174 @@+"""Reasoning-effort levels and their per-provider translation (OPE-176).++One setting, `reasoning_effort`, five levels mirroring Anthropic's: low, medium, high,+xhigh, max. Unset means "send nothing" — every provider's request stays byte-identical to+before the setting existed (Anthropic's API default is `high`; Together's default for+Kimi K3 is `max`). Each provider client translates a level into the parameter its wire+accepts, records what it actually sent, and falls back (once, per model, per run) when+the endpoint rejects the parameter.++Level names a model does not accept map to the NEAREST accepted level by rank, ties going+UP (xhigh on Kimi K3 → max; medium on Kimi K3 → high). The mapping is recorded on every+reply as `{requested, effective, param, note}` so a run record states its effort.++Sources (read 2026-09-08): platform.claude.com/docs/en/build-with-claude/effort (supported+models per level; `high` == omitted; hold the level constant within a conversation or+the prompt cache restarts); Moonshot/Together Kimi K3 docs (`reasoning_effort` low/high/max,+default max).+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any, Optional, Sequence++from ..config import EFFORT_LEVELS++_RANK = {level: i for i, level in enumerate(EFFORT_LEVELS)}+++@dataclass(frozen=True)+class EffortPlan:+ requested: str+ # The level/value actually sent; None when nothing was sent (unsupported, rejected).+ effective: Optional[str]+ # Provider request parameters to merge (empty when nothing is sent).+ params: dict[str, Any] = field(default_factory=dict)+ note: str = ""++ def record(self) -> dict[str, Any]:+ """The sidecar persisted on the assistant message / run record."""+ out: dict[str, Any] = {"requested": self.requested, "effective": self.effective}+ if self.params:+ out["param"] = self.params+ if self.note:+ out["note"] = self.note+ return out++ def without_param(self, note: str) -> "EffortPlan":+ """The plan after the endpoint rejected the parameter and it was dropped."""+ return EffortPlan(self.requested, None, {}, note)+++def validate_level(value: Any, source: str = "reasoning_effort") -> Optional[str]:+ """Normalise a configured value to one of EFFORT_LEVELS (case-insensitive) or raise."""+ if value is None:+ return None+ text = str(value).strip().lower()+ if not text:+ return None+ if text not in _RANK:+ raise ValueError(+ f"{source} must be one of {', '.join(EFFORT_LEVELS)}; got {value!r}"+ )+ return text+++def nearest_supported(level: str, supported: Sequence[str]) -> Optional[str]:+ """The accepted level closest in rank to `level`; ties resolve to the higher one."""+ if not supported:+ return None+ if level in supported:+ return level+ target = _RANK[level]+ return min(supported, key=lambda s: (abs(_RANK[s] - target), -_RANK[s]))+++# -- Anthropic -----------------------------------------------------------------------++_ALL = tuple(EFFORT_LEVELS)+_NO_XHIGH = ("low", "medium", "high", "max")+# Longest prefix wins. Per the effort doc's "Supported models" + per-level availability.+_ANTHROPIC_EFFORT: tuple[tuple[str, tuple[str, ...]], ...] = (+ ("claude-fable-5-1", _ALL),+ ("claude-mythos-5-1", _ALL),+ ("claude-fable-5", _ALL),+ ("claude-mythos-5", _ALL),+ ("claude-mythos-preview", _NO_XHIGH),+ ("claude-opus-5", _ALL),+ ("claude-opus-4-8", _ALL),+ ("claude-opus-4-7", _ALL),+ ("claude-opus-4-6", _NO_XHIGH),+ ("claude-opus-4-5", ("low", "medium", "high")),+ ("claude-sonnet-5", _ALL),+ ("claude-sonnet-4-6", _NO_XHIGH),+)+# Budget-thinking models (older Claude): the level becomes a thinking budget. Anthropic+# requires budget_tokens >= 1,024 and < max_tokens; the provider floors max_tokens.+BUDGET_TOKENS_BY_LEVEL = {+ "low": 2_048,+ "medium": 8_192,+ "high": 16_000,+ "xhigh": 24_000,+ "max": 32_000,+}+++def _anthropic_supported(model: str) -> Optional[tuple[str, ...]]:+ best: Optional[tuple[str, ...]] = None+ best_len = -1+ for prefix, levels in _ANTHROPIC_EFFORT:+ if model.startswith(prefix) and len(prefix) > best_len:+ best, best_len = levels, len(prefix)+ return best+++def anthropic_effort(model: str, level: str, *, budget_mode: bool) -> EffortPlan:+ """`output_config.effort` on adaptive-thinking models; `thinking.budget_tokens` on+ budget-mode models. Unknown adaptive models get the level as-is (the 400 fallback+ covers a wrong guess); the mapping is recorded either way."""+ if budget_mode:+ budget = BUDGET_TOKENS_BY_LEVEL[level]+ return EffortPlan(+ level,+ level,+ {"thinking": {"type": "enabled", "budget_tokens": budget}},+ f"budget-thinking model: {level} -> budget_tokens {budget}",+ )+ supported = _anthropic_supported(model)+ if supported is None:+ return EffortPlan(+ level,+ level,+ {"output_config": {"effort": level}},+ "model not in the documented effort table; sent unverified",+ )+ effective = nearest_supported(level, supported)+ assert effective is not None+ note = "" if effective == level else f"{level} not accepted by {model}; sent {effective}"+ return EffortPlan(level, effective, {"output_config": {"effort": effective}}, note)+++# -- OpenAI-compatible endpoints (Together, Moonshot, DeepSeek, …) -------------------++# Bare model id (as the OpenAI-compatible client receives it) → accepted values.+# Only rows with a verified source; everything else gets the OpenAI vocabulary.+_OPENAI_COMPAT: dict[str, tuple[str, ...]] = {+ # Kimi K3: Moonshot and Together document reasoning_effort low / high / max.+ "moonshotai/Kimi-K3": ("low", "high", "max"),+ "kimi-k3": ("low", "high", "max"),+}+_OPENAI_DEFAULT = ("low", "medium", "high")+++def openai_compat_effort(model: str, level: str) -> EffortPlan:+ supported = _OPENAI_COMPAT.get(model) or _OPENAI_COMPAT.get(model.lower()) or _OPENAI_DEFAULT+ effective = nearest_supported(level, supported)+ assert effective is not None+ verified = model in _OPENAI_COMPAT or model.lower() in _OPENAI_COMPAT+ note = ""+ if effective != level:+ note = f"{level} not accepted by {model}; sent {effective}"+ elif not verified:+ note = "model not in the verified table; OpenAI vocabulary assumed"+ return EffortPlan(level, effective, {"reasoning_effort": effective}, note)+++def unsupported(level: str, why: str) -> EffortPlan:+ return EffortPlan(level, None, {}, why)+++def mentions_effort(exc: BaseException) -> bool:+ """Does an endpoint error name the effort parameter (so dropping it is the fix)?"""+ msg = str(exc).lower()+ return "effort" in msg or "output_config" in msgdiff --git a/coworker/providers/openai_provider.py b/coworker/providers/openai_provider.pyindex c98d0352..0ec70c6c 100644--- a/coworker/providers/openai_provider.py+++ b/coworker/providers/openai_provider.py@@ -14,6 +14,7 @@ import jsonimport refrom typing import Any, Optional+from .effort import EffortPlan, mentions_effort, openai_compat_effortfrom .base import (AssistantTurn,ModelCapabilities,@@ -100,6 +101,16 @@ def _param_fix_retry(kwargs: dict[str, Any], exc: Exception) -> dict[str, Any]:msg = str(exc).lower()if _EFFORT_ERROR in msg and kwargs.get("reasoning_effort") != "none":return {**kwargs, "reasoning_effort": "none"}+ if (+ "reasoning_effort" in kwargs+ and kwargs.get("reasoning_effort") != "none"+ and ("reasoning_effort" in msg or "effort" in msg)+ ):+ # OPE-176: the endpoint has no effort knob under that name — drop it and run on+ # the server default; the reply's `effort` record says it was rejected.+ fixed = dict(kwargs)+ fixed.pop("reasoning_effort")+ return fixedif _MAX_TOKENS_ERROR in msg and "max_tokens" in kwargs:fixed = dict(kwargs)fixed["max_completion_tokens"] = fixed.pop("max_tokens")@@ -120,6 +131,23 @@ def _param_fix_retry(kwargs: dict[str, Any], exc: Exception) -> dict[str, Any]:raise exc+def _effort_record(plan: Optional[EffortPlan], kwargs: dict[str, Any]) -> Optional[dict[str, Any]]:+ """The effort record for a reply, read from the kwargs that were finally sent (after+ the param-fix retries may have dropped or pinned the parameter)."""+ if plan is None:+ return None+ if not plan.params:+ return plan.record()+ sent = kwargs.get("reasoning_effort")+ if sent is None:+ return plan.without_param("endpoint rejected reasoning_effort; resent without it").record()+ if sent != plan.effective:+ return EffortPlan(+ plan.requested, str(sent), {"reasoning_effort": sent}, f"endpoint accepted only {sent}"+ ).record()+ return plan.record()++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)."""@@ -193,6 +221,7 @@ class OpenAIProvider(ProviderClient):tools: Optional[list[dict[str, Any]]] = None,**settings: Any,) -> AssistantTurn:+ plan = self._effort_plan(model, settings)kwargs: dict[str, Any] = {"model": model,"messages": _strip_foreign_sidecars(messages),@@ -201,6 +230,8 @@ class OpenAIProvider(ProviderClient):if tools:kwargs["tools"] = toolskwargs.setdefault("max_tokens", DEFAULT_MAX_TOKENS)+ if plan is not None and plan.params:+ kwargs.update(plan.params)_pin_reasoning_effort(kwargs)client = self._ensure_client()@@ -227,11 +258,35 @@ class OpenAIProvider(ProviderClient):reasoning=_delta_reasoning(message),usage=_usage_from(getattr(response, "usage", None)),output_limit=_output_limit(kwargs),+ effort=self._note_effort(model, plan, kwargs),)def capabilities(self, model: str) -> ModelCapabilities:return capabilities_for(model)+ # -- reasoning effort (OPE-176) ---------------------------------------------------++ def _effort_plan(self, model: str, settings: dict[str, Any]) -> Optional[EffortPlan]:+ """Pop the engine-level `reasoning_effort` setting (it must never ride the wire+ unmapped) and translate it for this model; None when unset."""+ level = settings.pop("reasoning_effort", None)+ if not level:+ return None+ rejected = self.__dict__.setdefault("_effort_rejected", set())+ if model in rejected:+ return EffortPlan(+ str(level), None, {}, "endpoint rejected reasoning_effort earlier in this run; not sent"+ )+ return openai_compat_effort(model, str(level))++ def _note_effort(+ self, model: str, plan: Optional[EffortPlan], kwargs: dict[str, Any]+ ) -> Optional[dict[str, Any]]:+ record = _effort_record(plan, kwargs)+ if plan is not None and plan.params and kwargs.get("reasoning_effort") is None:+ self.__dict__.setdefault("_effort_rejected", set()).add(model)+ return record+def stream(self,*,@@ -240,6 +295,7 @@ class OpenAIProvider(ProviderClient):tools: Optional[list[dict[str, Any]]] = None,**settings: Any,):+ plan = self._effort_plan(model, settings)kwargs: dict[str, Any] = {"model": model,"messages": _strip_foreign_sidecars(messages),@@ -252,6 +308,8 @@ class OpenAIProvider(ProviderClient):if tools:kwargs["tools"] = toolskwargs.setdefault("max_tokens", DEFAULT_MAX_TOKENS)+ if plan is not None and plan.params:+ kwargs.update(plan.params)_pin_reasoning_effort(kwargs)client = self._ensure_client()@@ -326,6 +384,7 @@ class OpenAIProvider(ProviderClient):reasoning="".join(reasoning_parts) or None,usage=usage,output_limit=_output_limit(kwargs),+ effort=self._note_effort(model, plan, kwargs),))diff --git a/docs/config.example.toml b/docs/config.example.tomlindex b3b6b0c9..b3c592bb 100644--- a/docs/config.example.toml+++ b/docs/config.example.toml@@ -10,6 +10,11 @@ max_iterations = 12 # max model<->tool iterations per turn before stopp# max_output_tokens = 64000 # per-reply output cap sent as max_tokens (thinking + text +# tool arguments). Unset = provider default (32000; Bedrock# 4096). Env override: COWORKER_MAX_OUTPUT_TOKENS.+# reasoning_effort = "high" # low | medium | high | xhigh | max — how hard the model thinks+ # per reply, translated per provider (Anthropic output_config+ # .effort; Together/Moonshot reasoning_effort). Unset = provider+ # default (Anthropic high, Kimi K3 max). Env override:+ # COWORKER_REASONING_EFFORT.# Commands auto-allowed without an approval prompt (prefix match).allowed_commands = [diff --git a/tests/test_reasoning_effort.py b/tests/test_reasoning_effort.pynew file mode 100644index 00000000..fecc6506--- /dev/null+++ b/tests/test_reasoning_effort.py@@ -0,0 +1,387 @@+"""OPE-176: the `reasoning_effort` setting, its per-provider translation and its record.++Unset keeps every request byte-identical to before (Anthropic = API default high, Kimi K3+on Together = its default max). Set, the level travels via `model_settings`, each provider+maps it to its own parameter, drops it once per model if the endpoint rejects it, and the+engine persists `{requested, effective, param, note}` on every assistant message.+"""++from __future__ import annotations++import asyncio+from contextlib import contextmanager+from types import SimpleNamespace++import aisuite as ai+import pytest+from coworker.agent import build_code_engine+from coworker.config import EFFORT_LEVELS, load_config+from coworker.engine import TurnEngine, _assistant_message+from coworker.events import EventType+from coworker.permissions import PermissionEngine+from coworker.providers import (+ AnthropicProvider,+ AssistantTurn,+ ModelCapabilities,+ OpenAIProvider,+ ProviderClient,+)+from coworker.providers.anthropic_provider import _uses_budget_thinking+from coworker.providers.effort import (+ BUDGET_TOKENS_BY_LEVEL,+ anthropic_effort,+ nearest_supported,+ openai_compat_effort,+ validate_level,+)+from coworker.providers.matrix import MATRIX+from coworker.tools import ToolRegistry++# -- levels and config --------------------------------------------------------------+++def test_levels_are_anthropics_five_in_order():+ assert EFFORT_LEVELS == ("low", "medium", "high", "xhigh", "max")++[email protected]("raw,expected", [("high", "high"), (" XHigh ", "xhigh"), ("", None), (None, None)])+def test_validate_level_normalises(raw, expected):+ assert validate_level(raw) == expected++[email protected]("bad", ["highest", "adaptive", "1", "none"])+def test_validate_level_rejects_unknown(bad):+ with pytest.raises(ValueError, match="reasoning_effort"):+ validate_level(bad)+++def test_config_default_unset_and_layering(tmp_path, monkeypatch):+ g = tmp_path / "global.toml"+ assert load_config(global_path=tmp_path / "nope.toml").reasoning_effort is None+ g.write_text('reasoning_effort = "medium"\n')+ assert load_config(global_path=g).reasoning_effort == "medium"+ ws = tmp_path / "ws"+ (ws / ".coworker").mkdir(parents=True)+ (ws / ".coworker" / "config.toml").write_text('reasoning_effort = "XHIGH"\n')+ assert load_config(ws, global_path=g).reasoning_effort == "xhigh"+ monkeypatch.setenv("COWORKER_REASONING_EFFORT", "low")+ assert load_config(ws, global_path=g).reasoning_effort == "low"+ monkeypatch.setenv("COWORKER_REASONING_EFFORT", "turbo")+ with pytest.raises(ValueError, match="COWORKER_REASONING_EFFORT"):+ load_config(ws, global_path=g)+++# -- build_engine ---------------------------------------------------------------------+++class _Stub(ProviderClient):+ def complete(self, **k): # pragma: no cover+ raise NotImplementedError++ def capabilities(self, m):+ return ModelCapabilities()+++def _engine_with_config(tmp_path, toml, **kwargs):+ (tmp_path / ".coworker").mkdir(exist_ok=True)+ (tmp_path / ".coworker" / "config.toml").write_text(toml)+ return build_code_engine(workspace=tmp_path, provider=_Stub(), **kwargs)+++def test_build_engine_threads_the_level_into_model_settings(tmp_path):+ engine = _engine_with_config(tmp_path, 'reasoning_effort = "xhigh"\nmax_output_tokens = 64000\n')+ try:+ assert engine.model_settings == {"max_tokens": 64000, "reasoning_effort": "xhigh"}+ finally:+ engine.executor.close()+++def test_build_engine_explicit_setting_wins_and_unset_is_empty(tmp_path):+ engine = _engine_with_config(+ tmp_path, 'reasoning_effort = "xhigh"\n', model_settings={"reasoning_effort": "low"}+ )+ try:+ assert engine.model_settings["reasoning_effort"] == "low"+ finally:+ engine.executor.close()+ (tmp_path / "b").mkdir()+ engine = _engine_with_config(tmp_path / "b", "max_iterations = 3\n")+ try:+ assert engine.model_settings == {}+ finally:+ engine.executor.close()+++# -- mapping tables -------------------------------------------------------------------+++def test_nearest_supported_ties_go_up():+ assert nearest_supported("xhigh", ("low", "high", "max")) == "max"+ assert nearest_supported("medium", ("low", "high", "max")) == "high"+ assert nearest_supported("xhigh", ("low", "medium", "high")) == "high"+ assert nearest_supported("max", ("low", "medium", "high")) == "high"+ assert nearest_supported("high", ("low", "high", "max")) == "high"+ assert nearest_supported("low", ()) is None+++ "model,level,effective",+ [+ ("claude-fable-5-1", "xhigh", "xhigh"),+ ("claude-fable-5-1", "max", "max"),+ ("claude-sonnet-5", "low", "low"),+ ("claude-opus-5", "medium", "medium"),+ ("claude-sonnet-4-6", "xhigh", "max"), # no xhigh on 4.6 → nearest, tie up+ ("claude-opus-4-5-20251101", "max", "high"), # low/medium/high only+ ("claude-opus-4-6", "xhigh", "max"),+ ],+)+def test_anthropic_adaptive_mapping(model, level, effective):+ plan = anthropic_effort(model, level, budget_mode=False)+ assert plan.effective == effective+ assert plan.params == {"output_config": {"effort": effective}}+ assert (plan.note == "") == (effective == level)+++def test_anthropic_budget_mode_mapping():+ for level in EFFORT_LEVELS:+ plan = anthropic_effort("claude-haiku-4-5", level, budget_mode=True)+ assert plan.params == {"thinking": {"type": "enabled", "budget_tokens": BUDGET_TOKENS_BY_LEVEL[level]}}+ assert plan.effective == level+ assert BUDGET_TOKENS_BY_LEVEL["low"] >= 1024 # Anthropic minimum+++def test_anthropic_unknown_model_sends_level_unverified():+ plan = anthropic_effort("claude-next-9", "xhigh", budget_mode=False)+ assert plan.params == {"output_config": {"effort": "xhigh"}} and "unverified" in plan.note+++ "model,level,effective,noted",+ [+ ("moonshotai/Kimi-K3", "high", "high", False),+ ("moonshotai/Kimi-K3", "max", "max", False),+ ("moonshotai/Kimi-K3", "xhigh", "max", True),+ ("moonshotai/Kimi-K3", "medium", "high", True),+ ("deepseek-ai/DeepSeek-V4-Pro", "max", "high", True), # unverified → OpenAI vocabulary+ ("gpt-5.6-sol", "medium", "medium", True), # unverified table → note, value as-is+ ],+)+def test_openai_compat_mapping(model, level, effective, noted):+ plan = openai_compat_effort(model, level)+ assert plan.effective == effective+ assert plan.params == {"reasoning_effort": effective}+ assert bool(plan.note) == noted+++def test_every_curated_model_resolves_every_level():+ """No level on any curated row may raise; providers without a knob are simply skipped."""+ for mid in MATRIX:+ provider, _, bare = mid.partition(":") if ":" in mid else ("openai", "", mid)+ for level in EFFORT_LEVELS:+ if provider == "anthropic":+ plan = anthropic_effort(bare, level, budget_mode=_uses_budget_thinking(bare))+ elif provider in ("gemini", "bedrock", "vertex", "ark", "ark-agent-plan-cn", "openai-codex", "openai"):+ continue # no chat-completions effort knob on these paths (recorded as such)+ else:+ plan = openai_compat_effort(bare, level)+ assert plan.requested == level and plan.effective in EFFORT_LEVELS, (mid, level)+++# -- Anthropic provider ---------------------------------------------------------------+++class _FakeAnthropic:+ def __init__(self, response=None, events=None, *, reject_effort=False):+ self.kwargs_seen: list[dict] = []+ self._reject = reject_effort++ def _check(kwargs):+ self.kwargs_seen.append(kwargs)+ if self._reject and "output_config" in kwargs:+ raise RuntimeError("400: output_config.effort: Extra inputs are not permitted")++ def create(**kwargs):+ _check(kwargs)+ if kwargs.get("stream"):+ return iter(events or [])+ return response++ @contextmanager+ def stream(**kwargs):+ _check(kwargs)+ yield SimpleNamespace(get_final_message=lambda: response)++ self.messages = SimpleNamespace(create=create, stream=stream)+ self.beta = SimpleNamespace(messages=SimpleNamespace(create=create, stream=stream))++ @property+ def kwargs(self):+ return self.kwargs_seen[-1]+++def _anthropic_response():+ return SimpleNamespace(content=[SimpleNamespace(type="text", text="hi")], stop_reason="end_turn")+++def _anthropic_events():+ return [+ 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="hi")),+ SimpleNamespace(type="message_delta", delta=SimpleNamespace(stop_reason="end_turn")),+ ]+++def test_anthropic_unset_sends_no_effort_field():+ fake = _FakeAnthropic(response=_anthropic_response())+ turn = AnthropicProvider(client=fake).complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}])+ assert "output_config" not in fake.kwargs and "reasoning_effort" not in fake.kwargs+ assert turn.effort is None+++def test_anthropic_complete_and_stream_send_output_config():+ fake = _FakeAnthropic(response=_anthropic_response(), events=_anthropic_events())+ provider = AnthropicProvider(client=fake)+ turn = provider.complete(model="claude-fable-5-1", messages=[{"role": "user", "content": "x"}], reasoning_effort="xhigh")+ assert fake.kwargs["output_config"] == {"effort": "xhigh"}+ assert "reasoning_effort" not in fake.kwargs+ assert turn.effort == {"requested": "xhigh", "effective": "xhigh", "param": {"output_config": {"effort": "xhigh"}}}+ chunks = list(provider.stream(model="claude-fable-5-1", messages=[{"role": "user", "content": "x"}], reasoning_effort="low"))+ assert fake.kwargs["output_config"] == {"effort": "low"}+ assert chunks[-1].turn.effort["effective"] == "low"+++def test_anthropic_budget_model_maps_to_budget_and_floors_max_tokens():+ fake = _FakeAnthropic(response=_anthropic_response())+ turn = AnthropicProvider(client=fake).complete(model="claude-haiku-4-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="max")+ assert fake.kwargs["thinking"] == {"type": "enabled", "budget_tokens": 32_000}+ assert fake.kwargs["max_tokens"] > 32_000+ assert "output_config" not in fake.kwargs+ assert turn.effort["effective"] == "max" and "budget_tokens" in turn.effort["note"]+++def test_anthropic_rejection_falls_back_once_and_is_remembered():+ fake = _FakeAnthropic(response=_anthropic_response(), reject_effort=True)+ provider = AnthropicProvider(client=fake)+ turn = provider.complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="low")+ assert len(fake.kwargs_seen) == 2 # rejected, then resent without the field+ assert "output_config" not in fake.kwargs+ assert turn.effort["requested"] == "low" and turn.effort["effective"] is None+ assert "rejected" in turn.effort["note"]+ # Next call on the same model does not try again.+ turn2 = provider.complete(model="claude-sonnet-5", messages=[{"role": "user", "content": "y"}], reasoning_effort="low")+ assert len(fake.kwargs_seen) == 3 and "output_config" not in fake.kwargs+ assert turn2.effort["effective"] is None+++def test_anthropic_unrelated_error_still_raises():+ class _Boom(_FakeAnthropic):+ pass++ fake = _Boom(response=_anthropic_response())++ def create(**kwargs):+ raise RuntimeError("overloaded_error")++ fake.messages = SimpleNamespace(create=create, stream=fake.messages.stream)+ with pytest.raises(RuntimeError, match="overloaded"):+ list(AnthropicProvider(client=fake).stream(model="claude-sonnet-5", messages=[{"role": "user", "content": "x"}], reasoning_effort="low"))+++# -- OpenAI-compatible provider -------------------------------------------------------+++class _FakeOpenAI:+ def __init__(self, *, response=None, stream_chunks=None, reject_effort=False):+ self.calls: list[dict] = []+ self._reject = reject_effort++ def create(**kwargs):+ self.calls.append(kwargs)+ if self._reject and "reasoning_effort" in kwargs:+ raise RuntimeError("Unrecognized request argument supplied: reasoning_effort")+ return stream_chunks if kwargs.get("stream") else response++ self.chat = SimpleNamespace(completions=SimpleNamespace(create=create))+++def _openai_response():+ return SimpleNamespace(choices=[SimpleNamespace(message=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")], usage=None)+++def _openai_chunks():+ return [SimpleNamespace(choices=[SimpleNamespace(delta=SimpleNamespace(content="hi", tool_calls=None), finish_reason="stop")], usage=None)]+++def test_openai_compat_unset_sends_nothing():+ fake = _FakeOpenAI(response=_openai_response())+ turn = OpenAIProvider(client=fake).complete(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}])+ assert "reasoning_effort" not in fake.calls[-1] and turn.effort is None+++def test_openai_compat_kimi_sends_mapped_value_on_both_paths():+ fake = _FakeOpenAI(response=_openai_response(), stream_chunks=_openai_chunks())+ provider = OpenAIProvider(client=fake)+ turn = provider.complete(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}], reasoning_effort="high")+ assert fake.calls[-1]["reasoning_effort"] == "high"+ assert turn.effort == {"requested": "high", "effective": "high", "param": {"reasoning_effort": "high"}}+ chunks = list(provider.stream(model="moonshotai/Kimi-K3", messages=[{"role": "user", "content": "x"}], reasoning_effort="xhigh"))+ assert fake.calls[-1]["reasoning_effort"] == "max"+ assert chunks[-1].turn.effort["effective"] == "max" and "sent max" in chunks[-1].turn.effort["note"]+++def test_openai_compat_rejection_drops_the_parameter_and_records_it():+ fake = _FakeOpenAI(response=_openai_response(), reject_effort=True)+ provider = OpenAIProvider(client=fake)+ turn = provider.complete(model="some/other-model", messages=[{"role": "user", "content": "x"}], reasoning_effort="high")+ assert len(fake.calls) == 2 and "reasoning_effort" not in fake.calls[-1]+ assert turn.effort["effective"] is None and "rejected" in turn.effort["note"]+ provider.complete(model="some/other-model", messages=[{"role": "user", "content": "y"}], reasoning_effort="high")+ assert len(fake.calls) == 3 and "reasoning_effort" not in fake.calls[-1]+++# -- engine record --------------------------------------------------------------------+++class _EffortProvider(ProviderClient):+ def __init__(self, effort):+ self._effort = effort++ def complete(self, *, model, messages, tools=None, **settings):+ return AssistantTurn(text="done", finish_reason="stop", effort=self._effort)++ def capabilities(self, model):+ return ModelCapabilities()+++def _run(tmp_path, provider, **engine_kwargs):+ registry = ToolRegistry()+ registry.register_all(ai.toolkits.files(root=str(tmp_path), allow_write=True))+ engine = TurnEngine(provider=provider, registry=registry, permissions=PermissionEngine(workspace_root=tmp_path), model="m", **engine_kwargs)++ async def _collect():+ return [ev async for ev in engine.run("hello")]++ return engine, asyncio.run(_collect())+++def test_engine_persists_the_provider_record_and_strips_it_outbound(tmp_path):+ rec = {"requested": "xhigh", "effective": "xhigh", "param": {"output_config": {"effort": "xhigh"}}}+ engine, events = _run(tmp_path, _EffortProvider(rec), model_settings={"reasoning_effort": "xhigh"})+ assistant = next(ev for ev in events if ev.type == EventType.ASSISTANT_MESSAGE)+ assert assistant.data["reasoning_effort"] == rec+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")+ assert persisted["reasoning_effort"] == rec+ assert all("reasoning_effort" not in m for m in engine._outbound_messages())+++def test_engine_records_a_requested_level_even_when_the_provider_reports_nothing(tmp_path):+ engine, _ = _run(tmp_path, _EffortProvider(None), model_settings={"reasoning_effort": "low"})+ persisted = next(m for m in engine.messages if m.get("role") == "assistant")+ assert persisted["reasoning_effort"]["requested"] == "low"+ assert persisted["reasoning_effort"]["effective"] is None+ assert "not report" in persisted["reasoning_effort"]["note"]+++def test_no_record_when_unset():+ assert "reasoning_effort" not in _assistant_message(AssistantTurn(text="x"))