@yahyahammad/venastine 0.2.0 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
package/core/client.py CHANGED
@@ -1,1559 +1,2715 @@
1
- from dataclasses import dataclass, field
2
- from typing import Optional
3
- from uuid import UUID, uuid4
4
- import json
5
- import logging
6
- import os
7
-
8
- import credentials
9
- from credentials import load_provider_data, no_providers_message, \
10
- unknown_provider_message
11
- import config
12
-
13
- # ROADMAP_v2 §33 W7 (#135). The three provider SDKs are NOT imported here.
14
- #
15
- # core.loop imports this module and main.py imports core.loop, so a module
16
- # -scope `from openai import OpenAI` is paid by every invocation of either
17
- # shell -- `--help`, `--summary`, a mistyped flag, the thread picker --
18
- # before argparse runs. Measured on Windows: 5.6s to print --help, of
19
- # which 3.5s was the three SDKs, and no run uses more than one of them.
20
- #
21
- # Each import therefore sits at the point of use, INSIDE the branch that
22
- # needs it rather than at the top of the enclosing function: a
23
- # GOOGLE-only name imported at the top of `_messages_for_provider` would
24
- # be paid on every Anthropic turn, which is most of them, and would leave
25
- # the defect in place while looking fixed.
26
- #
27
- # Deferred imports are otherwise not this file's idiom. The trade is
28
- # stated here rather than left to be re-derived: `import` is cached after
29
- # the first call, so the cost is a dict lookup per call on the hot path
30
- # and seconds saved on every launch that never makes one.
31
-
32
- logger = logging.getLogger(__name__)
33
-
34
- # Caches initialized clients so repeated calls for the same provider don't
35
- # rebuild the client (and re-read the credentials file) every time.
36
- _client_cache: dict[str, object] = {}
37
-
38
-
39
- def api_initialization(provider_name: str):
40
- if provider_name in _client_cache:
41
- return _client_cache[provider_name]
42
-
43
- provider_data = load_provider_data()
44
-
45
- # #24. The file's absence and the provider's absence are different
46
- # problems and now say so: the first names the path that was checked
47
- # and its remedy, the second names what IS configured, like /model's
48
- # refusal. Still ValueError either way -- callers (and tests) catch
49
- # the type, not the text. The constant is read THROUGH the module,
50
- # not imported: a from-import would freeze the value at this module's
51
- # import time and a test's monkeypatch of credentials.LLM_PROVIDERS_FILE
52
- # would not be seen here.
53
- if not provider_data and not os.path.exists(
54
- credentials.LLM_PROVIDERS_FILE):
55
- raise ValueError(no_providers_message())
56
- if provider_name not in provider_data:
57
- raise ValueError(unknown_provider_message(provider_name, provider_data))
58
-
59
- entry = provider_data[provider_name]
60
-
61
- if entry.get("is_v1_compatible", False):
62
- from openai import OpenAI
63
- client = OpenAI(base_url=entry["API_URL"], api_key=entry["API_KEY"])
64
- elif provider_name == "GOOGLE":
65
- from google import genai
66
- client = genai.Client(api_key=entry["API_KEY"])
67
- elif provider_name == "ANTHROPIC":
68
- from anthropic import Anthropic
69
- client = Anthropic(api_key=entry["API_KEY"])
70
- # Add further proprietary API formats here
71
- else:
72
- raise ValueError(f"Provider {provider_name} is not currently supported")
73
-
74
- _client_cache[provider_name] = client
75
- return client
76
-
77
-
78
- # ============================================================================
79
- # ---- Normalized response shape ---------------------------------------------
80
- # ============================================================================
81
-
82
- @dataclass
83
- class ToolCallRequest:
84
- id: str
85
- name: str
86
- input: dict
87
- # §33 W2 (#37). Set when the provider's `arguments` string could not
88
- # be read as a JSON object -- most often because the response was cut
89
- # off mid-arguments by the token limit. TRANSPORT ONLY: it describes
90
- # one wire read, not the thread, so `add_assistant_message` persists
91
- # {id, name, input} exactly as before and this never reaches storage.
92
- #
93
- # The call is still constructed rather than dropped. The model made a
94
- # call and is owed an answer about it; a silently missing tool_result
95
- # is M4's pairing defect, and `input={}` with no error would run the
96
- # tool with arguments nobody sent.
97
- parse_error: Optional[str] = None
98
-
99
-
100
- @dataclass
101
- class ModelResponse:
102
- text: str
103
- tool_calls: list[ToolCallRequest] = field(default_factory=list)
104
- usage: dict = field(default_factory=lambda: {"input_tokens": 0, "output_tokens": 0})
105
- stop_reason: str = "complete" # set by RunAgentLoop._run(), not here -- see core/loop.py
106
- thread_id: Optional[UUID] = None # set by the entry points (stream_deep_research_mode,
107
- # continue_conversation) so callers can persist/retry
108
- # against the same thread. call_model() itself NEVER
109
- # sets this -- it has no thread concept.
110
- # §25: calls that proceeded on a PRE-FLIGHT grant rather than a live
111
- # approval. Set by _run() (like stop_reason), never by call_model().
112
- #
113
- # Authorization moved up-front, so accountability moves after: this is
114
- # the record of what a single launch-time yes actually authorised,
115
- # written into the run artifacts for a pipeline nobody was watching.
116
- # Empty for every run that granted nothing, which is every run today.
117
- granted_calls: list = field(default_factory=list)
118
- # ROADMAP_v2 §21: compaction notices raised during this run, each a
119
- # {"kind", "text"} dict. Set by _run() like stop_reason and
120
- # granted_calls, never by call_model().
121
- #
122
- # Carried here as well as yielded as a LoopEvent because
123
- # run_to_completion() discards non-final events: the TUI watches the
124
- # generator, but the CLI and the pipeline drain it, so a notice with
125
- # only the event route would be invisible in two shells out of three.
126
- notices: list = field(default_factory=list)
127
- # #4 (batch 27): the two per-turn figures the loop computes, set by
128
- # _run() like stop_reason -- never by call_model(), which has no turn
129
- # concept. UNPRICED APPROXIMATIONS, deliberately: raw provider counts,
130
- # no cache-read/write pricing and no currency anywhere. Precise spend
131
- # lives in the provider's dashboard; these exist for RELATIVE reasoning
132
- # ("is this turn ballooning the context?"), not billing truth.
133
- #
134
- # turn_billed_tokens: cumulative input+output over this user-turn so
135
- # far -- the spend meter's running total (the prompt is re-sent every
136
- # step, so this grows quadratically in a tool-using turn, which is
137
- # correct: that is what the provider bills).
138
- # turn_new_tokens: what THIS TURN added to the thread -- output plus
139
- # positive input deltas, the first call's inherited prompt excluded
140
- # and mid-turn compaction shrinks clamped away. This is the figure
141
- # anything reasoning about SIZE reads; the spend meter must never be
142
- # read that way again (TECHNICAL_DEBT item 9, closed batch 27).
143
- # turn_output_tokens: what the MODEL WROTE this turn -- output tokens
144
- # and nothing else, summed across every step. Batch 61, and it is a
145
- # THIRD instrument rather than a convenience: the two above are a
146
- # SPEND meter and a SIZE meter, and a generation RATE can be derived
147
- # from neither. turn_billed_tokens counts the prompt again on every
148
- # step; turn_new_tokens adds the positive input deltas, so a
149
- # tool-using turn's tool results land in it and it overstates what was
150
- # generated. Dividing either by a duration produces a number that
151
- # looks like tok/s and is not, which is exactly the misreading
152
- # TECHNICAL_DEBT item 9 was closed for.
153
- turn_billed_tokens: Optional[int] = None
154
- turn_new_tokens: Optional[int] = None
155
- turn_output_tokens: Optional[int] = None
156
- # Batch 44 (§44). The turn's reasoning, as the PROVIDER'S OWN BLOCKS
157
- # rather than as the text §38 streams for display:
158
- #
159
- # {"provider": ..., "model": ..., "blocks": [ ...native... ]}
160
- #
161
- # §38's O1 made thinking display-only -- never persisted, never back
162
- # on the wire -- and sidestepped "does a provider need its own
163
- # thinking returned next turn?" by never returning it. That answer
164
- # stopped being free once it was clear the model had never seen its
165
- # own reasoning at ALL: not across a restart, and not between two
166
- # turns of one live session, so a turn re-derives what it already
167
- # worked out. O1 is amended here.
168
- #
169
- # BLOCKS, NOT THE STREAMED TEXT, and that is the whole reason this is
170
- # a field rather than an accumulation in core/loop.py. An Anthropic
171
- # thinking block carries a `signature`; the model reuses its own state
172
- # through the block, not through the prose, so a re-serialised copy of
173
- # the deltas would be unsigned and rejected. The blocks are read off
174
- # get_final_message(), which already has them in hand.
175
- #
176
- # `provider` and `model` ride along because the replay rule is
177
- # per-model: blocks go back UNCHANGED to the model that produced them
178
- # and are dropped for anything else.
179
- thinking: Optional[dict] = None
180
-
181
-
182
- def _tool_arguments(raw_args: str, tool_name: str,
183
- finish_reason: Optional[str] = None) -> tuple:
184
- """(input, parse_error) for one provider `arguments` string.
185
-
186
- The ONLY place a wire string is parsed as JSON. Google and Anthropic
187
- hand back dicts, so this is the OpenAI-compatible branch's alone --
188
- which is the branch a local model server takes, and truncated or
189
- malformed tool arguments are likeliest there.
190
-
191
- §33 W1 (#37): a failure is RETURNED, not raised. `dispatch()` turning
192
- handler exceptions into {"error": ...} is the whole reason a raising
193
- TOOL cannot kill a run; nothing played that role for a raising
194
- TRANSLATION one layer up, so a response cut mid-arguments took a
195
- JSONDecodeError out of this generator, out of _run(), and into the
196
- pipeline's `except Exception` -- recording status='failed' on a
197
- finished ten-pass run.
198
-
199
- §33 W4: `finish_reason` is what separates "the provider emitted bad
200
- JSON" from "the answer was cut off", which is the likeliest cause by
201
- far and the only one the model can act on.
202
- """
203
- # W9: no arguments is not an error. `get_time` declares properties=[]
204
- # and `pin` has no required parameters, so this is a live path -- and
205
- # json.loads("") raises. Dropping this fallback was green on the whole
206
- # suite when audit unit 3 ran mutation P10.
207
- if not raw_args:
208
- return {}, None
209
-
210
- try:
211
- parsed = json.loads(raw_args)
212
- except json.JSONDecodeError as exc:
213
- if finish_reason == "length":
214
- return {}, (
215
- f"The arguments for {tool_name} were cut off by the response "
216
- f"token limit, so the call could not be made. Reissue it with "
217
- f"shorter arguments."
218
- )
219
- return {}, (
220
- f"The arguments for {tool_name} were not valid JSON ({exc.msg}), "
221
- f"so the call could not be made. Reissue it with valid JSON "
222
- f"arguments."
223
- )
224
-
225
- # Valid JSON that is not an object -- "null", "[1,2]", "3". Rarer than
226
- # a truncation and caught in the same place because the consequence is
227
- # the same: dispatch() would be handed something that is not params.
228
- if not isinstance(parsed, dict):
229
- return {}, (
230
- f"The arguments for {tool_name} parsed as "
231
- f"{type(parsed).__name__}, not a JSON object, so the call could "
232
- f"not be made. Reissue it with a JSON object."
233
- )
234
-
235
- return parsed, None
236
-
237
-
238
- @dataclass
239
- class StreamToken:
240
- """One token-level event yielded by call_model_stream(). Exactly one
241
- field is populated per yield: text_delta for incremental text,
242
- thinking_delta for incremental REASONING text, or final_response for
243
- the terminal ModelResponse (with accumulated tool calls and usage).
244
-
245
- §38 O1: thinking is DISPLAY-ONLY. It never joins the accumulated
246
- `text`, is never persisted, and is never sent back on the wire -- so
247
- the ModelResponse each branch produces is byte-identical to what it
248
- produced before thinking was captured, and D20's persisted turn and
249
- M4's fold boundary keep exactly the bytes they have today.
250
-
251
- Which providers actually populate it (§38 O2): Anthropic, and every
252
- OpenAI-compatible provider that streams `reasoning_content` or
253
- `reasoning` (DeepSeek, Qwen, Z.AI, OpenRouter). It stays empty on
254
- OPENAI -- its Chat Completions endpoint returns no reasoning text at
255
- all -- and on GOOGLE, whose request deliberately does not ask for
256
- thought summaries. Absence is not a bug there; see O2.
257
- """
258
- text_delta: Optional[str] = None
259
- thinking_delta: Optional[str] = None
260
- final_response: Optional[ModelResponse] = None
261
-
262
-
263
- # ============================================================================
264
- # ---- Tool schema translation ------------------------------------------------
265
- # ============================================================================
266
-
267
- def _tools_for_provider(provider_name: str, tool_schemas: list[dict]):
268
- """
269
- tool_schemas arrive in Anthropic's native shape (name/description/
270
- input_schema), since that's what every tool's TOOL_SCHEMA already
271
- produces. Translate into whatever shape the target provider expects.
272
- """
273
- if not tool_schemas:
274
- return None
275
-
276
- if provider_name == "ANTHROPIC":
277
- return tool_schemas
278
-
279
- if provider_name == "GOOGLE":
280
- from google.genai import types as genai_types
281
- return [genai_types.Tool(
282
- function_declarations=[
283
- genai_types.FunctionDeclaration(
284
- name=s["name"],
285
- description=s["description"],
286
- parameters=s["input_schema"],
287
- )
288
- for s in tool_schemas
289
- ]
290
- )]
291
-
292
- # OpenAI-compatible providers
293
- return [
294
- {
295
- "type": "function",
296
- "function": {
297
- "name": s["name"],
298
- "description": s["description"],
299
- "parameters": s["input_schema"],
300
- },
301
- }
302
- for s in tool_schemas
303
- ]
304
-
305
-
306
- # ============================================================================
307
- # ---- Message history translation -------------------------------------------
308
- # ============================================================================
309
- # core/memory.py stores history in a provider-neutral shape (see that
310
- # file's docstring). This is the counterpart to _tools_for_provider above,
311
- # applied to conversation history instead of tool schemas -- the ONLY
312
- # place either provider's specific message wire format should exist.
313
-
314
- def _is_tool_result_message(msg: dict) -> bool:
315
- return isinstance(msg.get("content"), list) and all(
316
- isinstance(b, dict) and b.get("type") == "tool_result" for b in msg["content"]
317
- )
318
-
319
-
320
- def _is_empty_assistant_turn(msg: dict) -> bool:
321
- """An assistant turn carrying neither text nor tool calls (#13, #36).
322
-
323
- Produced when the model returns nothing at all -- a safety filter, a
324
- truncation, an empty pass response. `core/loop.py` persists it because
325
- D20 requires the assistant turn to be written before any stop-condition
326
- branching, so it reaches translation on every resume of that thread.
327
-
328
- It is meaningless on every provider, and each branch used to mangle it
329
- differently from the same neutral input:
330
-
331
- OPENAI: {"role": "assistant", "content": null} <- #13
332
- ANTHROPIC: {"role": "assistant", "content": []} <- #36
333
- GOOGLE: skipped entirely <- guarded
334
-
335
- Only Google was guarded, and only because Google was the provider being
336
- debugged when it surfaced. Dropping it above the branch split is
337
- AGENTS.md's *fix at the producer, not the consumer*: all three branches
338
- become correct at once, and so does the next one.
339
-
340
- Requiring BOTH halves to be empty is load-bearing. An empty text WITH
341
- tool calls is legitimate on the OpenAI schema -- a tool-call-only turn
342
- -- and `test_messages_openai_assistant_with_null_text` covers it, so a
343
- guard keyed on text alone breaks a valid case.
344
- """
345
- return (msg.get("role") == "assistant"
346
- and not msg.get("text")
347
- and not msg.get("tool_calls"))
348
-
349
-
350
- def _echoed_blocks(provider_name: str, model: Optional[str],
351
- msg: dict) -> list:
352
- """This turn's stored thinking blocks, if they may go back (§44).
353
-
354
- THE GATE IS THE PAIR, and it is the whole safety argument. A stored
355
- record names the provider and model that produced it; blocks go back
356
- UNCHANGED to that model and to nothing else. An Anthropic block carries
357
- a signature the model verifies against its own state, so handing it to
358
- a different model is at best ignored and at worst a 400 -- and after a
359
- /model switch the thread is full of blocks the new model never wrote.
360
- Dropping them is always safe: the harness then does exactly what it did
361
- before this batch.
362
-
363
- Empty for every message written before §44, which is what keeps the
364
- translation byte-identical for every existing thread.
365
- """
366
- record = msg.get("thinking")
367
- if not isinstance(record, dict) or not model:
368
- return []
369
- if record.get("provider") != provider_name or record.get("model") != model:
370
- return []
371
- return [b for b in record.get("blocks") or [] if isinstance(b, dict)]
372
-
373
-
374
- def _messages_for_provider(provider_name: str, neutral_messages: list[dict],
375
- model: Optional[str] = None,
376
- echo_reasoning: bool = False) -> list:
377
- """The wire shape for one provider.
378
-
379
- `model` and `echo_reasoning` are §44's: they decide whether a stored
380
- thinking record may travel. Both DEFAULT to the pre-§44 behaviour --
381
- no model means no echo, and the OpenAI-compatible side is opt-in per
382
- provider -- so a caller that does not pass them gets exactly the
383
- translation this function produced before.
384
- """
385
- # One rule, above the split (#13, #36). Note this can leave two
386
- # consecutive user turns -- which is the shape Google's branch has
387
- # always produced here, and which
388
- # `test_messages_google_empty_assistant_turn_skipped` has always
389
- # asserted.
390
- neutral_messages = [m for m in neutral_messages
391
- if not _is_empty_assistant_turn(m)]
392
-
393
- if provider_name == "GOOGLE":
394
- from google.genai import types as genai_types
395
- # Build a {tool_call_id: function_name} lookup from assistant
396
- # messages so we can populate FunctionResponse.name (required by
397
- # Google but absent from the neutral tool-result shape).
398
- call_id_to_name: dict[str, str] = {}
399
- for msg in neutral_messages:
400
- if msg["role"] == "assistant":
401
- for tc in msg.get("tool_calls", []):
402
- call_id_to_name[tc["id"]] = tc["name"]
403
-
404
- translated = []
405
- for msg in neutral_messages:
406
- role = msg["role"]
407
-
408
- if role == "user":
409
- translated.append(genai_types.Content(
410
- role="user",
411
- parts=[genai_types.Part(text=msg["content"])],
412
- ))
413
-
414
- elif role == "assistant":
415
- parts = []
416
- if msg.get("text"):
417
- parts.append(genai_types.Part(text=msg["text"]))
418
- for tc in msg.get("tool_calls", []):
419
- parts.append(genai_types.Part(
420
- function_call=genai_types.FunctionCall(
421
- name=tc["name"],
422
- args=tc["input"],
423
- id=tc["id"],
424
- )
425
- ))
426
- # Google rejects Content with empty parts. The turn that
427
- # produced them is now dropped above the branch split, so
428
- # this branch no longer needs its own guard -- one rule
429
- # rather than two that can disagree (#36).
430
- translated.append(genai_types.Content(role="model", parts=parts))
431
-
432
- elif role == "tool":
433
- name = call_id_to_name.get(msg["tool_call_id"])
434
- if name is None:
435
- raise ValueError(
436
- f"Tool result references tool_call_id={msg['tool_call_id']!r} "
437
- f"but no assistant message in the history made that call"
438
- )
439
- part = genai_types.Part(
440
- function_response=genai_types.FunctionResponse(
441
- name=name,
442
- response={"result": msg["content"]},
443
- )
444
- )
445
- # Batch consecutive tool results into a single user
446
- # Content — Google requires strict user/model alternation.
447
- if (translated
448
- and translated[-1].role == "user"
449
- and all(p.function_response is not None for p in translated[-1].parts)):
450
- translated[-1].parts.append(part)
451
- else:
452
- translated.append(genai_types.Content(role="user", parts=[part]))
453
-
454
- return translated
455
-
456
- if provider_name == "ANTHROPIC":
457
- translated: list[dict] = []
458
- for msg in neutral_messages:
459
- role = msg["role"]
460
-
461
- if role == "user":
462
- translated.append({"role": "user", "content": msg["content"]})
463
-
464
- elif role == "assistant":
465
- # §44. FIRST in the content array, because that is the
466
- # order the model emitted them in and the order the API
467
- # documents for the replay -- a signed block after the
468
- # text it preceded is not the same message.
469
- content = list(_echoed_blocks(provider_name, model, msg))
470
- if msg.get("text"):
471
- content.append({"type": "text", "text": msg["text"]})
472
- for tc in msg.get("tool_calls", []):
473
- content.append({
474
- "type": "tool_use", "id": tc["id"], "name": tc["name"], "input": tc["input"],
475
- })
476
- translated.append({"role": "assistant", "content": content})
477
-
478
- elif role == "tool":
479
- # Anthropic wants every tool result from one turn batched
480
- # into a SINGLE user message with multiple tool_result
481
- # blocks, not one message per result -- merge consecutive
482
- # tool-role entries into the same message rather than
483
- # appending a new one each time.
484
- block = {
485
- "type": "tool_result",
486
- "tool_use_id": msg["tool_call_id"],
487
- "content": msg["content"],
488
- }
489
- if translated and translated[-1]["role"] == "user" and _is_tool_result_message(translated[-1]):
490
- translated[-1]["content"].append(block)
491
- else:
492
- translated.append({"role": "user", "content": [block]})
493
-
494
- return translated
495
-
496
- # OpenAI-compatible: close to 1:1, each tool result is its own message
497
- translated = []
498
- for msg in neutral_messages:
499
- role = msg["role"]
500
-
501
- if role == "user":
502
- translated.append({"role": "user", "content": msg["content"]})
503
-
504
- elif role == "assistant":
505
- entry: dict = {"role": "assistant", "content": msg.get("text") or None}
506
- # §44, and OPT-IN PER PROVIDER rather than on by default.
507
- # There is no standard for sending reasoning back on this wire
508
- # the way there is for receiving it: DeepSeek documents that
509
- # reasoning_content must not be supplied on input and 400s,
510
- # while OpenRouter accepts it for some models and ignores it
511
- # for others. Off means today's behaviour exactly, so a
512
- # provider that has never been tried cannot be broken by this.
513
- if echo_reasoning:
514
- echoed = "\n\n".join(
515
- b.get("text", "") for b in _echoed_blocks(
516
- provider_name, model, msg)
517
- if b.get("text"))
518
- if echoed:
519
- entry["reasoning_content"] = echoed
520
- if msg.get("tool_calls"):
521
- entry["tool_calls"] = [
522
- {
523
- "id": tc["id"],
524
- "type": "function",
525
- "function": {"name": tc["name"], "arguments": json.dumps(tc["input"])},
526
- }
527
- for tc in msg["tool_calls"]
528
- ]
529
- translated.append(entry)
530
-
531
- elif role == "tool":
532
- translated.append({
533
- "role": "tool", "tool_call_id": msg["tool_call_id"], "content": msg["content"],
534
- })
535
-
536
- return translated
537
-
538
-
539
- # ============================================================================
540
- # ---- The actual call --------------------------------------------------------
541
- # ============================================================================
542
-
543
- # ============================================================================
544
- # ---- Sampling + reasoning-effort translation (ROADMAP_v2 §16) ---------------
545
- # ============================================================================
546
- #
547
- # Both helpers below are the same "translate at the boundary, once" case that
548
- # _tools_for_provider / _messages_for_provider exist for: the three providers
549
- # express these concepts differently enough that no caller should have to know.
550
-
551
- # (provider_name, model) -> supported effort levels. Populated lazily; the
552
- # Anthropic branch queries the API once per process rather than per call.
553
- _effort_levels_cache: dict[tuple[str, str], list[str]] = {}
554
-
555
- # (provider_name, model) -> context window in tokens, or None for "asked,
556
- # and this provider does not report one". Same lazy, once-per-process
557
- # posture as the effort cache above; see context_window_for() for why None
558
- # is cached and a raised query is not.
559
- _context_window_cache: dict[tuple[str, str], Optional[int]] = {}
560
-
561
- # (provider_name, model) -> how many times the query has RAISED.
562
- #
563
- # The middle ground between #35's two bad options. Caching a failure makes
564
- # one transient error suppress the query for the life of the process;
565
- # never caching one means a provider with no /models endpoint at all --
566
- # Grok, Fireworks, Z.AI -- is asked again on every turn, which across a
567
- # ten-pass research run is ten failing HTTP calls to learn the same thing.
568
- # So a failure is retried, and after this many it settles on the table and
569
- # says so once. Transient blips still recover; a permanent 404 costs three
570
- # calls per process, not one per turn.
571
- _context_window_failures: dict[tuple[str, str], int] = {}
572
- MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS = 3
573
-
574
-
575
- def _sampling_kwargs(provider_name: str, model: str, temperature) -> dict:
576
- """Sampling parameters for this call, or {} when the model rejects them.
577
-
578
- Current Anthropic models removed temperature/top_p/top_k outright (any
579
- value returns a 400) and Sonnet 5 rejects non-default values. Sending
580
- one anyway is not a degraded request, it is a failed one -- which is how
581
- ROADMAP §10's ensemble mode came to be built, documented as working, and
582
- incapable of running against this harness's own default model.
583
-
584
- Dropping the parameter is logged at WARNING rather than done silently.
585
-
586
- THIS FUNCTION NOW HAS NO CALLER THAT DEPENDS ON IT, and the warning is
587
- what makes that safe. Ensemble mode used to be the one, and
588
- orchestrator.py carried a guard refusing to run it on a model in the set
589
- below. §10's revisit replaced sampling variation with a roster of
590
- different models, so the guard is gone and nothing in the harness passes
591
- a temperature any more.
592
-
593
- Kept rather than removed: `temperature` still threads through
594
- core/loop.py, this is still the correct boundary translation for it, and
595
- the next caller to want sampling variation needs to be told rather than
596
- silently ignored. If this warning ever fires, something new is relying on
597
- sampling variation without knowing it cannot have it -- which is exactly
598
- how §10 came to be built, documented as working, and incapable of running
599
- against this harness's own default model.
600
- """
601
- if temperature is None:
602
- return {}
603
- if model in config.MODELS_REJECTING_SAMPLING_PARAMS:
604
- logger.warning(
605
- "Dropping temperature=%s: model %r rejects sampling parameters. "
606
- "Steer via prompting or reasoning effort instead.",
607
- temperature, model,
608
- )
609
- return {}
610
- return {"temperature": temperature}
611
-
612
-
613
- def effort_for(client, provider_name: str, model: str,
614
- requested: Optional[str]) -> Optional[str]:
615
- """The effort level to actually SEND to (provider_name, model), or None.
616
-
617
- One validator for every send site, because nothing else checked a
618
- level against the model that would receive it. Three ways a wrong one
619
- used to reach the wire, all of them 400ing every turn until the user
620
- intervened by hand:
621
-
622
- * a persisted settings.json `tui.effort` was trusted as-is;
623
- * the TUI's current level was inherited by an agent that declares
624
- its OWN model/provider, so a level validated for one model was
625
- sent to a different one;
626
- * nothing revalidated after a /model or agent switch.
627
-
628
- `effort=None` sends nothing on every provider and is the one
629
- universally safe value, so dropping is always available as an answer.
630
-
631
- On a FAILED lookup the requested level is passed through unverified
632
- with a warning rather than dropped: a transient network blip must not
633
- silently downgrade a deliberate choice. A genuinely wrong level still
634
- fails at the provider, which is the honest outcome.
635
- """
636
- if not requested:
637
- return None
638
- levels, authoritative = _effort_levels(client, provider_name, model)
639
- if requested in levels:
640
- return requested
641
- if not authoritative:
642
- logger.warning(
643
- "Could not verify effort %r for %s/%s; sending it unverified.",
644
- requested, provider_name, model)
645
- return requested
646
- logger.warning(
647
- "Dropping effort %r: %s/%s accepts %s. Sending no effort parameter.",
648
- requested, provider_name, model, levels or "no effort control")
649
- return None
650
-
651
-
652
- def effort_levels_for_model(client, provider_name: str, model: str) -> list[str]:
653
- """Reasoning-effort levels this model accepts, most-to-least capable last.
654
-
655
- Anthropic is queried, not tabulated: its Models API reports per-model
656
- effort support (`capabilities.effort.<level>.supported`), so a newly
657
- released Anthropic model needs no manual entry here. Every other provider
658
- is tabulated because there is nothing to ask -- no OpenAI-compatible
659
- provider in providers.json exposes a capability endpoint, and Google
660
- expresses depth as an integer budget rather than a level set at all.
661
-
662
- Falling back logs at WARNING, matching §21's MODEL_CONTEXT_WINDOWS
663
- posture: a static table is honest about being incomplete, but it should
664
- say so out loud when it is the thing answering.
665
-
666
- Returns [] when the model supports no effort control, which callers must
667
- treat as "offer no picker and send no effort parameter".
668
- """
669
- return _effort_levels(client, provider_name, model)[0]
670
-
671
-
672
- def _effort_levels(client, provider_name: str, model: str) -> tuple:
673
- """(levels, authoritative).
674
-
675
- `authoritative` is False when the answer came from the static table
676
- after the capability QUERY failed, as opposed to because no query was
677
- ever possible for that provider. Only effort_for() needs the
678
- distinction -- an unverified answer must not be used to drop a level
679
- the user deliberately chose.
680
- """
681
- key = (provider_name, model)
682
- if key in _effort_levels_cache:
683
- return _effort_levels_cache[key], True
684
-
685
- levels: Optional[list[str]] = None
686
- query_failed = False
687
- if provider_name == "GOOGLE" and not _google_supports_thinking_budget():
688
- # Reporting no levels is the honest answer, not a silent [] : on the
689
- # pinned SDK there is no field to put a budget in, so a picker
690
- # offering levels would be offering something unsendable.
691
- _effort_levels_cache[key] = []
692
- return [], True
693
- if provider_name == "ANTHROPIC":
694
- try:
695
- # ATTRIBUTES, not subscripts (#35). This read used to be
696
- # `capabilities["effort"]` with `effort.get(name)` and
697
- # `isinstance(..., dict)`. On the exactly-pinned SDK those are
698
- # pydantic models -- ModelCapabilities, EffortCapability,
699
- # CapabilitySupport -- supporting neither [] nor .get(), so the
700
- # TypeError was caught below, query_failed was set, and the
701
- # query FELL BACK EVERY SINGLE TIME. Not "failed sometimes":
702
- # it could not succeed. All three dict spellings were wrong,
703
- # so correcting the subscript alone would have failed one line
704
- # further down.
705
- #
706
- # No dict/attribute dual path on purpose. A defensive default
707
- # is only safe where absence is impossible, requirements.txt
708
- # pins anthropic exactly, and test_sdk_conformance.py exists
709
- # to go red when the pinned shape moves -- which is a better
710
- # signal than a fallback that silently keeps guessing.
711
- info = client.models.retrieve(model)
712
- # ONE retrieve, TWO readings (§21's revisit). The context
713
- # window is on this SAME ModelInfo as `max_input_tokens`, so
714
- # recording it here IS the entire Anthropic half of the
715
- # window query: no second call, no second failure mode, and
716
- # it lands on the path every send already crosses
717
- # (core/loop.py calls effort_for before the wire). §21
718
- # rejected a window query on the belief that there was
719
- # nothing to ask; for this provider the answer was already
720
- # in hand and being dropped. See context_window_for below.
721
- _record_window(provider_name, model,
722
- getattr(info, "max_input_tokens", None))
723
- capabilities = info.capabilities
724
- effort = capabilities.effort
725
- levels = [
726
- name for name in ("low", "medium", "high", "xhigh", "max")
727
- # getattr, because `xhigh` is Optional on the pinned type
728
- # and a model that does not offer a level reports None
729
- # rather than supported=False.
730
- if getattr(getattr(effort, name, None), "supported", False)
731
- ]
732
- except Exception as e:
733
- # Network failure, an SDK too old to expose capabilities, or a
734
- # model the endpoint doesn't know. Fall through to the table.
735
- query_failed = True
736
- logger.warning(
737
- "Could not read effort capabilities for %r from the Anthropic "
738
- "Models API (%s); falling back to the static table.", model, e,
739
- )
740
-
741
- if levels is None:
742
- levels = config.MODEL_EFFORT_LEVELS.get(model)
743
- if levels is None:
744
- logger.warning(
745
- "No effort levels known for %r on %s; assuming %s. Add an entry "
746
- "to config.MODEL_EFFORT_LEVELS if this is wrong.",
747
- model, provider_name, config.DEFAULT_EFFORT_LEVELS,
748
- )
749
- levels = list(config.DEFAULT_EFFORT_LEVELS)
750
-
751
- if query_failed:
752
- # Do NOT cache a failure-derived guess. Caching it made one
753
- # transient error permanently suppress the query that is this
754
- # function's entire reason to exist: for the whole process life
755
- # the picker would offer a guessed level set, and every selection
756
- # from it could 400 with no path back short of a restart.
757
- return levels, False
758
-
759
- _effort_levels_cache[key] = levels
760
- return levels, True
761
-
762
-
763
- # The field names a provider might report a context window under, in the
764
- # order they are tried. ONE reader covers every OpenAI-compatible provider
765
- # rather than one adapter each, because openai.types.Model is declared
766
- # `extra="allow"` -- a field the SDK does not model survives on the parsed
767
- # object and reaches `.model_extra`. Verified against the pinned openai
768
- # 2.45.0 in test_sdk_conformance.py, because that permissiveness is the
769
- # whole reason this is one function.
770
- #
771
- # context_window Groq
772
- # context_length Together, OpenRouter, Cohere (native /v1 only)
773
- # max_context_length Mistral
774
- # max_input_tokens Anthropic's spelling, accepted here so a gateway
775
- # proxying Anthropic through an OpenAI-shaped API
776
- # is not silently unreadable
777
- #
778
- # OpenAI, DeepSeek and Perplexity report NONE of these -- they answer with
779
- # id/created/object/owned_by and nothing else. That is not a failure, it is
780
- # the answer, and it is why config.MODEL_CONTEXT_WINDOWS still exists.
781
- _WINDOW_FIELD_ALIASES = (
782
- "context_window",
783
- "context_length",
784
- "max_context_length",
785
- "max_input_tokens",
786
- )
787
-
788
- #: Returned by _model_info when a COMPLETE listing did not contain the model.
789
- #: Distinct from a raise: the provider answered, so there is nothing to retry.
790
- _NOT_LISTED = object()
791
-
792
-
793
- def _window_from_model_object(info) -> Optional[int]:
794
- """The context window off one provider model object, or None.
795
-
796
- Declared fields first, then model_extra -- the same object may carry
797
- either depending on whether the installed SDK models the field.
798
- ATTRIBUTES not subscripts, for #35's reason: these are pydantic objects
799
- on every pinned SDK here.
800
-
801
- `top_provider.context_length` is the one NESTED spelling, and it is
802
- OpenRouter's: the flat `context_length` is the model's maximum across
803
- every backend, while top_provider carries the routed one. Read second,
804
- so the flat value still wins where both exist -- this is a fallback for
805
- entries that carry only the nested form, not a preference for the
806
- narrower number.
807
- """
808
- extra = getattr(info, "model_extra", None) or {}
809
- for name in _WINDOW_FIELD_ALIASES:
810
- value = getattr(info, name, None)
811
- if value is None:
812
- value = extra.get(name)
813
- if value is not None:
814
- return value
815
- top = extra.get("top_provider")
816
- if isinstance(top, dict):
817
- return top.get("context_length")
818
- return None
819
-
820
-
821
- def _model_info(client, model):
822
- """The provider's object for one model, via retrieve or via the listing.
823
-
824
- THE ROUTE WAS THE BUG, NOT THE READER (batch 44). This asked
825
- `client.models.retrieve(model)` alone, which is `GET {base}/models/{id}`
826
- -- and OpenRouter implements `GET /api/v1/models` plus
827
- `/models/:author/:slug/endpoints` and no plain per-id retrieve, so an id
828
- containing a slash (`minimax/minimax-m3`) turns the path into a route
829
- that does not exist. 404, every time, on a provider whose listing has
830
- carried `context_length` all along and which _WINDOW_FIELD_ALIASES'
831
- own comment names. NVIDIA's endpoint has the same shape, and so does
832
- every other provider whose ids are `vendor/model`.
833
-
834
- Retrieve stays FIRST: it is one call and it is the right one for Groq,
835
- Together and Mistral, and a listing can be hundreds of entries. The
836
- fallback costs one extra call per provider per process, on the path
837
- that was previously three failures and a permanent give-up.
838
-
839
- Three outcomes, deliberately distinct:
840
- an object something answered
841
- _NOT_LISTED a complete listing came back without this model, which
842
- is an ANSWER ("this provider has nothing to say about
843
- it") and must not be retried like a network blip
844
- raises neither route could answer; the caller counts it
845
- """
846
- try:
847
- return client.models.retrieve(model)
848
- except Exception as retrieve_error:
849
- listing = getattr(getattr(client, "models", None), "list", None)
850
- if listing is None:
851
- raise
852
- try:
853
- entries = list(listing())
854
- except Exception:
855
- # The listing is not a second opinion about the retrieve; it is
856
- # the same question by another route. Report the FIRST failure,
857
- # which is the one that names the endpoint the caller asked for.
858
- raise retrieve_error from None
859
- for entry in entries:
860
- if getattr(entry, "id", None) == model:
861
- return entry
862
- if not entries:
863
- # An empty listing answered nothing at all; report the failure
864
- # that names the endpoint the caller actually asked for.
865
- raise retrieve_error from None
866
- return _NOT_LISTED
867
-
868
-
869
- def _record_window(provider_name: str, model: str, value) -> Optional[int]:
870
- """Cache a queried window, coercing anything unusable to None.
871
-
872
- A POSITIVE int or nothing. The Anthropic Models API types
873
- `max_input_tokens` as nullable and its own documented example carries
874
- a placeholder 0, so "present" is not "usable" -- and a 0 reaching
875
- compaction would make `context_limit - backstop` clamp to the floor
876
- and compact continuously. Anything that is not a positive int is
877
- recorded as None, which means "asked, got no usable answer" and sends
878
- the caller to the static table.
879
- """
880
- window = value if isinstance(value, int) and not isinstance(value, bool) else None
881
- if window is not None and window <= 0:
882
- window = None
883
- _context_window_cache[(provider_name, model)] = window
884
- return window
885
-
886
-
887
- def known_context_window(provider_name: str, model: str) -> Optional[int]:
888
- """The queried window for (provider, model), or None if none is known.
889
-
890
- CACHE ONLY -- this never makes a call, which is what lets
891
- core/compaction.py ask the question without holding a client or
892
- importing an SDK. The cache is primed by context_window_for() on the
893
- path core/loop.py already crosses before every send, so by the time a
894
- compaction check runs the answer is there if the provider had one.
895
- """
896
- return _context_window_cache.get((provider_name, model))
897
-
898
-
899
- def context_window_for(client, provider_name: str, model: str) -> tuple:
900
- """(window_or_None, authoritative). Queries the provider once per process.
901
-
902
- §21 rejected this as needing "fifteen adapters" for a roster where no
903
- uniform endpoint existed. Re-measured against the PINNED SDKs, that
904
- premise did not hold, and the shape below is what it actually costs:
905
-
906
- ANTHROPIC already answered. _effort_levels retrieves the ModelInfo
907
- to read capabilities.effort and max_input_tokens rides
908
- along on it, so this branch is usually a cache hit and
909
- makes no call at all.
910
- GOOGLE models.get(...).input_token_limit, one field on the
911
- pinned google-genai type.
912
- v1-compat ONE alias sniff over model_extra, not thirteen adapters,
913
- because openai.types.Model allows extra fields -- over
914
- whichever of models.retrieve() and models.list() answers
915
- (see _model_info: providers whose ids carry a slash have
916
- no per-id route, so retrieve 404s on them).
917
-
918
- §21's CONCLUSION survives intact and is why the table remains: OpenAI,
919
- DeepSeek and Perplexity report nothing, so a fallback constant is
920
- still needed at the end of it.
921
-
922
- THE FAILURE/SILENCE SPLIT IS THE POINT, and it is _effort_levels'
923
- query_failed rule (#35's lesson) applied to a second query. A call
924
- that RAISED is warned and NOT cached: a transient network error must
925
- not permanently suppress the query for the life of the process. A
926
- call that SUCCEEDED and reported no window IS cached as None, because
927
- that is a real and stable answer, and re-asking it on every
928
- compaction evaluation would spend a request per step to learn the
929
- same thing.
930
- """
931
- key = (provider_name, model)
932
- if key in _context_window_cache:
933
- return _context_window_cache[key], True
934
-
935
- try:
936
- if provider_name == "GOOGLE":
937
- info = client.models.get(model=model)
938
- return _record_window(
939
- provider_name, model,
940
- getattr(info, "input_token_limit", None)), True
941
- info = _model_info(client, model)
942
- if info is _NOT_LISTED:
943
- # Asked and answered by a listing that did not name it.
944
- return _record_window(provider_name, model, None), True
945
- window = _window_from_model_object(info)
946
- if window is not None:
947
- return _record_window(provider_name, model, window), True
948
- # Asked and answered: this provider reports no window.
949
- return _record_window(provider_name, model, None), True
950
- except Exception as e:
951
- # Network failure, a provider with no models endpoint at all, or a
952
- # model the endpoint does not know. Not cached as an ANSWER -- see
953
- # the docstring -- but counted, so a permanent failure stops being
954
- # re-asked once it has proved it is not a blip.
955
- attempts = _context_window_failures.get(key, 0) + 1
956
- _context_window_failures[key] = attempts
957
- giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
958
- logger.warning(
959
- "Could not read a context window for %r from %s (%s); "
960
- "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
961
- model, provider_name, e,
962
- " Not asking again this session." if giving_up else "")
963
- if giving_up:
964
- _record_window(provider_name, model, None)
965
- return None, False
966
-
967
-
968
- _google_budget_support: Optional[bool] = None
969
-
970
-
971
- def _google_supports_thinking_budget() -> bool:
972
- """Whether the INSTALLED google-genai can express a thinking budget.
973
-
974
- Checked rather than assumed, and the check earns its keep: the pinned
975
- google-genai (1.0.0) ships a ThinkingConfig whose only field is
976
- `include_thoughts` -- `thinking_budget` arrived in a later release. So
977
- the obvious implementation, ThinkingConfig(thinking_budget=N), raises a
978
- TypeError against the version this repo actually pins.
979
-
980
- Rather than bump the pin (which would put §9's verified Google
981
- implementation back in play for a feature Google users can do without),
982
- reasoning effort is simply unavailable on Google until the pin moves.
983
- D22's rule, applied: check the dependency's real shape, don't assume it.
984
- """
985
- from google.genai import types as genai_types
986
-
987
- global _google_budget_support
988
- if _google_budget_support is None:
989
- fields = getattr(genai_types.ThinkingConfig, "model_fields", {})
990
- _google_budget_support = "thinking_budget" in fields
991
- if not _google_budget_support:
992
- logger.info(
993
- "Installed google-genai has no ThinkingConfig.thinking_budget; "
994
- "reasoning effort is unavailable on GOOGLE until the pin moves."
995
- )
996
- return _google_budget_support
997
-
998
-
999
- def _thinking_record(provider_name: str, model: str,
1000
- blocks: list) -> Optional[dict]:
1001
- """The turn's reasoning in the shape ModelResponse.thinking carries.
1002
-
1003
- None when the turn produced none, so "no reasoning" and "a provider
1004
- that reports none" stay one thing and no row is written for either.
1005
- """
1006
- if not blocks:
1007
- return None
1008
- return {"provider": provider_name, "model": model, "blocks": blocks}
1009
-
1010
-
1011
- def _thinking_for_provider(provider_name: str, effort: Optional[str]) -> dict:
1012
- """Reasoning-effort kwargs for this provider, or {} when no effort is set.
1013
-
1014
- Effort is opt-in: `effort=None` sends nothing at all and every provider
1015
- behaves exactly as it did before §16. That matters because the parameter
1016
- is not universally safe -- `reasoning_effort` is rejected by
1017
- OpenAI-compatible NON-reasoning models, and `thinking: {"type": "adaptive"}`
1018
- is rejected by pre-4.6 Anthropic models. Callers are expected to offer
1019
- only the levels effort_levels_for_model() reported, and to offer nothing
1020
- when it reported none.
1021
-
1022
- Returned keys are merged into the provider's own kwargs by the caller;
1023
- the Google entry is nested inside GenerateContentConfig rather than sent
1024
- top-level, matching how that provider takes every other setting.
1025
- """
1026
- if not effort:
1027
- return {}
1028
- if provider_name == "ANTHROPIC":
1029
- # Adaptive thinking + an effort level is the current-model pairing;
1030
- # `display` is EXPLICIT because its default changed under us. On
1031
- # Fable 5, Opus 5, Opus 4.8/4.7 and Sonnet 5 it defaults to
1032
- # "omitted", which still streams thinking blocks but with EMPTY
1033
- # text -- so §38's whole feature rendered nothing at all on
1034
- # Anthropic: ev.thinking was "", core/loop.py's `if
1035
- # token.thinking_delta` never fired, and neither the inline block
1036
- # nor ThinkingIndicator ever appeared. It looked like it worked
1037
- # because the OpenAI-compatible branch reads reasoning_content and
1038
- # is unaffected. The raw chain of thought is never exposed on any
1039
- # model; "summarized" is the readable form, and it is what the
1040
- # blocks captured below carry back to the model that wrote them.
1041
- # budget_tokens was removed and returns a 400.
1042
- return {
1043
- "thinking": {"type": "adaptive", "display": "summarized"},
1044
- "output_config": {"effort": effort},
1045
- }
1046
- if provider_name == "GOOGLE":
1047
- from google.genai import types as genai_types
1048
- budget = config.GOOGLE_THINKING_BUDGETS.get(effort)
1049
- if budget is None or not _google_supports_thinking_budget():
1050
- return {}
1051
- return {"thinking_config": genai_types.ThinkingConfig(thinking_budget=budget)}
1052
- return {"reasoning_effort": effort}
1053
-
1054
-
1055
- # ============================================================================
1056
- # ---- Streaming call + helpers -----------------------------------------------
1057
- # ============================================================================
1058
-
1059
- def call_model_stream(
1060
- client,
1061
- provider_name: str,
1062
- model: str,
1063
- messages: list[dict],
1064
- system_prompt: str,
1065
- tool_schemas: list[dict],
1066
- temperature: Optional[float] = None,
1067
- effort: Optional[str] = None,
1068
- ):
1069
- """The one model call, for every provider. Yields StreamToken
1070
- events: text_delta for incremental text, thinking_delta for
1071
- incremental reasoning text where the provider sends any (§38 O2),
1072
- final_response for the terminal ModelResponse with accumulated tool
1073
- calls and usage.
1074
-
1075
- Three provider implementations — Anthropic typed events, Google
1076
- chunked candidates, OpenAI-compatible index-accumulated tool-call
1077
- fragments — which must agree with each other about the ModelResponse
1078
- they produce for the same inputs.
1079
-
1080
- There used to be a non-streaming `call_model()` beside this, and this
1081
- docstring used to promise the two were identical. They were not: it
1082
- set ModelResponse.raw and no streaming branch did, which is what a
1083
- second implementation nobody runs accumulates (#38). It is gone, and
1084
- with it `raw`; the only thing left to keep in step is the three
1085
- branches below.
1086
-
1087
- D21 (usage-or-raise): if the provider is marked as supporting stream
1088
- usage but the stream completes with zero usage, raise rather than
1089
- silently reporting zero (which disables budget enforcement and §21's
1090
- compaction trigger).
1091
- """
1092
- # Read once so every branch applies the same D21 usage-or-raise rule --
1093
- # all three of them, since audit #40. This comment used to claim that in
1094
- # its first sentence and take it back in the second ("the flag only gates
1095
- # the Google and OpenAI-compatible branches"), which left the one
1096
- # provider whose example config ships the flag `true` as the one provider
1097
- # where setting it did nothing.
1098
- provider_data = load_provider_data()
1099
- supports_stream_usage = provider_data.get(provider_name, {}).get(
1100
- "supports_stream_usage", False
1101
- )
1102
- # §44. Whether this OpenAI-compatible provider accepts its own
1103
- # reasoning back on the next request. supports_stream_usage's
1104
- # precedent: a per-provider fact that cannot be discovered and must not
1105
- # be guessed, so it lives beside the endpoint it describes and defaults
1106
- # to the conservative answer.
1107
- echoes_reasoning = provider_data.get(provider_name, {}).get(
1108
- "echoes_reasoning", False
1109
- )
1110
-
1111
- translated_messages = _messages_for_provider(
1112
- provider_name, messages, model, echoes_reasoning)
1113
- sampling = _sampling_kwargs(provider_name, model, temperature)
1114
- thinking = _thinking_for_provider(provider_name, effort)
1115
-
1116
- if provider_name == "ANTHROPIC":
1117
- stream_kwargs = dict(
1118
- model=model,
1119
- max_tokens=config.MAX_TOKENS,
1120
- system=system_prompt,
1121
- messages=translated_messages,
1122
- tools=_tools_for_provider(provider_name, tool_schemas),
1123
- )
1124
- stream_kwargs.update(sampling)
1125
- stream_kwargs.update(thinking)
1126
-
1127
- with client.messages.stream(**stream_kwargs) as stream:
1128
- # §38 O3. Iterating the STREAM rather than stream.text_stream,
1129
- # because text_stream yields text deltas only and there is no
1130
- # way to have both: `text_stream` is an instance attribute
1131
- # built from the same underlying iterator in MessageStream's
1132
- # __init__, so consuming one consumes the other.
1133
- #
1134
- # The SDK emits its own synthetic events beside the raw ones --
1135
- # TextEvent(type="text", text=<delta>) and
1136
- # ThinkingEvent(type="thinking", thinking=<delta>) -- which is
1137
- # why this reads two attribute names rather than unpacking
1138
- # content_block_delta by hand. Verified against the pinned
1139
- # anthropic==0.116.0 rather than assumed (D22), and pinned in
1140
- # tests/test_sdk_conformance.py.
1141
- #
1142
- # Every other event kind is ignored on purpose: `text` is the
1143
- # accumulated answer read off get_final_message() below, not
1144
- # off these deltas, so nothing here can change what this
1145
- # branch returns.
1146
- for ev in stream:
1147
- kind = getattr(ev, "type", None)
1148
- if kind == "text":
1149
- yield StreamToken(text_delta=ev.text)
1150
- elif kind == "thinking":
1151
- yield StreamToken(thinking_delta=ev.thinking)
1152
- final_msg = stream.get_final_message()
1153
- text = "\n".join(
1154
- b.text for b in final_msg.content if b.type == "text"
1155
- )
1156
- calls = [
1157
- ToolCallRequest(id=b.id, name=b.name, input=b.input)
1158
- for b in final_msg.content if b.type == "tool_use"
1159
- ]
1160
- # model_dump() rather than a hand-built dict: what goes back on
1161
- # the wire has to be what came off it, field for field, or the
1162
- # signature does not verify. redacted_thinking is included for
1163
- # the same reason -- it is opaque to us and meaningful to the
1164
- # model, so dropping it would silently break a turn that had
1165
- # one.
1166
- thinking_blocks = [
1167
- b.model_dump() for b in final_msg.content
1168
- if b.type in ("thinking", "redacted_thinking")
1169
- ]
1170
- usage_obj = getattr(final_msg, "usage", None)
1171
- usage = {
1172
- "input_tokens": getattr(usage_obj, "input_tokens", 0) if usage_obj else 0,
1173
- "output_tokens": getattr(usage_obj, "output_tokens", 0) if usage_obj else 0,
1174
- }
1175
-
1176
- # D21 parity with the other two branches (audit #40). This branch
1177
- # used to be exempt on the reasoning that get_final_message() always
1178
- # carries usage -- which is very likely right for anthropic==0.116.0,
1179
- # and is exactly the kind of assumption D21 exists because nobody can
1180
- # verify from inside. The getattr defaults above are the softened
1181
- # form D21's own note forbids, so on the DEFAULT provider an SDK
1182
- # field rename would have zeroed the budget silently, disabling both
1183
- # the budget stop condition and §21's compaction trigger. That is the
1184
- # mcp v1->v2 failure mode, and #35 is this file's live example of it.
1185
- #
1186
- # Honouring the flag rather than always raising keeps it meaning ONE
1187
- # thing on all three providers, which is the coherence #40 is about;
1188
- # providers.json.example ships it true for ANTHROPIC, so the default
1189
- # posture is the checked one, and a proxy that genuinely omits usage
1190
- # can still opt out instead of being unable to run.
1191
- if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1192
- raise RuntimeError(
1193
- f"Streaming call to {provider_name} completed without usage "
1194
- f"data despite supports_stream_usage=True. The stream may "
1195
- f"have been interrupted before the final usage chunk."
1196
- )
1197
-
1198
- yield StreamToken(final_response=ModelResponse(
1199
- text=text, tool_calls=calls, usage=usage,
1200
- thinking=_thinking_record(provider_name, model, thinking_blocks),
1201
- ))
1202
- return
1203
-
1204
- if provider_name == "GOOGLE":
1205
- from google.genai import types as genai_types
1206
- genai_config_kwargs = dict(
1207
- system_instruction=system_prompt,
1208
- tools=_tools_for_provider(provider_name, tool_schemas),
1209
- max_output_tokens=config.MAX_TOKENS,
1210
- )
1211
- genai_config_kwargs.update(sampling)
1212
- genai_config_kwargs.update(thinking)
1213
-
1214
- text_parts = []
1215
- calls = []
1216
- usage = {"input_tokens": 0, "output_tokens": 0}
1217
-
1218
- for chunk in client.models.generate_content_stream(
1219
- model=model,
1220
- contents=translated_messages,
1221
- config=genai_types.GenerateContentConfig(**genai_config_kwargs),
1222
- ):
1223
- candidate = chunk.candidates[0] if chunk.candidates else None
1224
- content = candidate.content if candidate else None
1225
- parts = content.parts if content else []
1226
- for p in parts:
1227
- if p.text is not None:
1228
- text_parts.append(p.text)
1229
- yield StreamToken(text_delta=p.text)
1230
- if p.function_call is not None:
1231
- fc = p.function_call
1232
- calls.append(ToolCallRequest(
1233
- id=fc.id or str(uuid4()),
1234
- name=fc.name,
1235
- input=fc.args or {},
1236
- ))
1237
- usage_meta = getattr(chunk, "usage_metadata", None)
1238
- if usage_meta:
1239
- usage["input_tokens"] = getattr(usage_meta, "prompt_token_count", 0)
1240
- usage["output_tokens"] = getattr(usage_meta, "candidates_token_count", 0)
1241
-
1242
- # D21 parity with the OpenAI branch: raise if marked as supporting
1243
- # stream usage but the stream completed with zero usage.
1244
- if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1245
- raise RuntimeError(
1246
- f"Streaming call to {provider_name} completed without usage "
1247
- f"data despite supports_stream_usage=True. The stream may "
1248
- f"have been interrupted before the final usage chunk."
1249
- )
1250
-
1251
- yield StreamToken(final_response=ModelResponse(
1252
- text="".join(text_parts), tool_calls=calls, usage=usage,
1253
- ))
1254
- return
1255
-
1256
- # OpenAI-compatible path (supports_stream_usage already read above)
1257
- full_messages = [{"role": "system", "content": system_prompt}] + translated_messages
1258
- openai_kwargs = dict(
1259
- model=model,
1260
- messages=full_messages,
1261
- max_completion_tokens=config.MAX_TOKENS,
1262
- tools=_tools_for_provider(provider_name, tool_schemas),
1263
- stream=True,
1264
- )
1265
- openai_kwargs.update(sampling)
1266
- openai_kwargs.update(thinking)
1267
- if supports_stream_usage:
1268
- openai_kwargs["stream_options"] = {"include_usage": True}
1269
-
1270
- text_parts = []
1271
- reasoning_parts = []
1272
- tool_fragments: dict[int, dict] = {}
1273
- usage = {"input_tokens": 0, "output_tokens": 0}
1274
-
1275
- finish_reason = None
1276
- for chunk in client.chat.completions.create(**openai_kwargs):
1277
- if chunk.choices:
1278
- # W4 (#37): free -- chunk.choices[0] is already read here. The
1279
- # provider sets this on the last content chunk, and `or
1280
- # finish_reason` keeps it once seen because the usage chunk
1281
- # that follows carries none. getattr because a chunk is only
1282
- # required to have `delta`.
1283
- choice = chunk.choices[0]
1284
- finish_reason = getattr(choice, "finish_reason", None) or finish_reason
1285
- delta = choice.delta
1286
- if delta.content:
1287
- text_parts.append(delta.content)
1288
- yield StreamToken(text_delta=delta.content)
1289
- # §38 O3. Reasoning text, where the provider sends any. There
1290
- # is no standard field: DeepSeek, Qwen and Z.AI use
1291
- # `reasoning_content`, OpenRouter and Groq use `reasoning`,
1292
- # and OpenAI's own endpoint sends neither. openai's ChoiceDelta
1293
- # is extra="allow" (pinned in test_sdk_conformance.py), so an
1294
- # unknown-to-the-SDK field arrives as a real attribute.
1295
- #
1296
- # NEVER appended to text_parts: reasoning is not the answer,
1297
- # and folding it in would change every ModelResponse this
1298
- # branch returns and put reasoning into the thread as though
1299
- # the model had said it. It is accumulated SEPARATELY instead
1300
- # (batch 44), into ModelResponse.thinking, where it is kept as
1301
- # this provider's own field name rather than as prose -- an
1302
- # echo back on the wire has to spell it the way the provider
1303
- # spelled it.
1304
- reasoning = (getattr(delta, "reasoning_content", None)
1305
- or getattr(delta, "reasoning", None))
1306
- if isinstance(reasoning, str) and reasoning:
1307
- reasoning_parts.append(reasoning)
1308
- yield StreamToken(thinking_delta=reasoning)
1309
- if delta.tool_calls:
1310
- for tc_delta in delta.tool_calls:
1311
- idx = tc_delta.index
1312
- if idx not in tool_fragments:
1313
- tool_fragments[idx] = {
1314
- "id": "", "name_parts": [], "arguments_parts": [],
1315
- }
1316
- if tc_delta.id:
1317
- tool_fragments[idx]["id"] = tc_delta.id
1318
- # Accumulate name like arguments: some v1-compatible
1319
- # providers split function.name across deltas, so a
1320
- # last-write-wins assignment would corrupt the name.
1321
- if tc_delta.function and tc_delta.function.name:
1322
- tool_fragments[idx]["name_parts"].append(
1323
- tc_delta.function.name
1324
- )
1325
- if tc_delta.function and tc_delta.function.arguments:
1326
- tool_fragments[idx]["arguments_parts"].append(
1327
- tc_delta.function.arguments
1328
- )
1329
- usage_obj = getattr(chunk, "usage", None)
1330
- if usage_obj:
1331
- usage["input_tokens"] = getattr(usage_obj, "prompt_tokens", 0)
1332
- usage["output_tokens"] = getattr(usage_obj, "completion_tokens", 0)
1333
-
1334
- # D21: if the provider is marked as supporting stream usage but we
1335
- # got zero usage, the stream was likely interrupted before the final
1336
- # usage chunk arrived. Raise rather than silently reporting zero.
1337
- if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1338
- raise RuntimeError(
1339
- f"Streaming call to {provider_name} completed without usage "
1340
- f"data despite supports_stream_usage=True. The stream may "
1341
- f"have been interrupted before the final usage chunk."
1342
- )
1343
-
1344
- calls = []
1345
- for idx in sorted(tool_fragments):
1346
- frag = tool_fragments[idx]
1347
- name = "".join(frag["name_parts"])
1348
- parsed, parse_error = _tool_arguments(
1349
- "".join(frag["arguments_parts"]), name, finish_reason)
1350
- if parse_error is not None:
1351
- logger.warning(
1352
- "%s: %s (finish_reason=%r)", name, parse_error, finish_reason)
1353
- calls.append(ToolCallRequest(
1354
- id=frag["id"], name=name, input=parsed, parse_error=parse_error,
1355
- ))
1356
-
1357
- # ONE block, not one per delta. There is no block structure on this
1358
- # wire -- reasoning arrives as a flat string of deltas -- so the record
1359
- # is the concatenation under the field name the request would use to
1360
- # send it back. `type` names the shape for _messages_for_provider;
1361
- # nothing about it is the provider's, which is why it is spelled after
1362
- # the field rather than after Anthropic's "thinking".
1363
- reasoning_blocks = ([{"type": "reasoning_content",
1364
- "text": "".join(reasoning_parts)}]
1365
- if reasoning_parts else [])
1366
-
1367
- yield StreamToken(final_response=ModelResponse(
1368
- text="".join(text_parts), tool_calls=calls, usage=usage,
1369
- thinking=_thinking_record(provider_name, model, reasoning_blocks),
1370
- ))
1371
-
1372
-
1373
- # ===========================================================================
1374
- # ---- Embeddings (ROADMAP_v2 §45, SQ2/SQ7) ---------------------------------
1375
- # ===========================================================================
1376
- #
1377
- # §33's rule is that this file is where a model call lives, and an
1378
- # embedding is a model call. It shares `api_initialization` and its client
1379
- # cache with the chat path, so an embedder on a provider already in use
1380
- # costs no second client.
1381
- #
1382
- # WHAT THIS DELIBERATELY DOES NOT SHARE. No streaming, no tool
1383
- # translation, no `effort`, no context-window check, and no entry in
1384
- # `ModelResponse`: none of those mean anything for a call that takes
1385
- # strings and returns vectors. `EmbeddingResult` is its own small shape
1386
- # for the same reason ToolCallRequest is -- widening ModelResponse with
1387
- # three fields that are null on every chat turn is how a response object
1388
- # stops describing anything.
1389
-
1390
-
1391
- class EmbeddingError(RuntimeError):
1392
- """An embedding call that could not produce usable vectors.
1393
-
1394
- ITS OWN TYPE, so §45's scoring stage can catch exactly this and fall
1395
- back to the model's own similarity (SQ10) without also swallowing a
1396
- programming error from inside its own chunker. The message names the
1397
- provider and the model, because the two most common causes -- a
1398
- provider with no embeddings endpoint, and a chat model slug passed to
1399
- one -- are both fixed by changing one of those two words.
1400
- """
1401
-
1402
-
1403
- @dataclass
1404
- class EmbeddingResult:
1405
- """Vectors for the texts that were sent, in the order they were sent.
1406
-
1407
- `usage` mirrors ModelResponse's shape but carries input tokens only:
1408
- an embedding call produces no output tokens, and reporting a zero
1409
- under a key that means something elsewhere would put embedding spend
1410
- into a total that is documented as billed input+output of model calls.
1411
- §45 counts it separately and says so.
1412
- """
1413
-
1414
- vectors: list = field(default_factory=list)
1415
- model: str = ""
1416
- provider_name: str = ""
1417
- usage: dict = field(default_factory=lambda: {"input_tokens": 0})
1418
-
1419
- @property
1420
- def dimension(self) -> int:
1421
- return len(self.vectors[0]) if self.vectors else 0
1422
-
1423
-
1424
- # Providers with no embeddings endpoint at all, where the failure is worth
1425
- # naming rather than surfacing as a 404 from inside a research run.
1426
- #
1427
- # ANTHROPIC IS NOT AN OVERSIGHT. There is no Anthropic embeddings API; the
1428
- # recommended route is a third-party embedder, which this harness reaches
1429
- # as its own provider entry. OPENROUTER proxies chat completions only.
1430
- #
1431
- # INCOMPLETE ON PURPOSE, and safe when incomplete -- the same posture as
1432
- # MODELS_REJECTING_SAMPLING_PARAMS. An unlisted provider that turns out to
1433
- # have no endpoint fails loudly on the probe `/embedder` runs at selection
1434
- # time, which is a measurement rather than a guess and is why there is no
1435
- # `supports_embeddings` table to keep in step with the world.
1436
- PROVIDERS_WITHOUT_EMBEDDINGS = frozenset({"ANTHROPIC", "OPENROUTER"})
1437
-
1438
-
1439
- def embed_texts(provider_name: str, model: str, texts,
1440
- *, prefix: str = "", task_type: str = "") -> EmbeddingResult:
1441
- """Embed `texts` with `model` on `provider_name`.
1442
-
1443
- `prefix` is prepended to every text in this call. Asymmetric embedders
1444
- -- e5's `"query: "` / `"passage: "`, BGE's instruction prefix -- score
1445
- materially worse without it and produce no error at all, so it is
1446
- configuration rather than something inferred from a model slug.
1447
- `task_type` is Google's equivalent (`RETRIEVAL_QUERY` /
1448
- `RETRIEVAL_DOCUMENT`) and is ignored elsewhere.
1449
-
1450
- Raises EmbeddingError, never a provider exception: the caller's whole
1451
- contract (SQ10) is to degrade to a documented fallback, and it cannot
1452
- do that against an exception type that differs per SDK.
1453
- """
1454
- items = [f"{prefix}{text}" for text in texts]
1455
- if not items:
1456
- return EmbeddingResult(model=model, provider_name=provider_name)
1457
-
1458
- if provider_name in PROVIDERS_WITHOUT_EMBEDDINGS:
1459
- raise EmbeddingError(
1460
- f"{provider_name} has no embeddings endpoint. Configure an "
1461
- f"embedder on a provider that does -- /embedder <PROVIDER> "
1462
- f"<model> -- or leave it unset to score similarity with the "
1463
- f"grounding model itself."
1464
- )
1465
-
1466
- try:
1467
- client = api_initialization(provider_name)
1468
- except ValueError as exc:
1469
- raise EmbeddingError(str(exc)) from exc
1470
-
1471
- try:
1472
- if provider_name == "GOOGLE":
1473
- vectors, tokens = _embed_google(client, model, items, task_type)
1474
- else:
1475
- vectors, tokens = _embed_openai_compatible(client, model, items)
1476
- except EmbeddingError:
1477
- raise
1478
- except Exception as exc:
1479
- raise EmbeddingError(
1480
- f"{provider_name} embeddings call failed for model {model!r}: "
1481
- f"{type(exc).__name__}: {exc}"
1482
- ) from exc
1483
-
1484
- _check_vectors(provider_name, model, vectors, len(items))
1485
- return EmbeddingResult(
1486
- vectors=vectors, model=model, provider_name=provider_name,
1487
- usage={"input_tokens": tokens},
1488
- )
1489
-
1490
-
1491
- def _embed_openai_compatible(client, model, items):
1492
- """`/v1/embeddings`, which is what every is_v1_compatible provider
1493
- exposes if it exposes embeddings at all.
1494
-
1495
- SORTED BY INDEX rather than trusted in arrival order. The response
1496
- carries an explicit `index` per item precisely because the order is
1497
- not guaranteed, and a silently permuted batch pairs every claim with
1498
- another claim's vector -- a wrong number with no symptom, which is the
1499
- failure this whole section exists to stop producing.
1500
- """
1501
- response = client.embeddings.create(model=model, input=items)
1502
- data = sorted(response.data, key=lambda item: getattr(item, "index", 0))
1503
- vectors = [list(item.embedding) for item in data]
1504
- usage = getattr(response, "usage", None)
1505
- return vectors, int(getattr(usage, "prompt_tokens", 0) or 0)
1506
-
1507
-
1508
- def _embed_google(client, model, items, task_type):
1509
- """google-genai's `embed_content`, which takes the batch as
1510
- `contents` and returns `embeddings[].values`.
1511
-
1512
- The config object is built ONLY when a task type was given, and
1513
- through getattr rather than a direct import of the types module: a
1514
- pinned SDK that does not carry EmbedContentConfig would otherwise turn
1515
- an optional tuning parameter into an import error on every Google
1516
- embedding call. D22's rule -- check the dependency's real shape, do
1517
- not assume it.
1518
- """
1519
- kwargs = {"model": model, "contents": items}
1520
- if task_type:
1521
- from google.genai import types as genai_types
1522
- config_cls = getattr(genai_types, "EmbedContentConfig", None)
1523
- if config_cls is not None:
1524
- kwargs["config"] = config_cls(task_type=task_type)
1525
- else:
1526
- logger.warning(
1527
- "Ignoring embedder task_type=%r: the installed google-genai "
1528
- "has no EmbedContentConfig.", task_type)
1529
-
1530
- response = client.models.embed_content(**kwargs)
1531
- vectors = [list(item.values) for item in (response.embeddings or [])]
1532
- # google-genai reports embedding token usage inconsistently across
1533
- # releases; absent is reported as zero rather than guessed at.
1534
- metadata = getattr(response, "metadata", None)
1535
- return vectors, int(getattr(metadata, "billable_character_count", 0) or 0)
1536
-
1537
-
1538
- def _check_vectors(provider_name, model, vectors, expected) -> None:
1539
- """Three ways a successful response is still unusable.
1540
-
1541
- All three produce a WRONG NUMBER rather than an error downstream: a
1542
- short batch pairs texts with the wrong vectors, a ragged batch makes
1543
- cosine compare different spaces, and an empty vector makes every
1544
- cosine zero -- which reads as "no source supports this claim" and is
1545
- indistinguishable from a real finding.
1546
- """
1547
- if len(vectors) != expected:
1548
- raise EmbeddingError(
1549
- f"{provider_name} returned {len(vectors)} embedding(s) for "
1550
- f"{expected} input(s) with model {model!r}.")
1551
- dimensions = {len(v) for v in vectors}
1552
- if len(dimensions) > 1:
1553
- raise EmbeddingError(
1554
- f"{provider_name} returned embeddings of differing dimensions "
1555
- f"{sorted(dimensions)} for model {model!r}.")
1556
- if dimensions == {0}:
1557
- raise EmbeddingError(
1558
- f"{provider_name} returned empty embeddings for model "
1559
- f"{model!r}.")
1
+ import base64
2
+ import binascii
3
+ import json
4
+ import logging
5
+ import math
6
+ import os
7
+ from dataclasses import dataclass, field
8
+ from typing import Optional
9
+ from uuid import UUID, uuid4
10
+
11
+ import config
12
+ import credentials
13
+ from credentials import (
14
+ load_provider_data,
15
+ no_providers_message,
16
+ unknown_provider_message,
17
+ )
18
+
19
+ # ROADMAP_v2 §33 W7 (#135). The three provider SDKs are NOT imported here.
20
+ #
21
+ # core.loop imports this module and main.py imports core.loop, so a module
22
+ # -scope `from openai import OpenAI` is paid by every invocation of either
23
+ # shell -- `--help`, `--summary`, a mistyped flag, the thread picker --
24
+ # before argparse runs. Measured on Windows: 5.6s to print --help, of
25
+ # which 3.5s was the three SDKs, and no run uses more than one of them.
26
+ #
27
+ # Each import therefore sits at the point of use, INSIDE the branch that
28
+ # needs it rather than at the top of the enclosing function: a
29
+ # GOOGLE-only name imported at the top of `_messages_for_provider` would
30
+ # be paid on every Anthropic turn, which is most of them, and would leave
31
+ # the defect in place while looking fixed.
32
+ #
33
+ # Deferred imports are otherwise not this file's idiom. The trade is
34
+ # stated here rather than left to be re-derived: `import` is cached after
35
+ # the first call, so the cost is a dict lookup per call on the hot path
36
+ # and seconds saved on every launch that never makes one.
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+ # Caches initialized clients so repeated calls for the same provider don't
41
+ # rebuild the client (and re-read the credentials file) every time.
42
+ _client_cache: dict[str, object] = {}
43
+
44
+
45
+ def api_initialization(provider_name: str):
46
+ if provider_name in _client_cache:
47
+ return _client_cache[provider_name]
48
+
49
+ provider_data = load_provider_data()
50
+
51
+ # #24. The file's absence and the provider's absence are different
52
+ # problems and now say so: the first names the path that was checked
53
+ # and its remedy, the second names what IS configured, like /model's
54
+ # refusal. Still ValueError either way -- callers (and tests) catch
55
+ # the type, not the text. The constant is read THROUGH the module,
56
+ # not imported: a from-import would freeze the value at this module's
57
+ # import time and a test's monkeypatch of credentials.LLM_PROVIDERS_FILE
58
+ # would not be seen here.
59
+ if not provider_data and not os.path.exists(
60
+ credentials.LLM_PROVIDERS_FILE):
61
+ raise ValueError(no_providers_message())
62
+ if provider_name not in provider_data:
63
+ raise ValueError(unknown_provider_message(provider_name, provider_data))
64
+
65
+ entry = provider_data[provider_name]
66
+
67
+ # ROADMAP_v3 §83. Routed by NAME, before the flag: the plan is not
68
+ # v1-compatible and must never fall to the Chat Completions branch.
69
+ if provider_name == "CHATGPT":
70
+ client = _chatgpt_client()
71
+ elif entry.get("is_v1_compatible", False):
72
+ from openai import OpenAI
73
+ client = OpenAI(base_url=entry["API_URL"], api_key=entry["API_KEY"])
74
+ elif provider_name == "GOOGLE":
75
+ from google import genai
76
+ client = genai.Client(api_key=entry["API_KEY"])
77
+ elif provider_name == "ANTHROPIC":
78
+ # Batch 234. Refused HERE, before a client exists, because the SDK
79
+ # no longer says what is wrong: 2.x sends the key as `Bearer <key>`,
80
+ # httpx2 refuses `Bearer ` as an illegal header before any request,
81
+ # and the SDK wraps that in APIConnectionError -- which
82
+ # provider_errors retries as a network blip. 0.116.0 refused the
83
+ # empty key itself, so no configuration that worked stops working.
84
+ # Nothing is cached, so adding the key takes effect on the next call.
85
+ if not entry.get("API_KEY"):
86
+ raise ValueError(credentials.empty_key_refusal(provider_name))
87
+ from anthropic import Anthropic
88
+ client = Anthropic(api_key=entry["API_KEY"])
89
+ # Add further proprietary API formats here
90
+ else:
91
+ raise ValueError(f"Provider {provider_name} is not currently supported")
92
+
93
+ _client_cache[provider_name] = client
94
+ return client
95
+
96
+
97
+ def _chatgpt_client():
98
+ """The openai SDK, set up for the ChatGPT plan (ROADMAP_v3 §83, CG21).
99
+
100
+ `api_key` is a FUNCTION, `chatgpt_auth.access_token`: the SDK calls it
101
+ before every request (measured 25 of 25 in slice 2a), so the hourly
102
+ refresh needs no other plumbing and a cached client never holds a
103
+ stale token. `max_retries=0`, so CG10 decides every retry and the SDK
104
+ decides none: its own would resend a usage-limit 429.
105
+
106
+ The address is `chatgpt_auth.RESOURCE` and never the entry's `API_URL`.
107
+ The token is minted for that resource alone, and a hand-edited entry
108
+ must not be able to send it anywhere else.
109
+
110
+ Refused on a hosted deployment (CG1), as the sign-in already is, so a
111
+ `providers.json` carried onto one cannot reach the plan either.
112
+ """
113
+ from security import hosted
114
+
115
+ if hosted.is_hosted():
116
+ raise ValueError(
117
+ "The ChatGPT plan answers on a local install only (ROADMAP_v3 "
118
+ "§83, CG1): OpenAI offers it to open-source apps running on your "
119
+ "own machine.")
120
+ from openai import OpenAI
121
+
122
+ from core import chatgpt_auth
123
+
124
+ return OpenAI(base_url=chatgpt_auth.RESOURCE,
125
+ api_key=chatgpt_auth.access_token, max_retries=0)
126
+
127
+
128
+ def forget_client(provider_name: str) -> None:
129
+ """Drop the cached client for `provider_name`, so the next call builds a
130
+ new one from what `providers.json` (or the session) says NOW.
131
+
132
+ `/connect` is the caller (ROADMAP_v3 §79, HD5): the cache above is keyed
133
+ by provider name for the life of the process, so a key added or replaced
134
+ mid-session was otherwise ignored until a restart, with every call still
135
+ going out under the old one.
136
+ """
137
+ _client_cache.pop(provider_name, None)
138
+
139
+
140
+ def accepts_images(provider_name: str) -> bool:
141
+ """ROADMAP_v3 §81 (IM4). Whether an image in a tool result is DELIVERED
142
+ to this provider, as opposed to replaced by a note saying it was not.
143
+
144
+ Opt-in per provider through `accepts_images` in providers.json, on
145
+ `echoes_reasoning`'s terms: whether a provider takes an image depends on
146
+ the endpoint and often the model, cannot be discovered, and must not be
147
+ guessed, so it lives beside the endpoint and defaults to the
148
+ conservative answer. The test is `is True`, never truthiness:
149
+ `bool("false")` is True, and a quoted flag is a hand edit away (A29).
150
+
151
+ GOOGLE is honoured like the others since batch 173 (IM9). Until then it
152
+ was never delivered to and a flag on it was warned about: the old pin's
153
+ FunctionResponse had no field an image could go in, and the wire that
154
+ does work -- a harness turn after the batch -- had not been measured.
155
+ """
156
+ entry = load_provider_data().get(provider_name, {})
157
+ return isinstance(entry, dict) and entry.get("accepts_images") is True
158
+
159
+
160
+ # ============================================================================
161
+ # ---- Normalized response shape ---------------------------------------------
162
+ # ============================================================================
163
+
164
+ @dataclass
165
+ class ToolCallRequest:
166
+ id: str
167
+ name: str
168
+ input: dict
169
+ # §33 W2 (#37). Set when the provider's `arguments` string could not
170
+ # be read as a JSON object -- most often because the response was cut
171
+ # off mid-arguments by the token limit. TRANSPORT ONLY: it describes
172
+ # one wire read, not the thread, so `add_assistant_message` persists
173
+ # {id, name, input} exactly as before and this never reaches storage.
174
+ #
175
+ # The call is still constructed rather than dropped. The model made a
176
+ # call and is owed an answer about it; a silently missing tool_result
177
+ # is M4's pairing defect, and `input={}` with no error would run the
178
+ # tool with arguments nobody sent.
179
+ parse_error: Optional[str] = None
180
+
181
+
182
+ @dataclass
183
+ class ModelResponse:
184
+ text: str
185
+ tool_calls: list[ToolCallRequest] = field(default_factory=list)
186
+ usage: dict = field(default_factory=lambda: {"input_tokens": 0, "output_tokens": 0})
187
+ stop_reason: str = "complete" # set by RunAgentLoop._run(), not here -- see core/loop.py
188
+ thread_id: Optional[UUID] = None # set by the entry points (stream_deep_research_mode,
189
+ # continue_conversation) so callers can persist/retry
190
+ # against the same thread. call_model() itself NEVER
191
+ # sets this -- it has no thread concept.
192
+ # §25: calls that proceeded on a PRE-FLIGHT grant rather than a live
193
+ # approval. Set by _run() (like stop_reason), never by call_model().
194
+ #
195
+ # Authorization moved up-front, so accountability moves after: this is
196
+ # the record of what a single launch-time yes actually authorised,
197
+ # written into the run artifacts for a pipeline nobody was watching.
198
+ # Empty for every run that granted nothing, which is every run today.
199
+ granted_calls: list = field(default_factory=list)
200
+ # ROADMAP_v2 §21: compaction notices raised during this run, each a
201
+ # {"kind", "text"} dict. Set by _run() like stop_reason and
202
+ # granted_calls, never by call_model().
203
+ #
204
+ # Carried here as well as yielded as a LoopEvent because
205
+ # run_to_completion() discards non-final events: the TUI watches the
206
+ # generator, but the CLI and the pipeline drain it, so a notice with
207
+ # only the event route would be invisible in two shells out of three.
208
+ notices: list = field(default_factory=list)
209
+ # #4 (batch 27): the two per-turn figures the loop computes, set by
210
+ # _run() like stop_reason -- never by call_model(), which has no turn
211
+ # concept. UNPRICED APPROXIMATIONS, deliberately: raw provider counts,
212
+ # no cache-read/write pricing and no currency anywhere. Precise spend
213
+ # lives in the provider's dashboard; these exist for RELATIVE reasoning
214
+ # ("is this turn ballooning the context?"), not billing truth.
215
+ #
216
+ # turn_billed_tokens: cumulative input+output over this user-turn so
217
+ # far -- the spend meter's running total (the prompt is re-sent every
218
+ # step, so this grows quadratically in a tool-using turn, which is
219
+ # correct: that is what the provider bills).
220
+ # turn_new_tokens: what THIS TURN added to the thread -- output plus
221
+ # positive input deltas, the first call's inherited prompt excluded
222
+ # and mid-turn compaction shrinks clamped away. This is the figure
223
+ # anything reasoning about SIZE reads; the spend meter must never be
224
+ # read that way again (TECHNICAL_DEBT item 9, closed batch 27).
225
+ # turn_output_tokens: what the MODEL WROTE this turn -- output tokens
226
+ # and nothing else, summed across every step. Batch 61, and it is a
227
+ # THIRD instrument rather than a convenience: the two above are a
228
+ # SPEND meter and a SIZE meter, and a generation RATE can be derived
229
+ # from neither. turn_billed_tokens counts the prompt again on every
230
+ # step; turn_new_tokens adds the positive input deltas, so a
231
+ # tool-using turn's tool results land in it and it overstates what was
232
+ # generated. Dividing either by a duration produces a number that
233
+ # looks like tok/s and is not, which is exactly the misreading
234
+ # TECHNICAL_DEBT item 9 was closed for.
235
+ turn_billed_tokens: Optional[int] = None
236
+ turn_new_tokens: Optional[int] = None
237
+ turn_output_tokens: Optional[int] = None
238
+ # Batch 44 (§44). The turn's reasoning, as the PROVIDER'S OWN BLOCKS
239
+ # rather than as the text §38 streams for display:
240
+ #
241
+ # {"provider": ..., "model": ..., "blocks": [ ...native... ]}
242
+ #
243
+ # §38's O1 made thinking display-only -- never persisted, never back
244
+ # on the wire -- and sidestepped "does a provider need its own
245
+ # thinking returned next turn?" by never returning it. That answer
246
+ # stopped being free once it was clear the model had never seen its
247
+ # own reasoning at ALL: not across a restart, and not between two
248
+ # turns of one live session, so a turn re-derives what it already
249
+ # worked out. O1 is amended here.
250
+ #
251
+ # BLOCKS, NOT THE STREAMED TEXT, and that is the whole reason this is
252
+ # a field rather than an accumulation in core/loop.py. An Anthropic
253
+ # thinking block carries a `signature`; the model reuses its own state
254
+ # through the block, not through the prose, so a re-serialised copy of
255
+ # the deltas would be unsigned and rejected. The blocks are read off
256
+ # get_final_message(), which already has them in hand.
257
+ #
258
+ # `provider` and `model` ride along because the replay rule is
259
+ # per-model: blocks go back UNCHANGED to the model that produced them
260
+ # and are dropped for anything else.
261
+ thinking: Optional[dict] = None
262
+
263
+
264
+ def _tool_arguments(raw_args: str, tool_name: str,
265
+ finish_reason: Optional[str] = None) -> tuple:
266
+ """(input, parse_error) for one provider `arguments` string.
267
+
268
+ The ONLY place a wire string is parsed as JSON. Google and Anthropic
269
+ hand back dicts, so this is the OpenAI-compatible branch's -- which is
270
+ the branch a local model server takes, and truncated or malformed tool
271
+ arguments are likeliest there -- and, since ROADMAP_v3 §83, CHATGPT's,
272
+ whose Responses function calls carry `arguments` as a string too.
273
+
274
+ §33 W1 (#37): a failure is RETURNED, not raised. `dispatch()` turning
275
+ handler exceptions into {"error": ...} is the whole reason a raising
276
+ TOOL cannot kill a run; nothing played that role for a raising
277
+ TRANSLATION one layer up, so a response cut mid-arguments took a
278
+ JSONDecodeError out of this generator, out of _run(), and into the
279
+ pipeline's `except Exception` -- recording status='failed' on a
280
+ finished ten-pass run.
281
+
282
+ §33 W4: `finish_reason` is what separates "the provider emitted bad
283
+ JSON" from "the answer was cut off", which is the likeliest cause by
284
+ far and the only one the model can act on.
285
+ """
286
+ # W9: no arguments is not an error. `get_time` declares properties=[]
287
+ # and `pin` has no required parameters, so this is a live path -- and
288
+ # json.loads("") raises. Dropping this fallback was green on the whole
289
+ # suite when audit unit 3 ran mutation P10.
290
+ if not raw_args:
291
+ return {}, None
292
+
293
+ try:
294
+ parsed = json.loads(raw_args)
295
+ except json.JSONDecodeError as exc:
296
+ if finish_reason == "length":
297
+ return {}, (
298
+ f"The arguments for {tool_name} were cut off by the response "
299
+ f"token limit, so the call could not be made. Reissue it with "
300
+ f"shorter arguments."
301
+ )
302
+ return {}, (
303
+ f"The arguments for {tool_name} were not valid JSON ({exc.msg}), "
304
+ f"so the call could not be made. Reissue it with valid JSON "
305
+ f"arguments."
306
+ )
307
+
308
+ # Valid JSON that is not an object -- "null", "[1,2]", "3". Rarer than
309
+ # a truncation and caught in the same place because the consequence is
310
+ # the same: dispatch() would be handed something that is not params.
311
+ if not isinstance(parsed, dict):
312
+ return {}, (
313
+ f"The arguments for {tool_name} parsed as "
314
+ f"{type(parsed).__name__}, not a JSON object, so the call could "
315
+ f"not be made. Reissue it with a JSON object."
316
+ )
317
+
318
+ return parsed, None
319
+
320
+
321
+ @dataclass
322
+ class StreamToken:
323
+ """One token-level event yielded by call_model_stream(). Exactly one
324
+ field is populated per yield: text_delta for incremental text,
325
+ thinking_delta for incremental REASONING text, or final_response for
326
+ the terminal ModelResponse (with accumulated tool calls and usage).
327
+
328
+ §38 O1: thinking is DISPLAY-ONLY. It never joins the accumulated
329
+ `text`, is never persisted, and is never sent back on the wire -- so
330
+ the ModelResponse each branch produces is byte-identical to what it
331
+ produced before thinking was captured, and D20's persisted turn and
332
+ M4's fold boundary keep exactly the bytes they have today.
333
+
334
+ Which providers actually populate it (§38 O2): Anthropic, and every
335
+ OpenAI-compatible provider that streams `reasoning_content` or
336
+ `reasoning` (DeepSeek, Qwen, Z.AI, OpenRouter). It stays empty on
337
+ OPENAI -- its Chat Completions endpoint returns no reasoning text at
338
+ all -- and on GOOGLE, whose request deliberately does not ask for
339
+ thought summaries. Absence is not a bug there; see O2.
340
+ """
341
+ text_delta: Optional[str] = None
342
+ thinking_delta: Optional[str] = None
343
+ final_response: Optional[ModelResponse] = None
344
+
345
+
346
+ # ============================================================================
347
+ # ---- Token usage, which every branch reports and no branch can trust -------
348
+ # ============================================================================
349
+
350
+ def _token_count(usage_obj, field: str) -> Optional[int]:
351
+ """One token count off a provider's usage object, or None for "this
352
+ provider did not report that number".
353
+
354
+ `_record_window`'s rule applied to the other nullable figure these SDKs
355
+ carry -- "present" is not "usable". A bool is an int in Python and is
356
+ not a token count; a negative count is not one either.
357
+
358
+ WHY THIS IS NOT A `getattr(obj, field, 0)` DEFAULT, which is the
359
+ softened form D21's own note forbids: the attribute EXISTS on all three
360
+ pinned SDKs and holds None, so the default never fires and the None
361
+ travels into `core/loop.py`'s `usage_in + usage_out`. Measured per SDK
362
+ (batch 147), because the three reasons are different and only one of
363
+ them is visible in a type annotation. test_sdk_conformance.py holds each
364
+ on the pin; the versions below are batch 234's:
365
+
366
+ google-genai 2.32.0 every field of (as on 1.0.0 before it)
367
+ GenerateContentResponseUsageMetadata is
368
+ Optional[int] = None, and a bare instance is
369
+ TRUTHY -- so `if usage_meta:` passes and then
370
+ every read is None.
371
+ anthropic 2.1.0 Usage.input_tokens and CompletionUsage.
372
+ openai 3.36.0 prompt_tokens are annotated `int` and REQUIRED,
373
+ which says what the server promises rather than
374
+ what the object holds: both SDKs parse wire JSON
375
+ through pydantic's construct(), which skips
376
+ validation. `construct_type({"output_tokens":
377
+ 7}, Usage)` yields input_tokens=None, and
378
+ anthropic's own stream accumulator guards
379
+ `input_tokens` with `is not None` against that
380
+ same `int` annotation -- while assigning
381
+ `output_tokens` unconditionally.
382
+
383
+ So an `int` annotation is not a runtime guarantee anywhere here, which
384
+ is why ONE reader serves all three branches rather than the Google one
385
+ that the defect was found in.
386
+ """
387
+ if usage_obj is None:
388
+ return None
389
+ value = getattr(usage_obj, field, None)
390
+ if isinstance(value, bool) or not isinstance(value, int):
391
+ return None
392
+ return value if value >= 0 else None
393
+
394
+
395
+ def _stream_usage(provider_name: str, counts: dict,
396
+ supports_stream_usage: bool) -> dict:
397
+ """D21's usage-or-raise for all three streaming branches, and the one
398
+ place that turns "not reported" into a number.
399
+
400
+ RETURNS A TOTAL SHAPE: both values are ints, always. That is what makes
401
+ a belt in `core/loop.py` unnecessary rather than merely unfashionable --
402
+ the producer is where this belongs (AGENTS.md), and a consumer-side
403
+ guard would leave the next consumer to write its own.
404
+
405
+ D21 says a stream must not silently degrade token accounting, and the
406
+ guard that enforced it compared `input == 0 and output == 0`. A
407
+ PARTIAL report defeats that comparison without reporting anything
408
+ usable: `None != 0`, and once coerced, an unreported output count is
409
+ indistinguishable from a genuine zero. §64's A20 widens the rule to
410
+ match what D21 says rather than what it happened to compare: under the
411
+ flag, a count that is not a number raises, because the flag is the
412
+ per-provider statement that this provider DOES report usage and a
413
+ missing number is that promise broken.
414
+
415
+ Two messages, deliberately. "Completed without usage data" is kept
416
+ verbatim for the case it has always named -- nothing reported at all,
417
+ or an explicit zero for both -- so the existing guards keep their
418
+ meaning. The partial case gets its own line naming which count is
419
+ missing, because that is the one a reader cannot diagnose from the
420
+ other.
421
+
422
+ With the flag FALSE the coercion is all that happens, and 0 is the
423
+ right answer there: the flag's whole purpose is to let a provider that
424
+ genuinely omits usage run anyway.
425
+ """
426
+ reported_in = counts["input_tokens"]
427
+ reported_out = counts["output_tokens"]
428
+ if supports_stream_usage:
429
+ if (reported_in is None and reported_out is None) or (
430
+ reported_in == 0 and reported_out == 0):
431
+ raise RuntimeError(
432
+ f"Streaming call to {provider_name} completed without usage "
433
+ f"data despite supports_stream_usage=True. The stream may "
434
+ f"have been interrupted before the final usage chunk."
435
+ )
436
+ missing = [name for name, value in
437
+ (("input_tokens", reported_in),
438
+ ("output_tokens", reported_out)) if value is None]
439
+ if missing:
440
+ raise RuntimeError(
441
+ f"Streaming call to {provider_name} reported "
442
+ f"{' and '.join(missing)} as absent or not a number despite "
443
+ f"supports_stream_usage=True, so this step's token "
444
+ f"accounting would be short by it."
445
+ )
446
+ return {"input_tokens": reported_in or 0,
447
+ "output_tokens": reported_out or 0}
448
+
449
+
450
+ # ============================================================================
451
+ # ---- Tool schema translation ------------------------------------------------
452
+ # ============================================================================
453
+
454
+ #: ROADMAP_v3 §82 (GS4). The `Schema` fields the Gemini API is known to take:
455
+ #: the 22 google-genai 1.0.0 had, which batch 132 and §9 verified on the
456
+ #: wire. The SDK serves Vertex AI as well, and 2.29.0 added three fields for
457
+ #: it -- `additional_properties`, which the Gemini API refused when measured
458
+ #: in batch 172 (400, `Unknown name "additional_properties"`), `defs` and
459
+ #: `ref`. One refused key fails every GOOGLE call, because the declarations
460
+ #: travel together, so a new SDK field waits to be measured.
461
+ _GOOGLE_SCHEMA_VERIFIED = frozenset({
462
+ "any_of", "default", "description", "enum", "example", "format",
463
+ "items", "max_items", "max_length", "max_properties", "maximum",
464
+ "min_items", "min_length", "min_properties", "minimum",
465
+ "nullable", "pattern", "properties", "property_ordering",
466
+ "required", "title", "type",
467
+ })
468
+
469
+
470
+ def _google_schema_keys(genai_types) -> set:
471
+ """Every key the pinned `types.Schema` will accept AND the Gemini API is
472
+ known to take, read off the SDK.
473
+
474
+ Field names plus their camelCase aliases, because `Schema` sets
475
+ `populate_by_name` and JSON Schema spells things `anyOf`/`maxItems`
476
+ while the model declares `any_of`/`max_items`. Read off the SDK so that
477
+ a field the installed version lacks is never sent -- and read at CALL
478
+ time, not import time, because the root `conftest.py` puts a fake
479
+ `google.genai` in `sys.modules` before collection and an import-time
480
+ constant would bind the fake's fields for the whole test session.
481
+
482
+ It used to take EVERY field, on the reasoning that a version which adds
483
+ one should carry it with no change here. The 2.29.0 pin disproved that
484
+ (§82): a field on the type is not a field the Gemini API accepts. So the
485
+ SDK's set is narrowed to `_GOOGLE_SCHEMA_VERIFIED`.
486
+ """
487
+ keys = set()
488
+ # NOT `field`: this module imports dataclasses.field at the top, and
489
+ # shadowing it here is what ruff F402 flagged in batch 141 -- found only
490
+ # then, because the lint job is not on main and so has never run.
491
+ for name, model_field in genai_types.Schema.model_fields.items():
492
+ if name not in _GOOGLE_SCHEMA_VERIFIED:
493
+ continue
494
+ keys.add(name)
495
+ alias = getattr(model_field, "alias", None)
496
+ if alias:
497
+ keys.add(alias)
498
+ return keys
499
+
500
+
501
+ def _reduce_for_google(node, accepted: set):
502
+ """JSON Schema -> what the pinned `types.Schema` can actually carry.
503
+
504
+ `Schema.model_config` is `extra="forbid"`, so a key it has no field for
505
+ is a `ValidationError` rather than something ignored. The translation
506
+ used to hand `input_schema` over untouched, and because it is one list
507
+ comprehension over every schema, ONE refusal took the whole advertised
508
+ set with it: no model call on GOOGLE could be built at all. This
509
+ repository's own `probability_stats` was the entry that did it --
510
+ pydantic renders its `Optional[dict[str, float]]` as
511
+ `{"anyOf": [{"additionalProperties": {...}, "type": "object"},
512
+ {"type": "null"}]}`, and `additionalProperties` is not a field.
513
+
514
+ THE REDUCTION IS HERE AND NOT IN THE TOOL, because the schemas are
515
+ generated by `model_json_schema()`: fixing the one tool leaves the next
516
+ `Optional[dict]` to find this again, which is the shape D24 settled for
517
+ permissions. Two rules:
518
+
519
+ * drop any key `Schema` has no field or alias for;
520
+ * flatten `anyOf: [X, {"type": "null"}]` to X plus `nullable`, which
521
+ is how this SDK spells an optional value. Dropping the null member
522
+ is not cosmetic -- the pinned SDK coerces `{"type": "null"}` with a
523
+ `UserWarning: null is not a valid Type` and carries on, so without
524
+ the flattening a nullable field reaches the wire describing a type
525
+ that does not exist.
526
+
527
+ `docs/ARCHITECTURE.md` 4.7 said the raw dict "auto-converts to
528
+ `types.Schema`". It does not; it validates, and refuses.
529
+
530
+ Since batch 172 (§82) the pin's `Schema` HAS `additional_properties`
531
+ (2.29.0 then, 2.32.0 since batch 234, the same 25 fields) -- and the
532
+ Gemini API refuses it, so it is still dropped: `accepted` is the
533
+ verified set, not the SDK's.
534
+ """
535
+ if isinstance(node, list):
536
+ return [_reduce_for_google(item, accepted) for item in node]
537
+ if not isinstance(node, dict):
538
+ return node
539
+
540
+ members = node.get("anyOf")
541
+ if isinstance(members, list):
542
+ live = [m for m in members
543
+ if not (isinstance(m, dict) and m.get("type") == "null")]
544
+ nullable = len(live) != len(members)
545
+ siblings = {k: v for k, v in node.items() if k != "anyOf"}
546
+ if len(live) == 1:
547
+ # The Optional[X] case: X itself, carrying anything that sat
548
+ # beside the union (a description, a default) and the flag.
549
+ merged = dict(_reduce_for_google(live[0], accepted))
550
+ merged.update(_reduce_for_google(siblings, accepted))
551
+ if nullable:
552
+ merged["nullable"] = True
553
+ return merged
554
+ out = _reduce_for_google(siblings, accepted)
555
+ out["anyOf"] = [_reduce_for_google(m, accepted) for m in live]
556
+ if nullable:
557
+ out["nullable"] = True
558
+ return out
559
+
560
+ out = {}
561
+ for key, value in node.items():
562
+ if key not in accepted:
563
+ continue
564
+ if key == "properties" and isinstance(value, dict):
565
+ out[key] = {name: _reduce_for_google(sub, accepted)
566
+ for name, sub in value.items()}
567
+ elif key in ("items", "anyOf"):
568
+ out[key] = _reduce_for_google(value, accepted)
569
+ else:
570
+ out[key] = value
571
+ return out
572
+
573
+
574
+ def _tools_for_provider(provider_name: str, tool_schemas: list[dict]):
575
+ """
576
+ tool_schemas arrive in Anthropic's native shape (name/description/
577
+ input_schema), since that's what every tool's TOOL_SCHEMA already
578
+ produces. Translate into whatever shape the target provider expects.
579
+ """
580
+ if not tool_schemas:
581
+ return None
582
+
583
+ if provider_name == "ANTHROPIC":
584
+ return tool_schemas
585
+
586
+ if provider_name == "GOOGLE":
587
+ from google.genai import types as genai_types
588
+ accepted = _google_schema_keys(genai_types)
589
+ return [genai_types.Tool(
590
+ function_declarations=[
591
+ genai_types.FunctionDeclaration(
592
+ name=s["name"],
593
+ description=s["description"],
594
+ parameters=_reduce_for_google(s["input_schema"], accepted),
595
+ )
596
+ for s in tool_schemas
597
+ ]
598
+ )]
599
+
600
+ if provider_name == "CHATGPT":
601
+ # ROADMAP_v3 §83. The Responses API's FLAT function shape, and no
602
+ # `strict`. Slice 2a measured it: the registry's fifteen schemas,
603
+ # none of which meets strict mode's rules, completed a call without
604
+ # the key -- and cost fewer input tokens than with `strict: false`.
605
+ # Never a hosted tool (CG3): only what the harness itself runs.
606
+ return [
607
+ {
608
+ "type": "function",
609
+ "name": s["name"],
610
+ "description": s["description"],
611
+ "parameters": s["input_schema"],
612
+ }
613
+ for s in tool_schemas
614
+ ]
615
+
616
+ # OpenAI-compatible providers
617
+ return [
618
+ {
619
+ "type": "function",
620
+ "function": {
621
+ "name": s["name"],
622
+ "description": s["description"],
623
+ "parameters": s["input_schema"],
624
+ },
625
+ }
626
+ for s in tool_schemas
627
+ ]
628
+
629
+
630
+ # ============================================================================
631
+ # ---- Message history translation -------------------------------------------
632
+ # ============================================================================
633
+ # core/memory.py stores history in a provider-neutral shape (see that
634
+ # file's docstring). This is the counterpart to _tools_for_provider above,
635
+ # applied to conversation history instead of tool schemas -- the ONLY
636
+ # place either provider's specific message wire format should exist.
637
+
638
+ def _is_tool_result_message(msg: dict) -> bool:
639
+ return isinstance(msg.get("content"), list) and all(
640
+ isinstance(b, dict) and b.get("type") == "tool_result" for b in msg["content"]
641
+ )
642
+
643
+
644
+ def _is_empty_assistant_turn(msg: dict) -> bool:
645
+ """An assistant turn carrying neither text nor tool calls (#13, #36).
646
+
647
+ Produced when the model returns nothing at all -- a safety filter, a
648
+ truncation, an empty pass response. `core/loop.py` persists it because
649
+ D20 requires the assistant turn to be written before any stop-condition
650
+ branching, so it reaches translation on every resume of that thread.
651
+
652
+ It is meaningless on every provider, and each branch used to mangle it
653
+ differently from the same neutral input:
654
+
655
+ OPENAI: {"role": "assistant", "content": null} <- #13
656
+ ANTHROPIC: {"role": "assistant", "content": []} <- #36
657
+ GOOGLE: skipped entirely <- guarded
658
+
659
+ Only Google was guarded, and only because Google was the provider being
660
+ debugged when it surfaced. Dropping it above the branch split is
661
+ AGENTS.md's *fix at the producer, not the consumer*: all three branches
662
+ become correct at once, and so does the next one.
663
+
664
+ Requiring BOTH halves to be empty is load-bearing. An empty text WITH
665
+ tool calls is legitimate on the OpenAI schema -- a tool-call-only turn
666
+ -- and `test_messages_openai_assistant_with_null_text` covers it, so a
667
+ guard keyed on text alone breaks a valid case.
668
+ """
669
+ return (msg.get("role") == "assistant"
670
+ and not msg.get("text")
671
+ and not msg.get("tool_calls"))
672
+
673
+
674
+ def _echoed_blocks(provider_name: str, model: Optional[str],
675
+ msg: dict) -> list:
676
+ """This turn's stored thinking blocks, if they may go back (§44).
677
+
678
+ THE GATE IS THE PAIR, and it is the whole safety argument. A stored
679
+ record names the provider and model that produced it; blocks go back
680
+ UNCHANGED to that model and to nothing else. An Anthropic block carries
681
+ a signature the model verifies against its own state, so handing it to
682
+ a different model is at best ignored and at worst a 400 -- and after a
683
+ /model switch the thread is full of blocks the new model never wrote.
684
+ Dropping them is always safe: the harness then does exactly what it did
685
+ before this batch.
686
+
687
+ Empty for every message written before §44, which is what keeps the
688
+ translation byte-identical for every existing thread.
689
+ """
690
+ record = msg.get("thinking")
691
+ if not isinstance(record, dict) or not model:
692
+ return []
693
+ if record.get("provider") != provider_name or record.get("model") != model:
694
+ return []
695
+ return [b for b in record.get("blocks") or [] if isinstance(b, dict)]
696
+
697
+
698
+ def _chatgpt_reasoning(model: Optional[str], msg: dict) -> list:
699
+ """The reasoning items a CHATGPT turn goes back with (ROADMAP_v3 §83,
700
+ CG18, CG23): exactly as the SDK parsed them, `None` fields left out,
701
+ and only to the model that wrote them -- §44's pair, through
702
+ `_echoed_blocks`.
703
+
704
+ EVERY turn this model wrote, the ones that ended in calls included
705
+ (CG23, the owner's choice). Slice 2a measured the item accepted under
706
+ `store: false`, with its id and without, before a user message; inside a
707
+ tool loop it was never sent, because the model did not reason before a
708
+ trivial call. The item type is the same and so is the list it sits in,
709
+ and the tool loop is where a reasoning model most needs what it already
710
+ worked out. A refusal would fail that step with a 400 naming the input,
711
+ which is the owner's live check to see."""
712
+ return [b for b in _echoed_blocks("CHATGPT", model, msg)
713
+ if b.get("type") == "reasoning"]
714
+
715
+
716
+ #: ROADMAP_v3 §82 (GS3). Google's stand-in for a thought signature, for a
717
+ #: function call the target model did not write. Gemini 3 refuses a request
718
+ #: whose current turn holds an unsigned call, and a thread that switched
719
+ #: provider or model mid-turn has exactly that. Measured accepted on
720
+ #: gemini-3.1-flash-lite (batch 172); a real signature is always preferred.
721
+ _GOOGLE_FOREIGN_SIGNATURE = b"skip_thought_signature_validator"
722
+
723
+
724
+ def _google_signature_block(call_id: str, signature: Optional[bytes]) -> dict:
725
+ """One function call's thought signature, as §44's record holds it
726
+ (§82, GS2). One block per call, INCLUDING a call that carried none --
727
+ Gemini 3 signs only the first of a parallel batch, and a model that
728
+ does not think signs nothing -- so "this model wrote the turn and
729
+ attached nothing" stays distinguishable from "nothing is known". Base64
730
+ in the record, because the record is JSON; and no `text` or `thinking`
731
+ key, so replay renders nothing for it."""
732
+ return {"type": "thought_signature", "call_id": call_id,
733
+ "signature": (base64.b64encode(signature).decode("ascii")
734
+ if signature else None)}
735
+
736
+
737
+ def _google_signatures(model: Optional[str], msg: dict) -> Optional[dict]:
738
+ """{call_id: signature bytes or None} for a turn THIS model wrote, or
739
+ None when it wrote nothing here (§82, GS2/GS3).
740
+
741
+ The gate is §44's pair, read through `_echoed_blocks`: a signature goes
742
+ back unchanged to the model that produced it and to nothing else. A
743
+ stored value that will not decode costs that call its signature and
744
+ gets the placeholder instead, `_decode_thinking`'s rule: an unreadable
745
+ entry costs the entry, never the request."""
746
+ blocks = [b for b in _echoed_blocks("GOOGLE", model, msg)
747
+ if b.get("type") == "thought_signature"]
748
+ if not blocks:
749
+ return None
750
+ signatures: dict = {}
751
+ for block in blocks:
752
+ value = block.get("signature")
753
+ if value is None:
754
+ signatures[block.get("call_id")] = None
755
+ continue
756
+ try:
757
+ signatures[block.get("call_id")] = base64.b64decode(
758
+ value, validate=True)
759
+ except (binascii.Error, TypeError, ValueError):
760
+ signatures[block.get("call_id")] = _GOOGLE_FOREIGN_SIGNATURE
761
+ return signatures
762
+
763
+
764
+ #: ROADMAP_v3 §81 (IM10). The image types GOOGLE is sent: Gemini's documented
765
+ #: list (PNG, JPEG, WEBP, HEIC, HEIF) met with what `view_image` attaches.
766
+ #: GIF is left out, the owner's choice. Two Gemini 3 models read one correctly
767
+ #: when measured, but it is not documented, and an image the endpoint refused
768
+ #: would stay in the thread and fail every request after it.
769
+ _GOOGLE_IMAGE_TYPES = frozenset({"image/png", "image/jpeg", "image/webp"})
770
+
771
+ #: What a tool message says on the two wires that deliver images after the
772
+ #: batch, so the model meets the images knowing whose they are (IM4, IM9).
773
+ _IMAGES_FOLLOW = ("[The attached image(s) follow these tool results, in a "
774
+ "harness message.]")
775
+
776
+
777
+ def _image_note(images: list,
778
+ reason: str = "this provider is not set up to receive images"
779
+ ) -> str:
780
+ """What a tool result's images become on a wire that does not receive
781
+ them (ROADMAP_v3 §81, IM5): a sentence saying so, never the bytes and
782
+ never silence. One rule for every way to get here -- a provider not
783
+ marked `accepts_images`, a thread that switched to one after the image
784
+ was attached, and since batch 173 an image GOOGLE is not sent (IM10). A
785
+ model told nothing would answer from a result that reads as complete,
786
+ which is A32's lesson about MCP's placeholder."""
787
+ kinds = ", ".join(sorted({image["media_type"] for image in images}))
788
+ return (f"[{len(images)} image(s) attached to this result ({kinds}) were "
789
+ f"not sent: {reason}.]")
790
+
791
+
792
+ def _with_image_note(msg: dict) -> str:
793
+ """A tool row's text, with the IM5 note appended when it carries images
794
+ this wire will not receive."""
795
+ images = msg.get("images")
796
+ if not images:
797
+ return msg["content"]
798
+ return f"{msg['content']}\n{_image_note(images)}"
799
+
800
+
801
+ def _openai_image_turn(pending: list) -> dict:
802
+ """The user-role message that carries a tool batch's images on the
803
+ OpenAI-compatible wire (IM4).
804
+
805
+ A tool message there holds TEXT PARTS ONLY -- the installed SDK types its
806
+ content as text parts, and the API rejects an image part in it -- so an
807
+ image a tool returned can only travel in a user message. It goes AFTER
808
+ the whole batch: every tool message must directly follow the assistant
809
+ turn that called it, so one placed between two of them would break the
810
+ pairing. Built here and never persisted, like the compaction summary
811
+ (M8): the archive keeps the tool row with its images, and each request
812
+ derives this message from it again. It says it is the harness speaking,
813
+ so the model does not read the images as something the user sent.
814
+ """
815
+ parts: list = []
816
+ for tool_call_id, images in pending:
817
+ parts.append({"type": "text", "text": (
818
+ f"[Harness: the image(s) attached to the result of tool call "
819
+ f"{tool_call_id}. A tool message on this API carries text only, "
820
+ f"so they are delivered here.]")})
821
+ for image in images:
822
+ parts.append({"type": "image_url", "image_url": {
823
+ "url": f"data:{image['media_type']};base64,{image['data']}"}})
824
+ return {"role": "user", "content": parts}
825
+
826
+
827
+ def _google_tool_images(msg: dict, images: bool) -> tuple:
828
+ """(result text, [(media_type, bytes)]) for one tool row on GOOGLE
829
+ (ROADMAP_v3 §81, IM9/IM10).
830
+
831
+ The bytes go out DECODED: `Blob.data` is bytes on the pinned type, and
832
+ a base64 string handed to it would be sent as the text of the base64.
833
+ Each image that is not sent says why in the result: the provider is not
834
+ marked (IM5), the type is not one Google is sent (IM10), or the stored
835
+ copy will not decode -- `_decode_thinking`'s rule, so one unreadable
836
+ image costs that image, never the request."""
837
+ attached = msg.get("images") or []
838
+ if not attached:
839
+ return msg["content"], []
840
+ if not images:
841
+ return _with_image_note(msg), []
842
+ sent, refused, unreadable = [], [], []
843
+ for image in attached:
844
+ if image["media_type"] not in _GOOGLE_IMAGE_TYPES:
845
+ refused.append(image)
846
+ continue
847
+ try:
848
+ sent.append((image["media_type"],
849
+ base64.b64decode(image["data"], validate=True)))
850
+ except (binascii.Error, TypeError, ValueError):
851
+ unreadable.append(image)
852
+ text = msg["content"]
853
+ if refused:
854
+ kinds = ", ".join(sorted({image["media_type"] for image in refused}))
855
+ text += "\n" + _image_note(refused, f"this provider is not sent {kinds}")
856
+ if unreadable:
857
+ text += "\n" + _image_note(unreadable,
858
+ "the stored copy could not be read")
859
+ if sent:
860
+ text += "\n" + _IMAGES_FOLLOW
861
+ return text, sent
862
+
863
+
864
+ def _google_image_turn(pending: list, genai_types):
865
+ """The user-role Content that carries a tool batch's images on GOOGLE
866
+ (ROADMAP_v3 §81, IM9).
867
+
868
+ A FunctionResponse cannot carry them on the models a new account can
869
+ call: Gemini 2.5 answers "multimodal function responses are not
870
+ supported", and only Gemini 3 takes `FunctionResponse.parts`. A harness
871
+ turn after the WHOLE batch can, measured on two Gemini 3 models, and it
872
+ is the shape Google's own ADK uses for an artifact a tool loads. After
873
+ the batch, so the function responses still answer the call turn
874
+ directly; derived per request and never persisted, `_openai_image_turn`'s
875
+ rule; and it says it is the harness speaking."""
876
+ parts: list = []
877
+ for tool_call_id, images in pending:
878
+ parts.append(genai_types.Part(text=(
879
+ f"[Harness: the image(s) attached to the result of tool call "
880
+ f"{tool_call_id}. A function response on this API carries no "
881
+ f"image, so they are delivered here.]")))
882
+ for media_type, data in images:
883
+ parts.append(genai_types.Part(inline_data=genai_types.Blob(
884
+ mime_type=media_type, data=data)))
885
+ return genai_types.Content(role="user", parts=parts)
886
+
887
+
888
+ def _messages_for_provider(provider_name: str, neutral_messages: list[dict],
889
+ model: Optional[str] = None,
890
+ echo_reasoning: bool = False,
891
+ images: bool = False) -> list:
892
+ """The wire shape for one provider.
893
+
894
+ `model` and `echo_reasoning` are §44's: they decide whether a stored
895
+ thinking record may travel. Both DEFAULT to the pre-§44 behaviour --
896
+ no model means no echo, and the OpenAI-compatible side is opt-in per
897
+ provider -- so a caller that does not pass them gets exactly the
898
+ translation this function produced before. On GOOGLE `model` also
899
+ decides whether a function call's thought signature goes back (§82),
900
+ and the echo is not opt-in there: Gemini 3 refuses a turn without one.
901
+
902
+ `images` is ROADMAP_v3 §81's (IM4): whether a tool row's images are
903
+ delivered to this provider, or replaced by `_image_note`. It defaults
904
+ to the note, so a caller that does not pass it sends no bytes. GOOGLE
905
+ reads it too since batch 173 (IM9); it ignored it while that wire was
906
+ deferred.
907
+
908
+ CHATGPT (ROADMAP_v3 §83) gets the Responses API's `input` items, each
909
+ shape measured on the plan route in slice 2a. Its reasoning goes back
910
+ on §44's pair rule like Anthropic's, and is not opt-in: OpenAI's own
911
+ stateless pattern hands it back (CG18, CG23).
912
+ """
913
+ # One rule, above the split (#13, #36). Note this can leave two
914
+ # consecutive user turns -- which is the shape Google's branch has
915
+ # always produced here, and which
916
+ # `test_messages_google_empty_assistant_turn_skipped` has always
917
+ # asserted.
918
+ neutral_messages = [m for m in neutral_messages
919
+ if not _is_empty_assistant_turn(m)]
920
+
921
+ if provider_name == "CHATGPT":
922
+ # Slice 2a, item by item: an earlier reply as a plain assistant
923
+ # message, two user turns in a row, and a call WITHOUT its `fc_`
924
+ # item id -- under any call id, another provider's included, which
925
+ # is what a thread holds after a /model switch. So nothing beyond
926
+ # the neutral {id, name, input} has to be kept for a call.
927
+ translated: list = []
928
+ for msg in neutral_messages:
929
+ role = msg["role"]
930
+ if role == "user":
931
+ translated.append({"role": "user", "content": msg["content"]})
932
+ elif role == "assistant":
933
+ # The reasoning FIRST: the order the model emitted it in.
934
+ translated.extend(_chatgpt_reasoning(model, msg))
935
+ if msg.get("text"):
936
+ translated.append(
937
+ {"role": "assistant", "content": msg["text"]})
938
+ for tc in msg.get("tool_calls", []):
939
+ translated.append({
940
+ "type": "function_call", "call_id": tc["id"],
941
+ "name": tc["name"],
942
+ "arguments": json.dumps(tc["input"]),
943
+ })
944
+ elif role == "tool":
945
+ # CG7: no image is delivered on this wire. One swatch was
946
+ # misread in slice 0, and delivering one is a measurement and
947
+ # a translation still to come, so a result's images become
948
+ # IM5's note whatever `accepts_images` says.
949
+ translated.append({
950
+ "type": "function_call_output",
951
+ "call_id": msg["tool_call_id"],
952
+ "output": _with_image_note(msg),
953
+ })
954
+ return translated
955
+
956
+ if provider_name == "GOOGLE":
957
+ from google.genai import types as genai_types
958
+ # Build a {tool_call_id: function_name} lookup from assistant
959
+ # messages so we can populate FunctionResponse.name (required by
960
+ # Google but absent from the neutral tool-result shape).
961
+ call_id_to_name: dict[str, str] = {}
962
+ for msg in neutral_messages:
963
+ if msg["role"] == "assistant":
964
+ for tc in msg.get("tool_calls", []):
965
+ call_id_to_name[tc["id"]] = tc["name"]
966
+
967
+ translated = []
968
+ # §81 (IM9). (tool_call_id, [(media_type, bytes)]) for the tool
969
+ # batch being translated, sent as one harness turn when the batch
970
+ # ends -- see _google_image_turn.
971
+ pending_images: list = []
972
+ for msg in neutral_messages:
973
+ role = msg["role"]
974
+
975
+ if role != "tool" and pending_images:
976
+ translated.append(
977
+ _google_image_turn(pending_images, genai_types))
978
+ pending_images = []
979
+
980
+ if role == "user":
981
+ translated.append(genai_types.Content(
982
+ role="user",
983
+ parts=[genai_types.Part(text=msg["content"])],
984
+ ))
985
+
986
+ elif role == "assistant":
987
+ parts = []
988
+ if msg.get("text"):
989
+ parts.append(genai_types.Part(text=msg["text"]))
990
+ # §82 (GS2/GS3). Each call goes back with exactly what this
991
+ # model attached to it. A turn it did not write gets the
992
+ # placeholder on its FIRST call -- the one Gemini 3 checks --
993
+ # and nothing on the rest, which is how it signs its own.
994
+ own = _google_signatures(model, msg)
995
+ for index, tc in enumerate(msg.get("tool_calls", [])):
996
+ fallback = _GOOGLE_FOREIGN_SIGNATURE if index == 0 else None
997
+ parts.append(genai_types.Part(
998
+ function_call=genai_types.FunctionCall(
999
+ name=tc["name"],
1000
+ args=tc["input"],
1001
+ id=tc["id"],
1002
+ ),
1003
+ thought_signature=(fallback if own is None
1004
+ else own.get(tc["id"], fallback)),
1005
+ ))
1006
+ # Google rejects Content with empty parts. The turn that
1007
+ # produced them is now dropped above the branch split, so
1008
+ # this branch no longer needs its own guard -- one rule
1009
+ # rather than two that can disagree (#36).
1010
+ translated.append(genai_types.Content(role="model", parts=parts))
1011
+
1012
+ elif role == "tool":
1013
+ name = call_id_to_name.get(msg["tool_call_id"])
1014
+ if name is None:
1015
+ raise ValueError(
1016
+ f"Tool result references tool_call_id={msg['tool_call_id']!r} "
1017
+ f"but no assistant message in the history made that call"
1018
+ )
1019
+ # §81 (IM9/IM10). The images wait for the harness turn after
1020
+ # the batch; the result says they follow, or why not.
1021
+ result, sent = _google_tool_images(msg, images)
1022
+ if sent:
1023
+ pending_images.append((msg["tool_call_id"], sent))
1024
+ part = genai_types.Part(
1025
+ function_response=genai_types.FunctionResponse(
1026
+ name=name,
1027
+ response={"result": result},
1028
+ )
1029
+ )
1030
+ # Batch consecutive tool results into a single user
1031
+ # Content — Google requires strict user/model alternation.
1032
+ # The harness image turn comes only after the batch, so it
1033
+ # never sits between two of them.
1034
+ if (translated
1035
+ and translated[-1].role == "user"
1036
+ and all(p.function_response is not None for p in translated[-1].parts)):
1037
+ translated[-1].parts.append(part)
1038
+ else:
1039
+ translated.append(genai_types.Content(role="user", parts=[part]))
1040
+
1041
+ if pending_images:
1042
+ translated.append(_google_image_turn(pending_images, genai_types))
1043
+ return translated
1044
+
1045
+ if provider_name == "ANTHROPIC":
1046
+ translated: list[dict] = []
1047
+ for msg in neutral_messages:
1048
+ role = msg["role"]
1049
+
1050
+ if role == "user":
1051
+ translated.append({"role": "user", "content": msg["content"]})
1052
+
1053
+ elif role == "assistant":
1054
+ # §44. FIRST in the content array, because that is the
1055
+ # order the model emitted them in and the order the API
1056
+ # documents for the replay -- a signed block after the
1057
+ # text it preceded is not the same message.
1058
+ content = list(_echoed_blocks(provider_name, model, msg))
1059
+ if msg.get("text"):
1060
+ content.append({"type": "text", "text": msg["text"]})
1061
+ for tc in msg.get("tool_calls", []):
1062
+ content.append({
1063
+ "type": "tool_use", "id": tc["id"], "name": tc["name"], "input": tc["input"],
1064
+ })
1065
+ translated.append({"role": "assistant", "content": content})
1066
+
1067
+ elif role == "tool":
1068
+ # Anthropic wants every tool result from one turn batched
1069
+ # into a SINGLE user message with multiple tool_result
1070
+ # blocks, not one message per result -- merge consecutive
1071
+ # tool-role entries into the same message rather than
1072
+ # appending a new one each time.
1073
+ #
1074
+ # §81 (IM4). An image travels INSIDE its tool_result here --
1075
+ # the one wire of the three whose tool result takes an image
1076
+ # block -- after the text, as a content array. The text
1077
+ # block is omitted when empty, because the API rejects an
1078
+ # empty text block.
1079
+ content = msg["content"]
1080
+ if msg.get("images"):
1081
+ if images:
1082
+ content = (
1083
+ [{"type": "text", "text": msg["content"]}]
1084
+ if msg["content"] else [])
1085
+ content += [{
1086
+ "type": "image",
1087
+ "source": {"type": "base64",
1088
+ "media_type": image["media_type"],
1089
+ "data": image["data"]},
1090
+ } for image in msg["images"]]
1091
+ else:
1092
+ content = _with_image_note(msg)
1093
+ block = {
1094
+ "type": "tool_result",
1095
+ "tool_use_id": msg["tool_call_id"],
1096
+ "content": content,
1097
+ }
1098
+ if translated and translated[-1]["role"] == "user" and _is_tool_result_message(translated[-1]):
1099
+ translated[-1]["content"].append(block)
1100
+ else:
1101
+ translated.append({"role": "user", "content": [block]})
1102
+
1103
+ return translated
1104
+
1105
+ # OpenAI-compatible: close to 1:1, each tool result is its own message
1106
+ translated = []
1107
+ # §81 (IM4). (tool_call_id, images) for the tool batch being translated,
1108
+ # sent as one user message when the batch ends -- see _openai_image_turn.
1109
+ pending_images: list = []
1110
+ for msg in neutral_messages:
1111
+ role = msg["role"]
1112
+
1113
+ if role != "tool" and pending_images:
1114
+ translated.append(_openai_image_turn(pending_images))
1115
+ pending_images = []
1116
+
1117
+ if role == "user":
1118
+ translated.append({"role": "user", "content": msg["content"]})
1119
+
1120
+ elif role == "assistant":
1121
+ entry: dict = {"role": "assistant", "content": msg.get("text") or None}
1122
+ # §44, and OPT-IN PER PROVIDER rather than on by default.
1123
+ # There is no standard for sending reasoning back on this wire
1124
+ # the way there is for receiving it: DeepSeek documents that
1125
+ # reasoning_content must not be supplied on input and 400s,
1126
+ # while OpenRouter accepts it for some models and ignores it
1127
+ # for others. Off means today's behaviour exactly, so a
1128
+ # provider that has never been tried cannot be broken by this.
1129
+ if echo_reasoning:
1130
+ echoed = "\n\n".join(
1131
+ b.get("text", "") for b in _echoed_blocks(
1132
+ provider_name, model, msg)
1133
+ if b.get("text"))
1134
+ if echoed:
1135
+ entry["reasoning_content"] = echoed
1136
+ if msg.get("tool_calls"):
1137
+ entry["tool_calls"] = [
1138
+ {
1139
+ "id": tc["id"],
1140
+ "type": "function",
1141
+ "function": {"name": tc["name"], "arguments": json.dumps(tc["input"])},
1142
+ }
1143
+ for tc in msg["tool_calls"]
1144
+ ]
1145
+ translated.append(entry)
1146
+
1147
+ elif role == "tool":
1148
+ content = msg["content"]
1149
+ if msg.get("images"):
1150
+ if images:
1151
+ pending_images.append(
1152
+ (msg["tool_call_id"], msg["images"]))
1153
+ content = f"{content}\n{_IMAGES_FOLLOW}"
1154
+ else:
1155
+ content = _with_image_note(msg)
1156
+ translated.append({
1157
+ "role": "tool", "tool_call_id": msg["tool_call_id"], "content": content,
1158
+ })
1159
+
1160
+ if pending_images:
1161
+ translated.append(_openai_image_turn(pending_images))
1162
+ return translated
1163
+
1164
+
1165
+ # ============================================================================
1166
+ # ---- The actual call --------------------------------------------------------
1167
+ # ============================================================================
1168
+
1169
+ # ============================================================================
1170
+ # ---- Sampling + reasoning-effort translation (ROADMAP_v2 §16) ---------------
1171
+ # ============================================================================
1172
+ #
1173
+ # Both helpers below are the same "translate at the boundary, once" case that
1174
+ # _tools_for_provider / _messages_for_provider exist for: the three providers
1175
+ # express these concepts differently enough that no caller should have to know.
1176
+
1177
+ # (provider_name, model) -> supported effort levels. Populated lazily; the
1178
+ # Anthropic branch queries the API once per process rather than per call.
1179
+ _effort_levels_cache: dict[tuple[str, str], list[str]] = {}
1180
+
1181
+ # (provider_name, model) -> context window in tokens, or None for "asked,
1182
+ # and this provider does not report one". Same lazy, once-per-process
1183
+ # posture as the effort cache above; see context_window_for() for why None
1184
+ # is cached and a raised query is not.
1185
+ _context_window_cache: dict[tuple[str, str], Optional[int]] = {}
1186
+
1187
+ # (provider_name, model) -> how many times the query has RAISED.
1188
+ #
1189
+ # The middle ground between #35's two bad options. Caching a failure makes
1190
+ # one transient error suppress the query for the life of the process;
1191
+ # never caching one means a provider with no /models endpoint at all --
1192
+ # Grok, Fireworks, Z.AI -- is asked again on every turn, which across a
1193
+ # ten-pass research run is ten failing HTTP calls to learn the same thing.
1194
+ # So a failure is retried, and after this many it settles on the table and
1195
+ # says so once. Transient blips still recover; a permanent 404 costs three
1196
+ # calls per process, not one per turn.
1197
+ _context_window_failures: dict[tuple[str, str], int] = {}
1198
+ MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS = 3
1199
+
1200
+ #: ROADMAP_v3 §83 (CG22). The plan route's whole effort vocabulary, read off
1201
+ #: slice 0's `invalid_value` refusal of `ultra`. The model list names a level
1202
+ #: the route refuses (`ultra`), so a level reaches /effort only when the list
1203
+ #: names it AND this does. Slice 2a found the rule exact on both models whose
1204
+ #: refusal lists their levels.
1205
+ CHATGPT_EFFORT_VOCABULARY = ("none", "minimal", "low", "medium", "high",
1206
+ "xhigh", "max")
1207
+ #: CG24, the owner's choice. Six models accepted `none` in slice 2a and two
1208
+ #: refused it; no list entry names it, and a table of the six would go stale
1209
+ #: with a roster that changed between two runs a day apart.
1210
+ CHATGPT_NEVER_OFFERED = frozenset({"none"})
1211
+
1212
+
1213
+ def _chatgpt_listing(client) -> list:
1214
+ """The plan's model list, every entry (ROADMAP_v3 §83).
1215
+
1216
+ `client.get("/models", cast_to=object)`, because the plan's list is
1217
+ `{"models": [...]}` keyed by `slug`, which the SDK's `models.list()` --
1218
+ built for `{"data": [...]}` -- cannot read; slice 2a read it this way.
1219
+ Raises when the list cannot be read, which each caller counts as a
1220
+ failed query.
1221
+ """
1222
+ body = client.get("/models", cast_to=object)
1223
+ entries = body.get("models") if isinstance(body, dict) else None
1224
+ if not isinstance(entries, list):
1225
+ raise ValueError(
1226
+ "the ChatGPT plan's model list carried no `models` array")
1227
+ return [entry for entry in entries if isinstance(entry, dict)]
1228
+
1229
+
1230
+ def _chatgpt_entry(entries: list, model: str) -> Optional[dict]:
1231
+ """`model`'s entry, or None when the list does not name it. Any entry
1232
+ counts, a `visibility: hide` one included: a hidden model works when
1233
+ named, and its levels and window are its own."""
1234
+ return next((e for e in entries if e.get("slug") == model), None)
1235
+
1236
+
1237
+ def _chatgpt_unlisted(model: str, entries: list) -> None:
1238
+ """Say that the plan does not list `model`, and what it does list.
1239
+
1240
+ Batch 189, the owner's live check: a typo (`gpt-6-luba`) fell through to
1241
+ the static table's warning, which advised adding a config entry and
1242
+ named `ultra` -- a level the CHATGPT filter removes after that warning
1243
+ is written. On the plan an unlisted name is likeliest misspelt, and the
1244
+ list that would show it was already in hand.
1245
+ """
1246
+ listed = [e.get("slug") for e in entries
1247
+ if e.get("visibility") == "list" and e.get("slug")]
1248
+ logger.warning(
1249
+ "%r is not in your ChatGPT plan's model list, so the next turn will "
1250
+ "probably be refused. The plan lists: %s.", model,
1251
+ ", ".join(listed) or "no models")
1252
+
1253
+
1254
+ def _sampling_kwargs(provider_name: str, model: str, temperature,
1255
+ effort: Optional[str] = None) -> dict:
1256
+ """Sampling parameters for this call, or {} when the model rejects them.
1257
+
1258
+ Current Anthropic models removed temperature/top_p/top_k outright (any
1259
+ value returns a 400) and Sonnet 5 rejects non-default values. Sending
1260
+ one anyway is not a degraded request, it is a failed one -- which is how
1261
+ ROADMAP §10's ensemble mode came to be built, documented as working, and
1262
+ incapable of running against this harness's own default model.
1263
+
1264
+ TWO MORE, MEASURED FROM THE PROVIDERS' OWN DOCUMENTATION (ROADMAP_v3
1265
+ §87, #6). OpenAI's rule for its reasoning models is "When reasoning
1266
+ effort is not `none`, remove `temperature`, `top_p`, and
1267
+ `top_logprobs`", and a model that reasons refuses one with a 400 -- so
1268
+ `effort` decides it on OPENAI, the value `_thinking_for_provider` is
1269
+ about to send, with no model list to go stale. And Google's Gemini 3.6
1270
+ Flash and 3.5 Flash-Lite IGNORE a temperature, as Google says every
1271
+ later Gemini will: no error, no effect, which is the one failure here
1272
+ worse than a 400. Those are named in the set below like the rest.
1273
+
1274
+ ON ANTHROPIC, EVERY MODEL, SINCE BATCH 234 (A82, amended). anthropic 2.x
1275
+ sends API version 2026-10-21, which refuses `temperature`, `top_p` and
1276
+ `top_k` with a 400 on every model, even at the default; and 1.0 took
1277
+ them out of `messages.stream()`, so passing one is a TypeError before
1278
+ anything is sent (measured). The set's Claude names stay for Claude
1279
+ reached through an OpenAI-compatible gateway, where they are still the
1280
+ only thing that can drop it.
1281
+
1282
+ Dropping the parameter is logged at WARNING rather than done silently.
1283
+
1284
+ THIS FUNCTION NOW HAS NO CALLER THAT DEPENDS ON IT, and the warning is
1285
+ what makes that safe. Ensemble mode used to be the one, and
1286
+ orchestrator.py carried a guard refusing to run it on a model in the set
1287
+ below. §10's revisit replaced sampling variation with a roster of
1288
+ different models, so the guard is gone and nothing in the harness passes
1289
+ a temperature any more.
1290
+
1291
+ Kept rather than removed: `temperature` still threads through
1292
+ core/loop.py, this is still the correct boundary translation for it, and
1293
+ the next caller to want sampling variation needs to be told rather than
1294
+ silently ignored. If this warning ever fires, something new is relying on
1295
+ sampling variation without knowing it cannot have it -- which is exactly
1296
+ how §10 came to be built, documented as working, and incapable of running
1297
+ against this harness's own default model.
1298
+ """
1299
+ if temperature is None:
1300
+ return {}
1301
+ if provider_name == "CHATGPT":
1302
+ # ROADMAP_v3 §83: the plan route answers a temperature with 400
1303
+ # "Unsupported parameter" (slice 0), on every model.
1304
+ logger.warning(
1305
+ "Dropping temperature=%s: the ChatGPT plan's route refuses "
1306
+ "sampling parameters.", temperature)
1307
+ return {}
1308
+ if provider_name == "ANTHROPIC":
1309
+ logger.warning(
1310
+ "Dropping temperature=%s: Anthropic's API version 2026-10-21 "
1311
+ "refuses sampling parameters on every model.", temperature)
1312
+ return {}
1313
+ if provider_name == "OPENAI" and effort and effort != "none":
1314
+ # §87. Sent no effort at all, a reasoning model still reasons at
1315
+ # its own default and still refuses: that stays the loud 400 an
1316
+ # unlisted model has always been, rather than a guess here.
1317
+ logger.warning(
1318
+ "Dropping temperature=%s: OpenAI refuses sampling parameters "
1319
+ "while a model reasons (reasoning effort %r).", temperature,
1320
+ effort)
1321
+ return {}
1322
+ if model in config.MODELS_REJECTING_SAMPLING_PARAMS:
1323
+ logger.warning(
1324
+ "Dropping temperature=%s: model %r rejects sampling parameters. "
1325
+ "Steer via prompting or reasoning effort instead.",
1326
+ temperature, model,
1327
+ )
1328
+ return {}
1329
+ return {"temperature": temperature}
1330
+
1331
+
1332
+ def effort_for(client, provider_name: str, model: str,
1333
+ requested: Optional[str]) -> Optional[str]:
1334
+ """The effort level to actually SEND to (provider_name, model), or None.
1335
+
1336
+ One validator for every send site, because nothing else checked a
1337
+ level against the model that would receive it. Three ways a wrong one
1338
+ used to reach the wire, all of them 400ing every turn until the user
1339
+ intervened by hand:
1340
+
1341
+ * a persisted settings.json `tui.effort` was trusted as-is;
1342
+ * the TUI's current level was inherited by an agent that declares
1343
+ its OWN model/provider, so a level validated for one model was
1344
+ sent to a different one;
1345
+ * nothing revalidated after a /model or agent switch.
1346
+
1347
+ `effort=None` sends nothing on every provider and is the one
1348
+ universally safe value, so dropping is always available as an answer.
1349
+
1350
+ On a FAILED lookup the requested level is passed through unverified
1351
+ with a warning rather than dropped: a transient network blip must not
1352
+ silently downgrade a deliberate choice. A genuinely wrong level still
1353
+ fails at the provider, which is the honest outcome.
1354
+ """
1355
+ if not requested:
1356
+ return None
1357
+ levels, authoritative = _effort_levels(client, provider_name, model)
1358
+ if requested in levels:
1359
+ return requested
1360
+ if not authoritative:
1361
+ logger.warning(
1362
+ "Could not verify effort %r for %s/%s; sending it unverified.",
1363
+ requested, provider_name, model)
1364
+ return requested
1365
+ logger.warning(
1366
+ "Dropping effort %r: %s/%s accepts %s. Sending no effort parameter.",
1367
+ requested, provider_name, model, levels or "no effort control")
1368
+ return None
1369
+
1370
+
1371
+ def effort_levels_for_model(client, provider_name: str, model: str) -> list[str]:
1372
+ """Reasoning-effort levels this model accepts, most-to-least capable last.
1373
+
1374
+ Anthropic is queried, not tabulated: its Models API reports per-model
1375
+ effort support (`capabilities.effort.<level>.supported`), so a newly
1376
+ released Anthropic model needs no manual entry here. Every other provider
1377
+ is tabulated because there is nothing to ask -- no OpenAI-compatible
1378
+ provider in providers.json exposes a capability endpoint, and Google
1379
+ expresses depth as an integer budget rather than a level set at all.
1380
+
1381
+ Falling back logs at WARNING, matching §21's MODEL_CONTEXT_WINDOWS
1382
+ posture: a static table is honest about being incomplete, but it should
1383
+ say so out loud when it is the thing answering.
1384
+
1385
+ Returns [] when the model supports no effort control, which callers must
1386
+ treat as "offer no picker and send no effort parameter".
1387
+ """
1388
+ return _effort_levels(client, provider_name, model)[0]
1389
+
1390
+
1391
+ def effort_choice(levels, requested: str, current: Optional[str],
1392
+ model: str) -> tuple:
1393
+ """`/effort`'s decision in either shell: `(level, sentence, refused)`.
1394
+
1395
+ `levels` is what `effort_levels_for_model` answered for the session's
1396
+ model, `requested` the command's argument and `current` the level in
1397
+ force. The level comes back unchanged for a report or a refusal, None
1398
+ for `auto`, and the requested one when the model accepts it.
1399
+
1400
+ ONE COPY (ROADMAP_v3 §89): the TUI answers on a worker's message and
1401
+ the CLI inline, and what each may accept is the same decision. Moved
1402
+ out of the TUI's `_apply_effort_command`.
1403
+ """
1404
+ if not levels:
1405
+ return current, f"{model} exposes no reasoning-effort control.", False
1406
+ available = ", ".join(levels)
1407
+ if not requested:
1408
+ return (current,
1409
+ f"Effort: {current or 'auto'}. Available: {available} "
1410
+ f"(or 'auto').", False)
1411
+ if requested == "auto":
1412
+ return None, "Effort set to auto.", False
1413
+ if requested in levels:
1414
+ return requested, f"Effort set to {requested}.", False
1415
+ return (current,
1416
+ f"{model} does not support effort {requested!r}. "
1417
+ f"Available: {available}.", True)
1418
+
1419
+
1420
+ def _effort_levels(client, provider_name: str, model: str) -> tuple:
1421
+ """(levels, authoritative).
1422
+
1423
+ `authoritative` is False when the answer came from the static table
1424
+ after the capability QUERY failed, as opposed to because no query was
1425
+ ever possible for that provider. Only effort_for() needs the
1426
+ distinction -- an unverified answer must not be used to drop a level
1427
+ the user deliberately chose.
1428
+ """
1429
+ key = (provider_name, model)
1430
+ if key in _effort_levels_cache:
1431
+ return _effort_levels_cache[key], True
1432
+
1433
+ levels: Optional[list[str]] = None
1434
+ query_failed = False
1435
+ if provider_name == "GOOGLE" and not _google_supports_thinking_budget():
1436
+ # Reporting no levels is the honest answer, not a silent [] : on the
1437
+ # pinned SDK there is no field to put a budget in, so a picker
1438
+ # offering levels would be offering something unsendable.
1439
+ _effort_levels_cache[key] = []
1440
+ return [], True
1441
+ if provider_name == "ANTHROPIC":
1442
+ try:
1443
+ # ATTRIBUTES, not subscripts (#35). This read used to be
1444
+ # `capabilities["effort"]` with `effort.get(name)` and
1445
+ # `isinstance(..., dict)`. On the exactly-pinned SDK those are
1446
+ # pydantic models -- ModelCapabilities, EffortCapability,
1447
+ # CapabilitySupport -- supporting neither [] nor .get(), so the
1448
+ # TypeError was caught below, query_failed was set, and the
1449
+ # query FELL BACK EVERY SINGLE TIME. Not "failed sometimes":
1450
+ # it could not succeed. All three dict spellings were wrong,
1451
+ # so correcting the subscript alone would have failed one line
1452
+ # further down.
1453
+ #
1454
+ # No dict/attribute dual path on purpose. A defensive default
1455
+ # is only safe where absence is impossible, requirements.txt
1456
+ # pins anthropic exactly, and test_sdk_conformance.py exists
1457
+ # to go red when the pinned shape moves -- which is a better
1458
+ # signal than a fallback that silently keeps guessing.
1459
+ info = client.models.retrieve(model)
1460
+ # ONE retrieve, TWO readings (§21's revisit). The context
1461
+ # window is on this SAME ModelInfo as `max_input_tokens`, so
1462
+ # recording it here IS the entire Anthropic half of the
1463
+ # window query: no second call, no second failure mode, and
1464
+ # it lands on the path every send already crosses
1465
+ # (core/loop.py calls effort_for before the wire). §21
1466
+ # rejected a window query on the belief that there was
1467
+ # nothing to ask; for this provider the answer was already
1468
+ # in hand and being dropped. See context_window_for below.
1469
+ _record_window(provider_name, model,
1470
+ getattr(info, "max_input_tokens", None))
1471
+ capabilities = info.capabilities
1472
+ effort = capabilities.effort
1473
+ levels = [
1474
+ name for name in ("low", "medium", "high", "xhigh", "max")
1475
+ # getattr, because `xhigh` is Optional on the pinned type
1476
+ # and a model that does not offer a level reports None
1477
+ # rather than supported=False.
1478
+ if getattr(getattr(effort, name, None), "supported", False)
1479
+ ]
1480
+ except Exception as e:
1481
+ # Network failure, an SDK too old to expose capabilities, or a
1482
+ # model the endpoint doesn't know. Fall through to the table.
1483
+ query_failed = True
1484
+ logger.warning(
1485
+ "Could not read effort capabilities for %r from the Anthropic "
1486
+ "Models API (%s); falling back to the static table.", model, e,
1487
+ )
1488
+ if provider_name == "CHATGPT":
1489
+ try:
1490
+ entries = _chatgpt_listing(client)
1491
+ except Exception as e:
1492
+ query_failed = True
1493
+ logger.warning(
1494
+ "Could not read effort levels for %r from the ChatGPT plan's "
1495
+ "model list (%s); falling back to the static table.", model, e)
1496
+ else:
1497
+ entry = _chatgpt_entry(entries, model)
1498
+ if entry is not None:
1499
+ # ONE read, TWO readings, as Anthropic's retrieve: the entry
1500
+ # carries the window too.
1501
+ _record_window(provider_name, model,
1502
+ entry.get("context_window"))
1503
+ levels = [lv.get("effort") if isinstance(lv, dict) else lv
1504
+ for lv in entry.get("supported_reasoning_levels")
1505
+ or []]
1506
+ else:
1507
+ # The list answered and does not name the model: said in
1508
+ # the plan's own terms, and the default set is filtered
1509
+ # below like any other, without the static table's advice.
1510
+ _chatgpt_unlisted(model, entries)
1511
+ levels = list(config.DEFAULT_EFFORT_LEVELS)
1512
+
1513
+ if levels is None:
1514
+ levels = config.MODEL_EFFORT_LEVELS.get(model)
1515
+ if levels is None:
1516
+ logger.warning(
1517
+ "No effort levels known for %r on %s; assuming %s. Add an entry "
1518
+ "to config.MODEL_EFFORT_LEVELS if this is wrong.",
1519
+ model, provider_name, config.DEFAULT_EFFORT_LEVELS,
1520
+ )
1521
+ levels = list(config.DEFAULT_EFFORT_LEVELS)
1522
+
1523
+ if provider_name == "CHATGPT":
1524
+ # CG22 and CG24, applied to the static table's answer as well: its
1525
+ # default set ends in `ultra`, which the route refuses.
1526
+ levels = [lv for lv in levels if lv in CHATGPT_EFFORT_VOCABULARY
1527
+ and lv not in CHATGPT_NEVER_OFFERED]
1528
+
1529
+ if query_failed:
1530
+ # Do NOT cache a failure-derived guess. Caching it made one
1531
+ # transient error permanently suppress the query that is this
1532
+ # function's entire reason to exist: for the whole process life
1533
+ # the picker would offer a guessed level set, and every selection
1534
+ # from it could 400 with no path back short of a restart.
1535
+ return levels, False
1536
+
1537
+ _effort_levels_cache[key] = levels
1538
+ return levels, True
1539
+
1540
+
1541
+ # The field names a provider might report a context window under, in the
1542
+ # order they are tried. ONE reader covers every OpenAI-compatible provider
1543
+ # rather than one adapter each, because openai.types.Model is declared
1544
+ # `extra="allow"` -- a field the SDK does not model survives on the parsed
1545
+ # object and reaches `.model_extra`. Verified against the pinned openai
1546
+ # (2.45.0 when written, 3.36.0 since batch 234) in test_sdk_conformance.py,
1547
+ # because that permissiveness is the whole reason this is one function.
1548
+ #
1549
+ # context_window Groq
1550
+ # context_length Together, OpenRouter, Cohere (native /v1 only)
1551
+ # max_context_length Mistral
1552
+ # max_input_tokens Anthropic's spelling, accepted here so a gateway
1553
+ # proxying Anthropic through an OpenAI-shaped API
1554
+ # is not silently unreadable
1555
+ #
1556
+ # OpenAI, DeepSeek and Perplexity report NONE of these -- they answer with
1557
+ # id/created/object/owned_by and nothing else. That is not a failure, it is
1558
+ # the answer, and it is why config.MODEL_CONTEXT_WINDOWS still exists.
1559
+ _WINDOW_FIELD_ALIASES = (
1560
+ "context_window",
1561
+ "context_length",
1562
+ "max_context_length",
1563
+ "max_input_tokens",
1564
+ )
1565
+
1566
+ #: Returned by _model_info when a COMPLETE listing did not contain the model.
1567
+ #: Distinct from a raise: the provider answered, so there is nothing to retry.
1568
+ _NOT_LISTED = object()
1569
+
1570
+
1571
+ def _window_from_model_object(info) -> Optional[int]:
1572
+ """The context window off one provider model object, or None.
1573
+
1574
+ Declared fields first, then model_extra -- the same object may carry
1575
+ either depending on whether the installed SDK models the field.
1576
+ ATTRIBUTES not subscripts, for #35's reason: these are pydantic objects
1577
+ on every pinned SDK here.
1578
+
1579
+ `top_provider.context_length` is the one NESTED spelling, and it is
1580
+ OpenRouter's: the flat `context_length` is the model's maximum across
1581
+ every backend, while top_provider carries the routed one. Read second,
1582
+ so the flat value still wins where both exist -- this is a fallback for
1583
+ entries that carry only the nested form, not a preference for the
1584
+ narrower number.
1585
+ """
1586
+ extra = getattr(info, "model_extra", None) or {}
1587
+ for name in _WINDOW_FIELD_ALIASES:
1588
+ value = getattr(info, name, None)
1589
+ if value is None:
1590
+ value = extra.get(name)
1591
+ if value is not None:
1592
+ return value
1593
+ top = extra.get("top_provider")
1594
+ if isinstance(top, dict):
1595
+ return top.get("context_length")
1596
+ return None
1597
+
1598
+
1599
+ def _model_info(client, model):
1600
+ """The provider's object for one model, via retrieve or via the listing.
1601
+
1602
+ THE ROUTE WAS THE BUG, NOT THE READER (batch 44). This asked
1603
+ `client.models.retrieve(model)` alone, which is `GET {base}/models/{id}`
1604
+ -- and OpenRouter implements `GET /api/v1/models` plus
1605
+ `/models/:author/:slug/endpoints` and no plain per-id retrieve, so an id
1606
+ containing a slash (`minimax/minimax-m3`) turns the path into a route
1607
+ that does not exist. 404, every time, on a provider whose listing has
1608
+ carried `context_length` all along and which _WINDOW_FIELD_ALIASES'
1609
+ own comment names. NVIDIA's endpoint has the same shape, and so does
1610
+ every other provider whose ids are `vendor/model`.
1611
+
1612
+ Retrieve stays FIRST: it is one call and it is the right one for Groq,
1613
+ Together and Mistral, and a listing can be hundreds of entries. The
1614
+ fallback costs one extra call per provider per process, on the path
1615
+ that was previously three failures and a permanent give-up.
1616
+
1617
+ Three outcomes, deliberately distinct:
1618
+ an object something answered
1619
+ _NOT_LISTED a complete listing came back without this model, which
1620
+ is an ANSWER ("this provider has nothing to say about
1621
+ it") and must not be retried like a network blip
1622
+ raises neither route could answer; the caller counts it
1623
+ """
1624
+ try:
1625
+ return client.models.retrieve(model)
1626
+ except Exception as retrieve_error:
1627
+ listing = getattr(getattr(client, "models", None), "list", None)
1628
+ if listing is None:
1629
+ raise
1630
+ try:
1631
+ entries = list(listing())
1632
+ except Exception:
1633
+ # The listing is not a second opinion about the retrieve; it is
1634
+ # the same question by another route. Report the FIRST failure,
1635
+ # which is the one that names the endpoint the caller asked for.
1636
+ raise retrieve_error from None
1637
+ for entry in entries:
1638
+ if getattr(entry, "id", None) == model:
1639
+ return entry
1640
+ if not entries:
1641
+ # An empty listing answered nothing at all; report the failure
1642
+ # that names the endpoint the caller actually asked for.
1643
+ raise retrieve_error from None
1644
+ return _NOT_LISTED
1645
+
1646
+
1647
+ def _record_window(provider_name: str, model: str, value) -> Optional[int]:
1648
+ """Cache a queried window, coercing anything unusable to None.
1649
+
1650
+ A POSITIVE int or nothing. The Anthropic Models API types
1651
+ `max_input_tokens` as nullable and its own documented example carries
1652
+ a placeholder 0, so "present" is not "usable" -- and a 0 reaching
1653
+ compaction would make `context_limit - backstop` clamp to the floor
1654
+ and compact continuously. Anything that is not a positive int is
1655
+ recorded as None, which means "asked, got no usable answer" and sends
1656
+ the caller to the static table.
1657
+ """
1658
+ window = value if isinstance(value, int) and not isinstance(value, bool) else None
1659
+ if window is not None and window <= 0:
1660
+ window = None
1661
+ _context_window_cache[(provider_name, model)] = window
1662
+ return window
1663
+
1664
+
1665
+ def known_context_window(provider_name: str, model: str) -> Optional[int]:
1666
+ """The queried window for (provider, model), or None if none is known.
1667
+
1668
+ CACHE ONLY -- this never makes a call, which is what lets
1669
+ core/compaction.py ask the question without holding a client or
1670
+ importing an SDK. The cache is primed by context_window_for() on the
1671
+ path core/loop.py already crosses before every send, so by the time a
1672
+ compaction check runs the answer is there if the provider had one.
1673
+ """
1674
+ return _context_window_cache.get((provider_name, model))
1675
+
1676
+
1677
+ def context_window_for(client, provider_name: str, model: str) -> tuple:
1678
+ """(window_or_None, authoritative). Queries the provider once per process.
1679
+
1680
+ §21 rejected this as needing "fifteen adapters" for a roster where no
1681
+ uniform endpoint existed. Re-measured against the PINNED SDKs, that
1682
+ premise did not hold, and the shape below is what it actually costs:
1683
+
1684
+ ANTHROPIC already answered. _effort_levels retrieves the ModelInfo
1685
+ to read capabilities.effort and max_input_tokens rides
1686
+ along on it, so this branch is usually a cache hit and
1687
+ makes no call at all.
1688
+ GOOGLE models.get(...).input_token_limit, one field on the
1689
+ pinned google-genai type.
1690
+ CHATGPT the plan's model list, `context_window` on the model's
1691
+ entry (ROADMAP_v3 §83) -- not the larger
1692
+ `max_context_window`. Usually a cache hit too: _effort_levels
1693
+ records it off the same read.
1694
+ v1-compat ONE alias sniff over model_extra, not thirteen adapters,
1695
+ because openai.types.Model allows extra fields -- over
1696
+ whichever of models.retrieve() and models.list() answers
1697
+ (see _model_info: providers whose ids carry a slash have
1698
+ no per-id route, so retrieve 404s on them).
1699
+
1700
+ §21's CONCLUSION survives intact and is why the table remains: OpenAI,
1701
+ DeepSeek and Perplexity report nothing, so a fallback constant is
1702
+ still needed at the end of it.
1703
+
1704
+ THE FAILURE/SILENCE SPLIT IS THE POINT, and it is _effort_levels'
1705
+ query_failed rule (#35's lesson) applied to a second query. A call
1706
+ that RAISED is warned and NOT cached: a transient network error must
1707
+ not permanently suppress the query for the life of the process. A
1708
+ call that SUCCEEDED and reported no window IS cached as None, because
1709
+ that is a real and stable answer, and re-asking it on every
1710
+ compaction evaluation would spend a request per step to learn the
1711
+ same thing.
1712
+ """
1713
+ key = (provider_name, model)
1714
+ if key in _context_window_cache:
1715
+ return _context_window_cache[key], True
1716
+
1717
+ try:
1718
+ if provider_name == "GOOGLE":
1719
+ info = client.models.get(model=model)
1720
+ return _record_window(
1721
+ provider_name, model,
1722
+ getattr(info, "input_token_limit", None)), True
1723
+ if provider_name == "CHATGPT":
1724
+ entry = _chatgpt_entry(_chatgpt_listing(client), model)
1725
+ return _record_window(
1726
+ provider_name, model,
1727
+ entry.get("context_window") if entry else None), True
1728
+ info = _model_info(client, model)
1729
+ if info is _NOT_LISTED:
1730
+ # Asked and answered by a listing that did not name it.
1731
+ return _record_window(provider_name, model, None), True
1732
+ window = _window_from_model_object(info)
1733
+ if window is not None:
1734
+ return _record_window(provider_name, model, window), True
1735
+ # Asked and answered: this provider reports no window.
1736
+ return _record_window(provider_name, model, None), True
1737
+ except Exception as e:
1738
+ # Network failure, a provider with no models endpoint at all, or a
1739
+ # model the endpoint does not know. Not cached as an ANSWER -- see
1740
+ # the docstring -- but counted, so a permanent failure stops being
1741
+ # re-asked once it has proved it is not a blip.
1742
+ attempts = _context_window_failures.get(key, 0) + 1
1743
+ _context_window_failures[key] = attempts
1744
+ giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
1745
+ logger.warning(
1746
+ "Could not read a context window for %r from %s (%s); "
1747
+ "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
1748
+ model, provider_name, e,
1749
+ " Not asking again this session." if giving_up else "")
1750
+ if giving_up:
1751
+ _record_window(provider_name, model, None)
1752
+ return None, False
1753
+
1754
+
1755
+ _google_budget_support: Optional[bool] = None
1756
+
1757
+
1758
+ def _google_supports_thinking_budget() -> bool:
1759
+ """Whether the INSTALLED google-genai can express a thinking budget.
1760
+
1761
+ Checked rather than assumed, and the check earned its keep: the old pin,
1762
+ google-genai 1.0.0, shipped a ThinkingConfig whose only field was
1763
+ `include_thoughts`, so ThinkingConfig(thinking_budget=N) raised a
1764
+ TypeError and reasoning effort was unavailable on Google.
1765
+
1766
+ The pin moved in batch 172 (ROADMAP_v3 §82, GS1) -- for thought
1767
+ signatures, not for effort -- and 2.29.0 carries the field, so this now
1768
+ answers True and Google effort is on. The check stays: it is still the
1769
+ dependency's real shape that decides, D22's rule, and a downgrade would
1770
+ turn effort off again rather than send a field the SDK cannot carry.
1771
+ """
1772
+ from google.genai import types as genai_types
1773
+
1774
+ global _google_budget_support
1775
+ if _google_budget_support is None:
1776
+ fields = getattr(genai_types.ThinkingConfig, "model_fields", {})
1777
+ _google_budget_support = "thinking_budget" in fields
1778
+ if not _google_budget_support:
1779
+ logger.info(
1780
+ "Installed google-genai has no ThinkingConfig.thinking_budget; "
1781
+ "reasoning effort is unavailable on GOOGLE until the pin moves."
1782
+ )
1783
+ return _google_budget_support
1784
+
1785
+
1786
+ def _thinking_record(provider_name: str, model: str,
1787
+ blocks: list) -> Optional[dict]:
1788
+ """The turn's reasoning in the shape ModelResponse.thinking carries.
1789
+
1790
+ None when the turn produced none, so "no reasoning" and "a provider
1791
+ that reports none" stay one thing and no row is written for either.
1792
+ """
1793
+ if not blocks:
1794
+ return None
1795
+ return {"provider": provider_name, "model": model, "blocks": blocks}
1796
+
1797
+
1798
+ def _thinking_for_provider(provider_name: str, effort: Optional[str]) -> dict:
1799
+ """Reasoning-effort kwargs for this provider, or {} when no effort is set.
1800
+
1801
+ Effort is opt-in: `effort=None` sends nothing at all and every provider
1802
+ behaves exactly as it did before §16. That matters because the parameter
1803
+ is not universally safe -- `reasoning_effort` is rejected by
1804
+ OpenAI-compatible NON-reasoning models, and `thinking: {"type": "adaptive"}`
1805
+ is rejected by pre-4.6 Anthropic models. Callers are expected to offer
1806
+ only the levels effort_levels_for_model() reported, and to offer nothing
1807
+ when it reported none.
1808
+
1809
+ Returned keys are merged into the provider's own kwargs by the caller;
1810
+ the Google entry is nested inside GenerateContentConfig rather than sent
1811
+ top-level, matching how that provider takes every other setting.
1812
+
1813
+ CHATGPT is the one provider that sends something with no effort set
1814
+ (ROADMAP_v3 §83, CG18). Every request asks for a reasoning summary and
1815
+ for the encrypted reasoning: both were accepted with and without an
1816
+ effort in slice 2a, the encrypted reasoning arrives unasked anyway, and
1817
+ asking says what this code relies on rather than leaning on a default.
1818
+ "auto" leaves the summary to the server, which wrote one on one of the
1819
+ two requests that asked.
1820
+ """
1821
+ if provider_name == "CHATGPT":
1822
+ reasoning = {"summary": "auto"}
1823
+ if effort:
1824
+ reasoning["effort"] = effort
1825
+ return {"reasoning": reasoning,
1826
+ "include": ["reasoning.encrypted_content"]}
1827
+ if not effort:
1828
+ return {}
1829
+ if provider_name == "ANTHROPIC":
1830
+ # Adaptive thinking + an effort level is the current-model pairing;
1831
+ # `display` is EXPLICIT because its default changed under us. On
1832
+ # Fable 5, Opus 5, Opus 4.8/4.7 and Sonnet 5 it defaults to
1833
+ # "omitted", which still streams thinking blocks but with EMPTY
1834
+ # text -- so §38's whole feature rendered nothing at all on
1835
+ # Anthropic: ev.thinking was "", core/loop.py's `if
1836
+ # token.thinking_delta` never fired, and neither the inline block
1837
+ # nor ThinkingIndicator ever appeared. It looked like it worked
1838
+ # because the OpenAI-compatible branch reads reasoning_content and
1839
+ # is unaffected. The raw chain of thought is never exposed on any
1840
+ # model; "summarized" is the readable form, and it is what the
1841
+ # blocks captured below carry back to the model that wrote them.
1842
+ # budget_tokens was removed and returns a 400.
1843
+ return {
1844
+ "thinking": {"type": "adaptive", "display": "summarized"},
1845
+ "output_config": {"effort": effort},
1846
+ }
1847
+ if provider_name == "GOOGLE":
1848
+ from google.genai import types as genai_types
1849
+ budget = config.GOOGLE_THINKING_BUDGETS.get(effort)
1850
+ if budget is None or not _google_supports_thinking_budget():
1851
+ return {}
1852
+ return {"thinking_config": genai_types.ThinkingConfig(thinking_budget=budget)}
1853
+ return {"reasoning_effort": effort}
1854
+
1855
+
1856
+ # ============================================================================
1857
+ # ---- The ChatGPT plan's Responses path (ROADMAP_v3 §83, slice 2) -----------
1858
+ # ============================================================================
1859
+ #
1860
+ # The one route the plan answers on is the Responses API (CG3), carried by the
1861
+ # openai SDK (CG21). Every shape below was measured on the owner's account in
1862
+ # slices 0 and 2a, except CG23's reasoning inside a tool loop, which is said
1863
+ # where it is sent (_chatgpt_reasoning).
1864
+
1865
+ class ChatGPTPlanError(RuntimeError):
1866
+ """A plan request OpenAI refused for a reason another attempt cannot fix
1867
+ (CG10). The message is the person's to read.
1868
+
1869
+ ITS OWN TYPE, WITH NO `status_code`, and that is what makes it permanent
1870
+ to `core/provider_errors.py`, which reads a failure by its class names
1871
+ and its `status_code` and `body` and finds none of them here. So the
1872
+ loop's generic 429 retry never sees a usage limit, which CG10 says is
1873
+ never retried.
1874
+ """
1875
+
1876
+
1877
+ class ChatGPTUsageLimit(ChatGPTPlanError):
1878
+ """The plan's usage limit. Its message LEADS with Manage usage (CG8)."""
1879
+
1880
+
1881
+ class ChatGPTNotEligible(ChatGPTPlanError):
1882
+ """This account cannot share its plan, or its sign-in was kept without
1883
+ the plan scope (CG6)."""
1884
+
1885
+
1886
+ class ChatGPTUnsupported(ChatGPTPlanError):
1887
+ """A field the plan does not support. The message names it, and the
1888
+ same request is not sent again (CG10)."""
1889
+
1890
+
1891
+ #: §83's adopted default: an ineligible account is told the whole story once
1892
+ #: per process and briefly after that.
1893
+ _ineligible_explained = False
1894
+
1895
+
1896
+ def _wire_dict(obj) -> dict:
1897
+ """An SDK object as the plain dict the wire spelled, `None` fields left
1898
+ out: what goes into §44's record and back unchanged, the shape slice 2a
1899
+ handed back."""
1900
+ if isinstance(obj, dict):
1901
+ return {k: v for k, v in obj.items() if v is not None}
1902
+ dump = getattr(obj, "model_dump", None)
1903
+ if callable(dump):
1904
+ return dump(exclude_none=True, mode="json")
1905
+ return {}
1906
+
1907
+
1908
+ def _chatgpt_fields(body) -> tuple:
1909
+ """(code, param, message) off an error body, whichever of OpenAI's two
1910
+ shapes it came in: the standard error object, or `{"detail": ...}`."""
1911
+ error = body.get("error") if isinstance(body, dict) and isinstance(
1912
+ body.get("error"), dict) else body
1913
+ if not isinstance(error, dict):
1914
+ return None, None, None
1915
+ return (error.get("code"), error.get("param"),
1916
+ error.get("message") or error.get("detail"))
1917
+
1918
+
1919
+ def _chatgpt_refusal(body) -> Optional[Exception]:
1920
+ """CG10's exception for a refusal its code names, or None.
1921
+
1922
+ None hands the failure back to `core/provider_errors.py`, as for every
1923
+ other provider: a 503, another 429 or a dropped connection is retried
1924
+ with the loop's bounded backoff, and anything else fails the turn.
1925
+ """
1926
+ global _ineligible_explained
1927
+ from core import chatgpt_auth
1928
+
1929
+ code, param, message = _chatgpt_fields(body)
1930
+ said = (f" OpenAI said: {' '.join(str(message).split())[:300]}"
1931
+ if message else "")
1932
+ if code == "subscription_sharing_usage_limit_exceeded":
1933
+ return ChatGPTUsageLimit(
1934
+ f"Manage usage: {chatgpt_auth.USAGE_URL} -- this ChatGPT plan "
1935
+ f"has reached its usage limit, so the request was not sent again. "
1936
+ f"Your next message tries once more.{said}")
1937
+ if code == "subscription_sharing_user_not_eligible":
1938
+ if _ineligible_explained:
1939
+ return ChatGPTNotEligible(
1940
+ "This ChatGPT account cannot share its plan (said above).")
1941
+ _ineligible_explained = True
1942
+ return ChatGPTNotEligible(
1943
+ f"This ChatGPT account cannot share its plan with an app, so "
1944
+ f"nothing was sent again and no new sign-in was asked for. Switch "
1945
+ f"with /model, or sign out with /disconnect chatgpt.{said}")
1946
+ if code == "subscription_sharing_unsupported_capability":
1947
+ return ChatGPTUnsupported(
1948
+ f"The ChatGPT plan does not support "
1949
+ f"{param or 'a field this request sent'}, so the request was not "
1950
+ f"sent again.{said}")
1951
+ return None
1952
+
1953
+
1954
+ def _chatgpt_open(client, request: dict):
1955
+ """The stream, opened with CG10's one forced refresh on a 401.
1956
+
1957
+ The SDK called `chatgpt_auth.access_token` for the token it sent and
1958
+ holds that token as `client.api_key`. `replacing=` refreshes only while
1959
+ the file still holds it, so two requests refused together spend one
1960
+ refresh between them. A refresh refused as unusable raises `SignedOut`
1961
+ with the session cleared; a second 401 after a good refresh says to sign
1962
+ in again and keeps the tokens, because only an unusable refresh clears
1963
+ them (CG10). A refresh that could not be made at all is a
1964
+ `ConnectionError`, which the loop retries like any dropped connection.
1965
+
1966
+ THE ONE RESEND THIS FILE MAKES, and it is not a retry in AGENTS.md's
1967
+ sense, which this file does not own: nothing was wrong with the request
1968
+ or the weather, the credential was stale, and the second attempt is made
1969
+ with a different one. Every retry for a failure the provider might not
1970
+ repeat is still `core/loop.py`'s, asked of `core/provider_errors.py`.
1971
+ """
1972
+ from core import chatgpt_auth
1973
+
1974
+ for attempt in (1, 2):
1975
+ try:
1976
+ return client.responses.create(**request)
1977
+ except chatgpt_auth.Transient as exc:
1978
+ raise ConnectionError(str(exc)) from exc
1979
+ except chatgpt_auth.ChatGPTAuthError:
1980
+ raise
1981
+ except Exception as exc:
1982
+ refusal = _chatgpt_refusal(getattr(exc, "body", None))
1983
+ if refusal is not None:
1984
+ raise refusal from exc
1985
+ if getattr(exc, "status_code", None) != 401:
1986
+ raise
1987
+ if attempt == 2:
1988
+ raise ChatGPTPlanError(
1989
+ "OpenAI refused the ChatGPT plan's sign-in again after a "
1990
+ "refresh. /connect chatgpt signs in again; the stored "
1991
+ "tokens are kept.") from exc
1992
+ try:
1993
+ chatgpt_auth.access_token(
1994
+ replacing=getattr(client, "api_key", None) or None)
1995
+ except chatgpt_auth.Transient as again:
1996
+ raise ConnectionError(str(again)) from again
1997
+ raise AssertionError("unreachable: the second attempt returns or raises")
1998
+
1999
+
2000
+ def _chatgpt_stream_failure(source) -> Exception:
2001
+ """An `error` event or a `response.failed` as an exception. Neither has
2002
+ been seen: nothing failed in slice 2a.
2003
+
2004
+ The openai SDK raises only on an event whose top-level `error` key is an
2005
+ object, which neither of these has, so they arrive as events and this
2006
+ reads them. CG10's type when the code names one; otherwise the rule
2007
+ `core/provider_errors.py` applies to a stream that failed after it
2008
+ opened, on every provider.
2009
+ """
2010
+ from core import provider_errors
2011
+
2012
+ body = _wire_dict(source)
2013
+ refusal = _chatgpt_refusal(body)
2014
+ if refusal is not None:
2015
+ return refusal
2016
+ code, _, message = _chatgpt_fields(body)
2017
+ text = (f"The ChatGPT plan's response failed ({code or 'no code'}): "
2018
+ f"{message or 'no message'}")
2019
+ if provider_errors.open_stream_error_is_transient(body):
2020
+ return ConnectionError(text)
2021
+ return ChatGPTPlanError(text)
2022
+
2023
+
2024
+ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2025
+ tools, reasoning: dict, supports_stream_usage: bool):
2026
+ """The CHATGPT branch of `call_model_stream`.
2027
+
2028
+ DISPATCH IS ON `event.type` ALONE. The SDK parses an event it does not
2029
+ know as whichever class its union tries first: slice 2a's
2030
+ `response.metadata` came out as a `ResponseAudioDeltaEvent` whose `type`
2031
+ still said `response.metadata`. A class check would have read it as
2032
+ audio; the string is the one thing that is right.
2033
+
2034
+ Never sent: `temperature` (refused, slice 0), `previous_response_id`
2035
+ (the whole history goes in `input`), `service_tier`, a hosted tool, and
2036
+ the Codex instructions the model list carries (CG3).
2037
+ """
2038
+ from core import chatgpt_auth
2039
+
2040
+ state = chatgpt_auth.status()
2041
+ if state.signed_in and not state.plan_usage:
2042
+ raise ChatGPTNotEligible(
2043
+ "This ChatGPT sign-in did not share the plan: OpenAI did not "
2044
+ "grant chatgpt.tokens.use.direct, so nothing is sent on it (CG6). "
2045
+ "/connect chatgpt signs in again.")
2046
+ request = dict(model=model, instructions=system_prompt, input=items,
2047
+ store=False, stream=True,
2048
+ max_output_tokens=config.MAX_TOKENS)
2049
+ if tools:
2050
+ request["tools"] = tools
2051
+ request.update(reasoning)
2052
+
2053
+ stream = _chatgpt_open(client, request)
2054
+ text_parts: list = []
2055
+ pending_calls: list = []
2056
+ reasoning_items: list = []
2057
+ # None rather than 0, for the Google branch's reason (D21).
2058
+ usage = {"input_tokens": None, "output_tokens": None}
2059
+ finish_reason = None
2060
+ summary_started = False
2061
+ try:
2062
+ for event in stream:
2063
+ kind = getattr(event, "type", None)
2064
+ if kind == "response.output_text.delta":
2065
+ delta = getattr(event, "delta", None)
2066
+ if isinstance(delta, str) and delta:
2067
+ text_parts.append(delta)
2068
+ yield StreamToken(text_delta=delta)
2069
+ elif kind == "response.reasoning_summary_part.added":
2070
+ # §38: a summary in several parts reads as paragraphs.
2071
+ if summary_started:
2072
+ yield StreamToken(thinking_delta="\n\n")
2073
+ summary_started = True
2074
+ elif kind == "response.reasoning_summary_text.delta":
2075
+ delta = getattr(event, "delta", None)
2076
+ if isinstance(delta, str) and delta:
2077
+ yield StreamToken(thinking_delta=delta)
2078
+ elif kind == "response.output_item.done":
2079
+ item = getattr(event, "item", None)
2080
+ item_type = getattr(item, "type", None)
2081
+ if item_type == "function_call":
2082
+ pending_calls.append(item)
2083
+ elif item_type == "reasoning":
2084
+ reasoning_items.append(_wire_dict(item))
2085
+ elif kind in ("response.completed", "response.incomplete"):
2086
+ response = getattr(event, "response", None)
2087
+ usage_obj = getattr(response, "usage", None)
2088
+ for key in ("input_tokens", "output_tokens"):
2089
+ reported = _token_count(usage_obj, key)
2090
+ if reported is not None:
2091
+ usage[key] = reported
2092
+ details = getattr(response, "incomplete_details", None)
2093
+ if getattr(details, "reason", None) == "max_output_tokens":
2094
+ finish_reason = "length"
2095
+ elif kind == "response.failed":
2096
+ raise _chatgpt_stream_failure(
2097
+ getattr(getattr(event, "response", None), "error", None))
2098
+ elif kind == "error":
2099
+ raise _chatgpt_stream_failure(event)
2100
+ except Exception as exc:
2101
+ # An error the SDK raised mid-stream may still carry a code CG10
2102
+ # names; anything else, ours included, goes up as it is.
2103
+ refusal = _chatgpt_refusal(getattr(exc, "body", None))
2104
+ if refusal is None:
2105
+ raise
2106
+ raise refusal from exc
2107
+ finally:
2108
+ close = getattr(stream, "close", None)
2109
+ if callable(close):
2110
+ close()
2111
+
2112
+ usage = _stream_usage("CHATGPT", usage, supports_stream_usage)
2113
+ calls = []
2114
+ for item in pending_calls:
2115
+ name = getattr(item, "name", None) or ""
2116
+ parsed, parse_error = _tool_arguments(
2117
+ getattr(item, "arguments", None) or "", name, finish_reason)
2118
+ if parse_error is not None:
2119
+ logger.warning(
2120
+ "%s: %s (finish_reason=%r)", name, parse_error, finish_reason)
2121
+ calls.append(ToolCallRequest(
2122
+ # The id rule the other branches keep (batch 76).
2123
+ id=getattr(item, "call_id", None) or str(uuid4()),
2124
+ name=name, input=parsed, parse_error=parse_error))
2125
+ yield StreamToken(final_response=ModelResponse(
2126
+ text="".join(text_parts), tool_calls=calls, usage=usage,
2127
+ thinking=_thinking_record("CHATGPT", model, reasoning_items),
2128
+ ))
2129
+
2130
+
2131
+ # ============================================================================
2132
+ # ---- Streaming call + helpers -----------------------------------------------
2133
+ # ============================================================================
2134
+
2135
+ def call_model_stream(
2136
+ client,
2137
+ provider_name: str,
2138
+ model: str,
2139
+ messages: list[dict],
2140
+ system_prompt: str,
2141
+ tool_schemas: list[dict],
2142
+ temperature: Optional[float] = None,
2143
+ effort: Optional[str] = None,
2144
+ ):
2145
+ """The one model call, for every provider. Yields StreamToken
2146
+ events: text_delta for incremental text, thinking_delta for
2147
+ incremental reasoning text where the provider sends any (§38 O2),
2148
+ final_response for the terminal ModelResponse with accumulated tool
2149
+ calls and usage.
2150
+
2151
+ Four provider implementations — Anthropic typed events, Google
2152
+ chunked candidates, OpenAI-compatible index-accumulated tool-call
2153
+ fragments, and since ROADMAP_v3 §83 the ChatGPT plan's Responses events
2154
+ (_chatgpt_stream) — which must agree with each other about the
2155
+ ModelResponse they produce for the same inputs.
2156
+
2157
+ There used to be a non-streaming `call_model()` beside this, and this
2158
+ docstring used to promise the two were identical. They were not: it
2159
+ set ModelResponse.raw and no streaming branch did, which is what a
2160
+ second implementation nobody runs accumulates (#38). It is gone, and
2161
+ with it `raw`; the only thing left to keep in step is the three
2162
+ branches below.
2163
+
2164
+ D21 (usage-or-raise): if the provider is marked as supporting stream
2165
+ usage but the stream completes with zero usage, raise rather than
2166
+ silently reporting zero (which disables budget enforcement and §21's
2167
+ compaction trigger).
2168
+ """
2169
+ # Read once so every branch applies the same D21 usage-or-raise rule --
2170
+ # all three of them, since audit #40. This comment used to claim that in
2171
+ # its first sentence and take it back in the second ("the flag only gates
2172
+ # the Google and OpenAI-compatible branches"), which left the one
2173
+ # provider whose example config ships the flag `true` as the one provider
2174
+ # where setting it did nothing.
2175
+ provider_data = load_provider_data()
2176
+ supports_stream_usage = provider_data.get(provider_name, {}).get(
2177
+ "supports_stream_usage", False
2178
+ )
2179
+ # §44. Whether this OpenAI-compatible provider accepts its own
2180
+ # reasoning back on the next request. supports_stream_usage's
2181
+ # precedent: a per-provider fact that cannot be discovered and must not
2182
+ # be guessed, so it lives beside the endpoint it describes and defaults
2183
+ # to the conservative answer.
2184
+ echoes_reasoning = provider_data.get(provider_name, {}).get(
2185
+ "echoes_reasoning", False
2186
+ )
2187
+
2188
+ translated_messages = _messages_for_provider(
2189
+ provider_name, messages, model, echoes_reasoning,
2190
+ images=accepts_images(provider_name))
2191
+ sampling = _sampling_kwargs(provider_name, model, temperature, effort)
2192
+ thinking = _thinking_for_provider(provider_name, effort)
2193
+
2194
+ if provider_name == "CHATGPT":
2195
+ # ROADMAP_v3 §83. `sampling` is always {} here: _sampling_kwargs
2196
+ # drops a temperature for this provider, which the route refuses.
2197
+ yield from _chatgpt_stream(
2198
+ client, model, translated_messages, system_prompt,
2199
+ _tools_for_provider(provider_name, tool_schemas), thinking,
2200
+ supports_stream_usage)
2201
+ return
2202
+
2203
+ if provider_name == "ANTHROPIC":
2204
+ stream_kwargs = dict(
2205
+ model=model,
2206
+ max_tokens=config.MAX_TOKENS,
2207
+ system=system_prompt,
2208
+ messages=translated_messages,
2209
+ tools=_tools_for_provider(provider_name, tool_schemas),
2210
+ )
2211
+ stream_kwargs.update(sampling)
2212
+ stream_kwargs.update(thinking)
2213
+
2214
+ with client.messages.stream(**stream_kwargs) as stream:
2215
+ # §38 O3. Iterating the STREAM rather than stream.text_stream,
2216
+ # because text_stream yields text deltas only and there is no
2217
+ # way to have both: `text_stream` is an instance attribute
2218
+ # built from the same underlying iterator in MessageStream's
2219
+ # __init__, so consuming one consumes the other.
2220
+ #
2221
+ # The SDK emits its own synthetic events beside the raw ones --
2222
+ # TextEvent(type="text", text=<delta>) and
2223
+ # ThinkingEvent(type="thinking", thinking=<delta>) -- which is
2224
+ # why this reads two attribute names rather than unpacking
2225
+ # content_block_delta by hand. Verified against the pinned
2226
+ # anthropic (0.116.0, and 2.1.0 since batch 234) rather than
2227
+ # assumed (D22), and pinned in tests/test_sdk_conformance.py.
2228
+ #
2229
+ # Every other event kind is ignored on purpose: `text` is the
2230
+ # accumulated answer read off get_final_message() below, not
2231
+ # off these deltas, so nothing here can change what this
2232
+ # branch returns.
2233
+ for ev in stream:
2234
+ kind = getattr(ev, "type", None)
2235
+ if kind == "text":
2236
+ yield StreamToken(text_delta=ev.text)
2237
+ elif kind == "thinking":
2238
+ yield StreamToken(thinking_delta=ev.thinking)
2239
+ final_msg = stream.get_final_message()
2240
+ text = "\n".join(
2241
+ b.text for b in final_msg.content if b.type == "text"
2242
+ )
2243
+ calls = [
2244
+ ToolCallRequest(id=b.id, name=b.name, input=b.input)
2245
+ for b in final_msg.content if b.type == "tool_use"
2246
+ ]
2247
+ # model_dump() rather than a hand-built dict: what goes back on
2248
+ # the wire has to be what came off it, field for field, or the
2249
+ # signature does not verify. redacted_thinking is included for
2250
+ # the same reason -- it is opaque to us and meaningful to the
2251
+ # model, so dropping it would silently break a turn that had
2252
+ # one.
2253
+ thinking_blocks = [
2254
+ b.model_dump() for b in final_msg.content
2255
+ if b.type in ("thinking", "redacted_thinking")
2256
+ ]
2257
+ usage_obj = getattr(final_msg, "usage", None)
2258
+ usage = {
2259
+ "input_tokens": _token_count(usage_obj, "input_tokens"),
2260
+ "output_tokens": _token_count(usage_obj, "output_tokens"),
2261
+ }
2262
+
2263
+ # D21 parity with the other two branches (audit #40). This branch
2264
+ # used to be exempt on the reasoning that get_final_message() always
2265
+ # carries usage -- which is very likely right for anthropic==0.116.0,
2266
+ # and is exactly the kind of assumption D21 exists because nobody can
2267
+ # verify from inside. The getattr defaults that used to be above were
2268
+ # the softened form D21's own note forbids, so on the DEFAULT
2269
+ # provider an SDK field rename would have zeroed the budget silently,
2270
+ # disabling both the budget stop condition and §21's compaction
2271
+ # trigger. That is the mcp v1->v2 failure mode, and #35 is this
2272
+ # file's live example of it.
2273
+ #
2274
+ # Honouring the flag rather than always raising keeps it meaning ONE
2275
+ # thing on all three providers, which is the coherence #40 is about;
2276
+ # providers.json.example ships it true for ANTHROPIC, so the default
2277
+ # posture is the checked one, and a proxy that genuinely omits usage
2278
+ # can still opt out instead of being unable to run.
2279
+ #
2280
+ # Batch 147: the rule itself, and the coercion that makes `usage`
2281
+ # two ints, are in `_stream_usage` -- one copy for three branches
2282
+ # that carried three.
2283
+ usage = _stream_usage(provider_name, usage, supports_stream_usage)
2284
+
2285
+ yield StreamToken(final_response=ModelResponse(
2286
+ text=text, tool_calls=calls, usage=usage,
2287
+ thinking=_thinking_record(provider_name, model, thinking_blocks),
2288
+ ))
2289
+ return
2290
+
2291
+ if provider_name == "GOOGLE":
2292
+ from google.genai import types as genai_types
2293
+ genai_config_kwargs = dict(
2294
+ system_instruction=system_prompt,
2295
+ tools=_tools_for_provider(provider_name, tool_schemas),
2296
+ max_output_tokens=config.MAX_TOKENS,
2297
+ )
2298
+ genai_config_kwargs.update(sampling)
2299
+ genai_config_kwargs.update(thinking)
2300
+
2301
+ text_parts = []
2302
+ calls = []
2303
+ # §82 (GS2). One block per function call, read off the part that
2304
+ # carried the call: Gemini 3 refuses the next request unless each
2305
+ # call goes back with the signature it came with.
2306
+ signatures = []
2307
+ # None rather than 0: "not reported" has to stay distinguishable
2308
+ # from "reported as zero" until D21 has looked at it, or the
2309
+ # partial-report case the widened rule exists for arrives here
2310
+ # already coerced and indistinguishable (batch 147).
2311
+ usage = {"input_tokens": None, "output_tokens": None}
2312
+
2313
+ for chunk in client.models.generate_content_stream(
2314
+ model=model,
2315
+ contents=translated_messages,
2316
+ config=genai_types.GenerateContentConfig(**genai_config_kwargs),
2317
+ ):
2318
+ candidate = chunk.candidates[0] if chunk.candidates else None
2319
+ content = candidate.content if candidate else None
2320
+ # `or []`: Content.parts is Optional on the pinned type, and a
2321
+ # chunk can carry a content with no parts at all.
2322
+ parts = (content.parts if content else None) or []
2323
+ for p in parts:
2324
+ if p.text is not None:
2325
+ text_parts.append(p.text)
2326
+ yield StreamToken(text_delta=p.text)
2327
+ if p.function_call is not None:
2328
+ fc = p.function_call
2329
+ call_id = fc.id or str(uuid4())
2330
+ calls.append(ToolCallRequest(
2331
+ id=call_id,
2332
+ name=fc.name,
2333
+ input=fc.args or {},
2334
+ ))
2335
+ # getattr: the field is on every pinned Part
2336
+ # (test_sdk_conformance asks the real one), but not on
2337
+ # the bare namespaces the stream tests build parts from.
2338
+ signatures.append(_google_signature_block(
2339
+ call_id, getattr(p, "thought_signature", None)))
2340
+ # PER FIELD, and only when the field was reported. The
2341
+ # guard used to be `if usage_meta:` -- which passes for a bare
2342
+ # instance, because every field is Optional and the object is
2343
+ # truthy anyway -- and then overwrote both counts with
2344
+ # whatever it found, None included. A chunk that carries
2345
+ # usage_metadata without a count now leaves an earlier chunk's
2346
+ # figure alone: reported beats unreported whatever the order,
2347
+ # which is the only rule that does not depend on which chunk
2348
+ # the provider chose to put the totals on.
2349
+ usage_meta = getattr(chunk, "usage_metadata", None)
2350
+ if usage_meta is not None:
2351
+ for key, attribute in (
2352
+ ("input_tokens", "prompt_token_count"),
2353
+ ("output_tokens", "candidates_token_count")):
2354
+ reported = _token_count(usage_meta, attribute)
2355
+ if reported is not None:
2356
+ usage[key] = reported
2357
+
2358
+ # D21, in the one place all three branches read it (batch 147).
2359
+ # This is the branch the nullable-field defect was found in: the
2360
+ # pinned google-genai declares every usage field Optional[int], so
2361
+ # `usage` could leave here holding None and the raise could not
2362
+ # fire -- `None != 0`.
2363
+ usage = _stream_usage(provider_name, usage, supports_stream_usage)
2364
+
2365
+ yield StreamToken(final_response=ModelResponse(
2366
+ text="".join(text_parts), tool_calls=calls, usage=usage,
2367
+ thinking=_thinking_record(provider_name, model, signatures),
2368
+ ))
2369
+ return
2370
+
2371
+ # OpenAI-compatible path (supports_stream_usage already read above)
2372
+ full_messages = [{"role": "system", "content": system_prompt}] + translated_messages
2373
+ openai_kwargs = dict(
2374
+ model=model,
2375
+ messages=full_messages,
2376
+ max_completion_tokens=config.MAX_TOKENS,
2377
+ tools=_tools_for_provider(provider_name, tool_schemas),
2378
+ stream=True,
2379
+ )
2380
+ openai_kwargs.update(sampling)
2381
+ openai_kwargs.update(thinking)
2382
+ if supports_stream_usage:
2383
+ openai_kwargs["stream_options"] = {"include_usage": True}
2384
+
2385
+ text_parts = []
2386
+ reasoning_parts = []
2387
+ tool_fragments: dict[int, dict] = {}
2388
+ # None, for the reason the Google branch states: D21 cannot tell an
2389
+ # unreported count from a zero one once it has been coerced.
2390
+ usage = {"input_tokens": None, "output_tokens": None}
2391
+
2392
+ finish_reason = None
2393
+ for chunk in client.chat.completions.create(**openai_kwargs):
2394
+ if chunk.choices:
2395
+ # W4 (#37): free -- chunk.choices[0] is already read here. The
2396
+ # provider sets this on the last content chunk, and `or
2397
+ # finish_reason` keeps it once seen because the usage chunk
2398
+ # that follows carries none. getattr because a chunk is only
2399
+ # required to have `delta`.
2400
+ choice = chunk.choices[0]
2401
+ finish_reason = getattr(choice, "finish_reason", None) or finish_reason
2402
+ delta = choice.delta
2403
+ if delta.content:
2404
+ text_parts.append(delta.content)
2405
+ yield StreamToken(text_delta=delta.content)
2406
+ # §38 O3. Reasoning text, where the provider sends any. There
2407
+ # is no standard field: DeepSeek, Qwen and Z.AI use
2408
+ # `reasoning_content`, OpenRouter and Groq use `reasoning`,
2409
+ # and OpenAI's own endpoint sends neither. openai's ChoiceDelta
2410
+ # is extra="allow" (pinned in test_sdk_conformance.py), so an
2411
+ # unknown-to-the-SDK field arrives as a real attribute.
2412
+ #
2413
+ # NEVER appended to text_parts: reasoning is not the answer,
2414
+ # and folding it in would change every ModelResponse this
2415
+ # branch returns and put reasoning into the thread as though
2416
+ # the model had said it. It is accumulated SEPARATELY instead
2417
+ # (batch 44), into ModelResponse.thinking, where it is kept as
2418
+ # this provider's own field name rather than as prose -- an
2419
+ # echo back on the wire has to spell it the way the provider
2420
+ # spelled it.
2421
+ reasoning = (getattr(delta, "reasoning_content", None)
2422
+ or getattr(delta, "reasoning", None))
2423
+ if isinstance(reasoning, str) and reasoning:
2424
+ reasoning_parts.append(reasoning)
2425
+ yield StreamToken(thinking_delta=reasoning)
2426
+ if delta.tool_calls:
2427
+ for tc_delta in delta.tool_calls:
2428
+ idx = tc_delta.index
2429
+ if idx not in tool_fragments:
2430
+ tool_fragments[idx] = {
2431
+ "id": "", "name_parts": [], "arguments_parts": [],
2432
+ }
2433
+ if tc_delta.id:
2434
+ tool_fragments[idx]["id"] = tc_delta.id
2435
+ # Accumulate name like arguments: some v1-compatible
2436
+ # providers split function.name across deltas, so a
2437
+ # last-write-wins assignment would corrupt the name.
2438
+ if tc_delta.function and tc_delta.function.name:
2439
+ tool_fragments[idx]["name_parts"].append(
2440
+ tc_delta.function.name
2441
+ )
2442
+ if tc_delta.function and tc_delta.function.arguments:
2443
+ tool_fragments[idx]["arguments_parts"].append(
2444
+ tc_delta.function.arguments
2445
+ )
2446
+ # Per field and only when reported -- the Google branch's shape,
2447
+ # for its reason, and because `CompletionUsage` is parsed by the
2448
+ # SDK's construct() and so can hold None against an `int`
2449
+ # annotation (batch 147).
2450
+ usage_obj = getattr(chunk, "usage", None)
2451
+ if usage_obj is not None:
2452
+ for key, attribute in (("input_tokens", "prompt_tokens"),
2453
+ ("output_tokens", "completion_tokens")):
2454
+ reported = _token_count(usage_obj, attribute)
2455
+ if reported is not None:
2456
+ usage[key] = reported
2457
+
2458
+ # D21: if the provider is marked as supporting stream usage but we
2459
+ # got no usable usage, the stream was likely interrupted before the
2460
+ # final usage chunk arrived. Raise rather than silently reporting zero.
2461
+ # One copy for three branches since batch 147.
2462
+ usage = _stream_usage(provider_name, usage, supports_stream_usage)
2463
+
2464
+ calls = []
2465
+ for idx in sorted(tool_fragments):
2466
+ frag = tool_fragments[idx]
2467
+ name = "".join(frag["name_parts"])
2468
+ parsed, parse_error = _tool_arguments(
2469
+ "".join(frag["arguments_parts"]), name, finish_reason)
2470
+ if parse_error is not None:
2471
+ logger.warning(
2472
+ "%s: %s (finish_reason=%r)", name, parse_error, finish_reason)
2473
+ calls.append(ToolCallRequest(
2474
+ # `or str(uuid4())` for the Google branch's reason, which this
2475
+ # one was missing (batch 76). The fragment's id starts as ""
2476
+ # and is filled only if some delta carries one, so a provider
2477
+ # that streams parallel calls without ids hands back two
2478
+ # requests that are EQUAL on the field everything downstream
2479
+ # pairs by: the batch's own bookkeeping, `_spawn_threads` in
2480
+ # the TUI, and `parent_call_id` in storage. The generated id
2481
+ # is what goes back on the wire too, on BOTH halves of the
2482
+ # pair -- `add_assistant_message` persists the call and
2483
+ # `add_tool_result` answers it, so the two agree by
2484
+ # construction, which is all M4/D20 pairing needs. That is
2485
+ # also why "" was not the safer answer: a provider that
2486
+ # validates `tool_call_id` at all rejects an empty one.
2487
+ id=frag["id"] or str(uuid4()),
2488
+ name=name, input=parsed, parse_error=parse_error,
2489
+ ))
2490
+
2491
+ # ONE block, not one per delta. There is no block structure on this
2492
+ # wire -- reasoning arrives as a flat string of deltas -- so the record
2493
+ # is the concatenation under the field name the request would use to
2494
+ # send it back. `type` names the shape for _messages_for_provider;
2495
+ # nothing about it is the provider's, which is why it is spelled after
2496
+ # the field rather than after Anthropic's "thinking".
2497
+ reasoning_blocks = ([{"type": "reasoning_content",
2498
+ "text": "".join(reasoning_parts)}]
2499
+ if reasoning_parts else [])
2500
+
2501
+ yield StreamToken(final_response=ModelResponse(
2502
+ text="".join(text_parts), tool_calls=calls, usage=usage,
2503
+ thinking=_thinking_record(provider_name, model, reasoning_blocks),
2504
+ ))
2505
+
2506
+
2507
+ # ===========================================================================
2508
+ # ---- Embeddings (ROADMAP_v2 §45, SQ2/SQ7) ---------------------------------
2509
+ # ===========================================================================
2510
+ #
2511
+ # §33's rule is that this file is where a model call lives, and an
2512
+ # embedding is a model call. It shares `api_initialization` and its client
2513
+ # cache with the chat path, so an embedder on a provider already in use
2514
+ # costs no second client.
2515
+ #
2516
+ # WHAT THIS DELIBERATELY DOES NOT SHARE. No streaming, no tool
2517
+ # translation, no `effort`, no context-window check, and no entry in
2518
+ # `ModelResponse`: none of those mean anything for a call that takes
2519
+ # strings and returns vectors. `EmbeddingResult` is its own small shape
2520
+ # for the same reason ToolCallRequest is -- widening ModelResponse with
2521
+ # three fields that are null on every chat turn is how a response object
2522
+ # stops describing anything.
2523
+
2524
+
2525
+ class EmbeddingError(RuntimeError):
2526
+ """An embedding call that could not produce usable vectors.
2527
+
2528
+ ITS OWN TYPE, so §45's scoring stage can catch exactly this and fall
2529
+ back to the model's own similarity (SQ10) without also swallowing a
2530
+ programming error from inside its own chunker. The message names the
2531
+ provider and the model, because the two most common causes -- a
2532
+ provider with no embeddings endpoint, and a chat model slug passed to
2533
+ one -- are both fixed by changing one of those two words.
2534
+ """
2535
+
2536
+
2537
+ @dataclass
2538
+ class EmbeddingResult:
2539
+ """Vectors for the texts that were sent, in the order they were sent.
2540
+
2541
+ `usage` mirrors ModelResponse's shape but carries input tokens only:
2542
+ an embedding call produces no output tokens, and reporting a zero
2543
+ under a key that means something elsewhere would put embedding spend
2544
+ into a total that is documented as billed input+output of model calls.
2545
+ §45 counts it separately and says so.
2546
+ """
2547
+
2548
+ vectors: list = field(default_factory=list)
2549
+ model: str = ""
2550
+ provider_name: str = ""
2551
+ usage: dict = field(default_factory=lambda: {"input_tokens": 0})
2552
+
2553
+ @property
2554
+ def dimension(self) -> int:
2555
+ return len(self.vectors[0]) if self.vectors else 0
2556
+
2557
+
2558
+ # Providers with no embeddings endpoint at all, where the failure is worth
2559
+ # naming rather than surfacing as a 404 from inside a research run.
2560
+ #
2561
+ # ANTHROPIC IS NOT AN OVERSIGHT. There is no Anthropic embeddings API; the
2562
+ # recommended route is a third-party embedder, which this harness reaches
2563
+ # as its own provider entry. OPENROUTER proxies chat completions only.
2564
+ # CHATGPT is the plan, which answers on the Responses API and nothing else
2565
+ # (ROADMAP_v3 §83, CG3).
2566
+ #
2567
+ # INCOMPLETE ON PURPOSE, and safe when incomplete -- the same posture as
2568
+ # MODELS_REJECTING_SAMPLING_PARAMS. An unlisted provider that turns out to
2569
+ # have no endpoint fails loudly on the probe `/embedder` runs at selection
2570
+ # time, which is a measurement rather than a guess and is why there is no
2571
+ # `supports_embeddings` table to keep in step with the world.
2572
+ PROVIDERS_WITHOUT_EMBEDDINGS = frozenset({"ANTHROPIC", "OPENROUTER", "CHATGPT"})
2573
+
2574
+
2575
+ def embed_texts(provider_name: str, model: str, texts,
2576
+ *, prefix: str = "", task_type: str = "") -> EmbeddingResult:
2577
+ """Embed `texts` with `model` on `provider_name`.
2578
+
2579
+ `prefix` is prepended to every text in this call. Asymmetric embedders
2580
+ -- e5's `"query: "` / `"passage: "`, BGE's instruction prefix -- score
2581
+ materially worse without it and produce no error at all, so it is
2582
+ configuration rather than something inferred from a model slug.
2583
+ `task_type` is Google's equivalent (`RETRIEVAL_QUERY` /
2584
+ `RETRIEVAL_DOCUMENT`) and is ignored elsewhere.
2585
+
2586
+ Raises EmbeddingError, never a provider exception: the caller's whole
2587
+ contract (SQ10) is to degrade to a documented fallback, and it cannot
2588
+ do that against an exception type that differs per SDK.
2589
+ """
2590
+ items = [f"{prefix}{text}" for text in texts]
2591
+ if not items:
2592
+ return EmbeddingResult(model=model, provider_name=provider_name)
2593
+
2594
+ if provider_name in PROVIDERS_WITHOUT_EMBEDDINGS:
2595
+ raise EmbeddingError(
2596
+ f"{provider_name} has no embeddings endpoint. Configure an "
2597
+ f"embedder on a provider that does -- /embedder <PROVIDER> "
2598
+ f"<model> -- or leave it unset to score similarity with the "
2599
+ f"grounding model itself."
2600
+ )
2601
+
2602
+ try:
2603
+ client = api_initialization(provider_name)
2604
+ except ValueError as exc:
2605
+ raise EmbeddingError(str(exc)) from exc
2606
+
2607
+ try:
2608
+ if provider_name == "GOOGLE":
2609
+ vectors, tokens = _embed_google(client, model, items, task_type)
2610
+ else:
2611
+ vectors, tokens = _embed_openai_compatible(client, model, items)
2612
+ except EmbeddingError:
2613
+ raise
2614
+ except Exception as exc:
2615
+ raise EmbeddingError(
2616
+ f"{provider_name} embeddings call failed for model {model!r}: "
2617
+ f"{type(exc).__name__}: {exc}"
2618
+ ) from exc
2619
+
2620
+ _check_vectors(provider_name, model, vectors, len(items))
2621
+ return EmbeddingResult(
2622
+ vectors=vectors, model=model, provider_name=provider_name,
2623
+ usage={"input_tokens": tokens},
2624
+ )
2625
+
2626
+
2627
+ def _embed_openai_compatible(client, model, items):
2628
+ """`/v1/embeddings`, which is what every is_v1_compatible provider
2629
+ exposes if it exposes embeddings at all.
2630
+
2631
+ SORTED BY INDEX rather than trusted in arrival order. The response
2632
+ carries an explicit `index` per item precisely because the order is
2633
+ not guaranteed, and a silently permuted batch pairs every claim with
2634
+ another claim's vector -- a wrong number with no symptom, which is the
2635
+ failure this whole section exists to stop producing.
2636
+ """
2637
+ response = client.embeddings.create(model=model, input=items)
2638
+ data = sorted(response.data, key=lambda item: getattr(item, "index", 0))
2639
+ vectors = [list(item.embedding) for item in data]
2640
+ usage = getattr(response, "usage", None)
2641
+ return vectors, int(getattr(usage, "prompt_tokens", 0) or 0)
2642
+
2643
+
2644
+ def _embed_google(client, model, items, task_type):
2645
+ """google-genai's `embed_content`, which takes the batch as
2646
+ `contents` and returns `embeddings[].values`.
2647
+
2648
+ The config object is built ONLY when a task type was given, and
2649
+ through getattr rather than a direct import of the types module: a
2650
+ pinned SDK that does not carry EmbedContentConfig would otherwise turn
2651
+ an optional tuning parameter into an import error on every Google
2652
+ embedding call. D22's rule -- check the dependency's real shape, do
2653
+ not assume it.
2654
+ """
2655
+ kwargs = {"model": model, "contents": items}
2656
+ if task_type:
2657
+ from google.genai import types as genai_types
2658
+ config_cls = getattr(genai_types, "EmbedContentConfig", None)
2659
+ if config_cls is not None:
2660
+ kwargs["config"] = config_cls(task_type=task_type)
2661
+ else:
2662
+ logger.warning(
2663
+ "Ignoring embedder task_type=%r: the installed google-genai "
2664
+ "has no EmbedContentConfig.", task_type)
2665
+
2666
+ response = client.models.embed_content(**kwargs)
2667
+ vectors = [list(item.values) for item in (response.embeddings or [])]
2668
+ # google-genai reports embedding token usage inconsistently across
2669
+ # releases; absent is reported as zero rather than guessed at.
2670
+ metadata = getattr(response, "metadata", None)
2671
+ return vectors, int(getattr(metadata, "billable_character_count", 0) or 0)
2672
+
2673
+
2674
+ def _check_vectors(provider_name, model, vectors, expected) -> None:
2675
+ """Four ways a successful response is still unusable.
2676
+
2677
+ The first three produce a WRONG NUMBER rather than an error downstream:
2678
+ a short batch pairs texts with the wrong vectors, a ragged batch makes
2679
+ cosine compare different spaces, and an empty vector makes every
2680
+ cosine zero -- which reads as "no source supports this claim" and is
2681
+ indistinguishable from a real finding.
2682
+
2683
+ The fourth (batch 219, #218) is a component that is not a finite
2684
+ number. A string or None raised TypeError in `l2_normalize`, outside
2685
+ every handler, and flipped a run that had already grounded and scored
2686
+ to `status='failed'`; a NaN or an infinity raised nothing and scored
2687
+ NaN, the wrong-number class again. As an EmbeddingError it takes the
2688
+ path every other unusable response takes: the scorer gives up for the
2689
+ run and the stage falls back, with the cause in the trace.
2690
+ """
2691
+ if len(vectors) != expected:
2692
+ raise EmbeddingError(
2693
+ f"{provider_name} returned {len(vectors)} embedding(s) for "
2694
+ f"{expected} input(s) with model {model!r}.")
2695
+ if not all(isinstance(v, (list, tuple))
2696
+ and all(_is_finite_number(c) for c in v) for v in vectors):
2697
+ raise EmbeddingError(
2698
+ f"{provider_name} returned an embedding whose components are not "
2699
+ f"all finite numbers for model {model!r}.")
2700
+ dimensions = {len(v) for v in vectors}
2701
+ if len(dimensions) > 1:
2702
+ raise EmbeddingError(
2703
+ f"{provider_name} returned embeddings of differing dimensions "
2704
+ f"{sorted(dimensions)} for model {model!r}.")
2705
+ if dimensions == {0}:
2706
+ raise EmbeddingError(
2707
+ f"{provider_name} returned empty embeddings for model "
2708
+ f"{model!r}.")
2709
+
2710
+
2711
+ def _is_finite_number(component) -> bool:
2712
+ """An int or a float, not a bool, and not NaN or an infinity."""
2713
+ return (isinstance(component, (int, float))
2714
+ and not isinstance(component, bool)
2715
+ and math.isfinite(component))