@yahyahammad/venastine 0.3.15 → 0.3.17

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.
package/core/client.py CHANGED
@@ -10,6 +10,7 @@ from uuid import UUID, uuid4
10
10
 
11
11
  import config
12
12
  import credentials
13
+ from core import provider_errors
13
14
  from credentials import (
14
15
  load_provider_data,
15
16
  no_providers_message,
@@ -41,6 +42,11 @@ logger = logging.getLogger(__name__)
41
42
  # rebuild the client (and re-read the credentials file) every time.
42
43
  _client_cache: dict[str, object] = {}
43
44
 
45
+ #: What an OpenAI-compatible provider with an empty API_KEY is sent instead
46
+ #: (batch 258; see api_initialization). Says what it is, to anyone reading
47
+ #: a server's log, and is not shaped like any provider's real key.
48
+ KEYLESS = "venastine-no-key-configured"
49
+
44
50
 
45
51
  def api_initialization(provider_name: str):
46
52
  if provider_name in _client_cache:
@@ -70,7 +76,16 @@ def api_initialization(provider_name: str):
70
76
  client = _chatgpt_client()
71
77
  elif entry.get("is_v1_compatible", False):
72
78
  from openai import OpenAI
73
- client = OpenAI(base_url=entry["API_URL"], api_key=entry["API_KEY"],
79
+ # BATCH 258. An EMPTY key is sent as KEYLESS. openai 3.x refuses
80
+ # "" while the client is being built -- "Missing credentials ...
81
+ # set the OPENAI_API_KEY environment variable", measured on 3.45.0
82
+ # -- which broke the one configuration this harness says needs no
83
+ # key (credentials.missing_key_message: "unless it is a local
84
+ # endpoint that needs none"), and said so in another vendor's
85
+ # words. A local server ignores the placeholder; a remote one
86
+ # answers 401, and launch has already warned that the key is empty.
87
+ client = OpenAI(base_url=entry["API_URL"],
88
+ api_key=entry["API_KEY"] or KEYLESS,
74
89
  **_metered("openai"))
75
90
  elif provider_name == "GOOGLE":
76
91
  from google import genai
@@ -295,6 +310,17 @@ class ModelResponse:
295
310
  turn_billed_tokens: Optional[int] = None
296
311
  turn_new_tokens: Optional[int] = None
297
312
  turn_output_tokens: Optional[int] = None
313
+ # ROADMAP_v3 §97 (UF4). The usage keys THIS call's provider did not
314
+ # send, which `_stream_usage` coerced to 0 so the loop's arithmetic
315
+ # stays integer (D21). `/usage` reads it so a coerced zero is never
316
+ # shown as a count. A cache count needs no entry here: it is put in
317
+ # `usage` only when reported, so its absence already says so.
318
+ usage_unreported: tuple = ()
319
+ # §97 (UF4). This run's calls as a `core.usage_view.UsageTally`, set by
320
+ # `run_agent_conversation` and `wake_conversation` -- whose memory is
321
+ # built for the one run, so its tally is this turn's -- for the CLI's
322
+ # `/usage`, which keeps no memory between turns. None elsewhere.
323
+ turn_usage: Optional[object] = None
298
324
  # Batch 44 (§44). The turn's reasoning, as the PROVIDER'S OWN BLOCKS
299
325
  # rather than as the text §38 streams for display:
300
326
  #
@@ -482,6 +508,14 @@ def _stream_usage(provider_name: str, counts: dict,
482
508
  With the flag FALSE the coercion is all that happens, and 0 is the
483
509
  right answer there: the flag's whole purpose is to let a provider that
484
510
  genuinely omits usage run anyway.
511
+
512
+ RETURNS THE COERCED KEYS TOO (ROADMAP_v3 §97, UF4): `(usage,
513
+ unreported)`, where `unreported` names each count this made a 0 of,
514
+ for `ModelResponse.usage_unreported`. The 0 is right for the loop's
515
+ sums and wrong for `/usage`, which shows only what the provider sent;
516
+ one return keeps the two from being decided in two places. A cache
517
+ count (`CACHE_COUNTS`) is carried through only when it was reported --
518
+ nothing adds it, so it needs no zero.
485
519
  """
486
520
  reported_in = counts["input_tokens"]
487
521
  reported_out = counts["output_tokens"]
@@ -503,8 +537,56 @@ def _stream_usage(provider_name: str, counts: dict,
503
537
  f"supports_stream_usage=True, so this step's token "
504
538
  f"accounting would be short by it."
505
539
  )
506
- return {"input_tokens": reported_in or 0,
507
- "output_tokens": reported_out or 0}
540
+ usage = {"input_tokens": reported_in or 0,
541
+ "output_tokens": reported_out or 0}
542
+ for key in CACHE_COUNTS:
543
+ if counts.get(key) is not None:
544
+ usage[key] = counts[key]
545
+ unreported = tuple(name for name, value in
546
+ (("input_tokens", reported_in),
547
+ ("output_tokens", reported_out)) if value is None)
548
+ return usage, unreported
549
+
550
+
551
+ #: The cache counts a usage dict may carry (ROADMAP_v3 §97, UF4/UF5), each
552
+ #: present only when the provider reported it. Spelled the same on every
553
+ #: branch, whatever the SDK calls it, so `core/usage_view.py` reads one key.
554
+ CACHE_COUNTS = ("cache_read_tokens", "cache_write_tokens")
555
+
556
+ #: The Google branch's usage fields, each read per chunk and kept per its
557
+ #: own last report (batch 147's rule), then combined at the end of the
558
+ #: stream (§97, UF2). `tests/test_sdk_conformance.py` asks the pinned SDK
559
+ #: for every one.
560
+ _GOOGLE_COUNTS = ("prompt_token_count", "candidates_token_count",
561
+ "thoughts_token_count", "cached_content_token_count")
562
+
563
+
564
+ def _sum_reported(*values) -> Optional[int]:
565
+ """The sum of the counts that were reported, or None when none was.
566
+
567
+ For a figure a provider splits across fields that are each nullable:
568
+ Google's output, which is its candidates PLUS its thoughts (§97 UF2).
569
+ Not `sum(v or 0 ...)`, which would turn "reported nothing" into a zero
570
+ before D21 has looked at it -- batch 147's defect, one helper over.
571
+ """
572
+ reported = [value for value in values if value is not None]
573
+ return sum(reported) if reported else None
574
+
575
+
576
+ def _whole_prompt(input_tokens, cache_read, cache_write) -> Optional[int]:
577
+ """Input as the WHOLE prompt, on a branch that reports its cached part
578
+ apart (ROADMAP_v3 §97, UF5, the owner's choice).
579
+
580
+ The Anthropic SDK's `input_tokens` leaves out the tokens read from the
581
+ cache and the tokens written to it; the OpenAI-compatible and Google
582
+ counts include theirs. Adding them here, at the producer, is what makes
583
+ `billed`, `ctx` and the compaction trigger mean one thing on every
584
+ branch. None stays None: an input count the provider did not send is
585
+ D21's to judge, and a cache count alone is not an input count.
586
+ """
587
+ if input_tokens is None:
588
+ return None
589
+ return input_tokens + (cache_read or 0) + (cache_write or 0)
508
590
 
509
591
 
510
592
  # ============================================================================
@@ -1238,6 +1320,12 @@ def _messages_for_provider(provider_name: str, neutral_messages: list[dict],
1238
1320
  # Anthropic branch queries the API once per process rather than per call.
1239
1321
  _effort_levels_cache: dict[tuple[str, str], list[str]] = {}
1240
1322
 
1323
+ # (provider_name, model, level) whose drop effort_for has already reported.
1324
+ # Batch 258: a model that refused effort is recorded as taking none, and
1325
+ # effort_for then drops the chosen level on every turn -- said once, not
1326
+ # once per message.
1327
+ _effort_drops_said: set[tuple[str, str, str]] = set()
1328
+
1241
1329
  # (provider_name, model) -> context window in tokens, or None for "asked,
1242
1330
  # and this provider does not report one". Same lazy, once-per-process
1243
1331
  # posture as the effort cache above; see context_window_for() for why None
@@ -1422,9 +1510,13 @@ def effort_for(client, provider_name: str, model: str,
1422
1510
  "Could not verify effort %r for %s/%s; sending it unverified.",
1423
1511
  requested, provider_name, model)
1424
1512
  return requested
1425
- logger.warning(
1426
- "Dropping effort %r: %s/%s accepts %s. Sending no effort parameter.",
1427
- requested, provider_name, model, levels or "no effort control")
1513
+ said = (provider_name, model, requested)
1514
+ if said not in _effort_drops_said:
1515
+ _effort_drops_said.add(said)
1516
+ logger.warning(
1517
+ "Dropping effort %r: %s/%s accepts %s. Sending no effort "
1518
+ "parameter.", requested, provider_name, model,
1519
+ levels or "no effort control")
1428
1520
  return None
1429
1521
 
1430
1522
 
@@ -1689,7 +1781,16 @@ def _model_info(client, model):
1689
1781
  raise
1690
1782
  try:
1691
1783
  entries = list(listing())
1692
- except Exception:
1784
+ except Exception as listing_error:
1785
+ # BATCH 258: one exception to the rule below. `/models` is the
1786
+ # route EVERY OpenAI-compatible server has, so a page-not-found
1787
+ # there is not about this model -- it is the address, and the
1788
+ # most useful thing this lookup can say (core/provider_errors.
1789
+ # route_miss). The per-id route cannot carry that alone: some
1790
+ # providers have no such route for ids with a slash.
1791
+ if provider_errors.route_miss(listing_error):
1792
+ raise provider_errors.explain_route_miss(
1793
+ listing_error) from None
1693
1794
  # The listing is not a second opinion about the retrieve; it is
1694
1795
  # the same question by another route. Report the FIRST failure,
1695
1796
  # which is the one that names the endpoint the caller asked for.
@@ -2023,11 +2124,14 @@ def _chatgpt_open(client, request: dict):
2023
2124
  them (CG10). A refresh that could not be made at all is a
2024
2125
  `ConnectionError`, which the loop retries like any dropped connection.
2025
2126
 
2026
- THE ONE RESEND THIS FILE MAKES, and it is not a retry in AGENTS.md's
2027
- sense, which this file does not own: nothing was wrong with the request
2028
- or the weather, the credential was stale, and the second attempt is made
2029
- with a different one. Every retry for a failure the provider might not
2030
- repeat is still `core/loop.py`'s, asked of `core/provider_errors.py`.
2127
+ ONE OF THE TWO RESENDS THIS FILE MAKES, and neither is a retry in
2128
+ AGENTS.md's sense, which this file does not own: nothing was wrong with
2129
+ the request or the weather, the credential was stale, and the second
2130
+ attempt is made with a different one. The other is
2131
+ `_resend_without_effort` (batch 258), the same kind: a different
2132
+ request, never the same one again. Every retry for a failure the
2133
+ provider might not repeat is still `core/loop.py`'s, asked of
2134
+ `core/provider_errors.py`.
2031
2135
  """
2032
2136
  from core import chatgpt_auth
2033
2137
 
@@ -2149,6 +2253,15 @@ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2149
2253
  reported = _token_count(usage_obj, key)
2150
2254
  if reported is not None:
2151
2255
  usage[key] = reported
2256
+ # §97 (UF4). Part of `input_tokens` already on this API,
2257
+ # so UF5 adds nothing here; only what was sent is kept.
2258
+ cached = getattr(usage_obj, "input_tokens_details", None)
2259
+ for key, attribute in (("cache_read_tokens", "cached_tokens"),
2260
+ ("cache_write_tokens",
2261
+ "cache_write_tokens")):
2262
+ reported = _token_count(cached, attribute)
2263
+ if reported is not None:
2264
+ usage[key] = reported
2152
2265
  details = getattr(response, "incomplete_details", None)
2153
2266
  if getattr(details, "reason", None) == "max_output_tokens":
2154
2267
  finish_reason = "length"
@@ -2169,7 +2282,7 @@ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2169
2282
  if callable(close):
2170
2283
  close()
2171
2284
 
2172
- usage = _stream_usage("CHATGPT", usage, supports_stream_usage)
2285
+ usage, unreported = _stream_usage("CHATGPT", usage, supports_stream_usage)
2173
2286
  calls = []
2174
2287
  for item in pending_calls:
2175
2288
  name = getattr(item, "name", None) or ""
@@ -2184,6 +2297,7 @@ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2184
2297
  name=name, input=parsed, parse_error=parse_error))
2185
2298
  yield StreamToken(final_response=ModelResponse(
2186
2299
  text="".join(text_parts), tool_calls=calls, usage=usage,
2300
+ usage_unreported=unreported,
2187
2301
  thinking=_thinking_record("CHATGPT", model, reasoning_items),
2188
2302
  ))
2189
2303
 
@@ -2192,6 +2306,50 @@ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2192
2306
  # ---- Streaming call + helpers -----------------------------------------------
2193
2307
  # ============================================================================
2194
2308
 
2309
+ def _resend_without_effort(client, provider_name: str, model: str,
2310
+ kwargs: dict, thinking: dict, sampling: dict,
2311
+ temperature, effort: Optional[str], refusal):
2312
+ """Send an OpenAI-compatible request once more, without the reasoning
2313
+ effort a model refused, and return its stream (batch 258).
2314
+
2315
+ THE SECOND RESEND THIS FILE MAKES, and it is CG10's kind, not a retry:
2316
+ the request was wrong for this model, and the second attempt is a
2317
+ different request. `default_effort: high` ships, and a model with no
2318
+ `model_effort_levels` entry is assumed to take every level, so a local
2319
+ model that cannot reason was sent `reasoning_effort` on its first turn
2320
+ and refused it -- a local Ollama: `"llama3.2:3b" does not support
2321
+ thinking`, a 400 (measured). The owner chose to drop it and resend.
2322
+
2323
+ BELIEVED ONLY IF THE RESEND SUCCEEDS. `provider_errors.refuses_effort`
2324
+ matches widely, because no two servers word this alike; what makes
2325
+ that safe is here. A resend that fails too means the effort was not
2326
+ the cause, so the FIRST refusal is raised -- it is about the request
2327
+ the user's settings made -- and nothing is recorded. A resend that
2328
+ succeeds records the model as taking no effort for the life of the
2329
+ process (`_effort_levels`' cache), so effort_for drops the level from
2330
+ then on and the picker stops offering one.
2331
+
2332
+ `sampling` is rebuilt for no effort: on OPENAI the effort decides
2333
+ whether a temperature may be sent at all (`_sampling_kwargs`).
2334
+ """
2335
+ resend = {key: value for key, value in kwargs.items()
2336
+ if key not in thinking and key not in sampling}
2337
+ resend.update(_sampling_kwargs(provider_name, model, temperature, None))
2338
+ try:
2339
+ stream = client.chat.completions.create(**resend)
2340
+ except Exception:
2341
+ raise refusal from None
2342
+ _effort_levels_cache[(provider_name, model)] = []
2343
+ logger.warning(
2344
+ "%s/%s refused reasoning effort %r (%s). Sent again without it, "
2345
+ "which it accepted, so no effort is sent to this model again this "
2346
+ "session. To make that permanent, add %r: [] under "
2347
+ "model_effort_levels in config.yaml.",
2348
+ provider_name, model, effort, provider_errors.describe(refusal),
2349
+ model)
2350
+ return stream
2351
+
2352
+
2195
2353
  def call_model_stream(
2196
2354
  client,
2197
2355
  provider_name: str,
@@ -2315,9 +2473,19 @@ def call_model_stream(
2315
2473
  if b.type in ("thinking", "redacted_thinking")
2316
2474
  ]
2317
2475
  usage_obj = getattr(final_msg, "usage", None)
2476
+ # §97 (UF4, UF5). This SDK reports the cached part of the
2477
+ # prompt APART from `input_tokens`, so input is made the whole
2478
+ # prompt here, as every other branch's already is.
2479
+ cache_read = _token_count(usage_obj, "cache_read_input_tokens")
2480
+ cache_write = _token_count(usage_obj,
2481
+ "cache_creation_input_tokens")
2318
2482
  usage = {
2319
- "input_tokens": _token_count(usage_obj, "input_tokens"),
2483
+ "input_tokens": _whole_prompt(
2484
+ _token_count(usage_obj, "input_tokens"),
2485
+ cache_read, cache_write),
2320
2486
  "output_tokens": _token_count(usage_obj, "output_tokens"),
2487
+ "cache_read_tokens": cache_read,
2488
+ "cache_write_tokens": cache_write,
2321
2489
  }
2322
2490
 
2323
2491
  # D21 parity with the other two branches (audit #40). This branch
@@ -2340,10 +2508,12 @@ def call_model_stream(
2340
2508
  # Batch 147: the rule itself, and the coercion that makes `usage`
2341
2509
  # two ints, are in `_stream_usage` -- one copy for three branches
2342
2510
  # that carried three.
2343
- usage = _stream_usage(provider_name, usage, supports_stream_usage)
2511
+ usage, unreported = _stream_usage(provider_name, usage,
2512
+ supports_stream_usage)
2344
2513
 
2345
2514
  yield StreamToken(final_response=ModelResponse(
2346
2515
  text=text, tool_calls=calls, usage=usage,
2516
+ usage_unreported=unreported,
2347
2517
  thinking=_thinking_record(provider_name, model, thinking_blocks),
2348
2518
  ))
2349
2519
  return
@@ -2369,6 +2539,13 @@ def call_model_stream(
2369
2539
  # partial-report case the widened rule exists for arrives here
2370
2540
  # already coerced and indistinguishable (batch 147).
2371
2541
  usage = {"input_tokens": None, "output_tokens": None}
2542
+ # The provider's own fields, kept apart until the stream ends:
2543
+ # OUTPUT IS TWO OF THEM (§97, UF2). `candidates_token_count` leaves
2544
+ # the model's thoughts out -- the SDK's own `total_token_count` is
2545
+ # documented as prompt + candidates + tool-use prompt + thoughts --
2546
+ # and thoughts are generated and billed as output, so the rate and
2547
+ # `billed` read short by them on a thinking model until this batch.
2548
+ google_counts = dict.fromkeys(_GOOGLE_COUNTS)
2372
2549
 
2373
2550
  for chunk in client.models.generate_content_stream(
2374
2551
  model=model,
@@ -2408,22 +2585,33 @@ def call_model_stream(
2408
2585
  # the provider chose to put the totals on.
2409
2586
  usage_meta = getattr(chunk, "usage_metadata", None)
2410
2587
  if usage_meta is not None:
2411
- for key, attribute in (
2412
- ("input_tokens", "prompt_token_count"),
2413
- ("output_tokens", "candidates_token_count")):
2588
+ for attribute in _GOOGLE_COUNTS:
2414
2589
  reported = _token_count(usage_meta, attribute)
2415
2590
  if reported is not None:
2416
- usage[key] = reported
2591
+ google_counts[attribute] = reported
2592
+
2593
+ # §97 (UF2, UF4). Each field kept per its own last report above,
2594
+ # then combined once: thoughts join the candidates in output
2595
+ # (`_sum_reported`, so neither alone being absent zeroes the other),
2596
+ # and the cached content is a cache read that `prompt_token_count`
2597
+ # already includes, so UF5 adds nothing to input on this branch.
2598
+ usage["input_tokens"] = google_counts["prompt_token_count"]
2599
+ usage["output_tokens"] = _sum_reported(
2600
+ google_counts["candidates_token_count"],
2601
+ google_counts["thoughts_token_count"])
2602
+ usage["cache_read_tokens"] = google_counts["cached_content_token_count"]
2417
2603
 
2418
2604
  # D21, in the one place all three branches read it (batch 147).
2419
2605
  # This is the branch the nullable-field defect was found in: the
2420
2606
  # pinned google-genai declares every usage field Optional[int], so
2421
2607
  # `usage` could leave here holding None and the raise could not
2422
2608
  # fire -- `None != 0`.
2423
- usage = _stream_usage(provider_name, usage, supports_stream_usage)
2609
+ usage, unreported = _stream_usage(provider_name, usage,
2610
+ supports_stream_usage)
2424
2611
 
2425
2612
  yield StreamToken(final_response=ModelResponse(
2426
2613
  text="".join(text_parts), tool_calls=calls, usage=usage,
2614
+ usage_unreported=unreported,
2427
2615
  thinking=_thinking_record(provider_name, model, signatures),
2428
2616
  ))
2429
2617
  return
@@ -2450,7 +2638,17 @@ def call_model_stream(
2450
2638
  usage = {"input_tokens": None, "output_tokens": None}
2451
2639
 
2452
2640
  finish_reason = None
2453
- for chunk in client.chat.completions.create(**openai_kwargs):
2641
+ try:
2642
+ stream = client.chat.completions.create(**openai_kwargs)
2643
+ except Exception as refusal:
2644
+ if not (thinking and provider_errors.refuses_effort(refusal)):
2645
+ # Batch 258: a page-not-found names the address, not a model.
2646
+ provider_errors.explain_route_miss(refusal)
2647
+ raise
2648
+ stream = _resend_without_effort(
2649
+ client, provider_name, model, openai_kwargs, thinking, sampling,
2650
+ temperature, effort, refusal)
2651
+ for chunk in stream:
2454
2652
  if chunk.choices:
2455
2653
  # W4 (#37): free -- chunk.choices[0] is already read here. The
2456
2654
  # provider sets this on the last content chunk, and `or
@@ -2514,12 +2712,23 @@ def call_model_stream(
2514
2712
  reported = _token_count(usage_obj, attribute)
2515
2713
  if reported is not None:
2516
2714
  usage[key] = reported
2715
+ # §97 (UF4). Part of `prompt_tokens` already on this API, so
2716
+ # UF5 adds nothing here. A provider that spells its cache
2717
+ # counts some other way reports none, and /usage says so.
2718
+ cached = getattr(usage_obj, "prompt_tokens_details", None)
2719
+ for key, attribute in (("cache_read_tokens", "cached_tokens"),
2720
+ ("cache_write_tokens",
2721
+ "cache_write_tokens")):
2722
+ reported = _token_count(cached, attribute)
2723
+ if reported is not None:
2724
+ usage[key] = reported
2517
2725
 
2518
2726
  # D21: if the provider is marked as supporting stream usage but we
2519
2727
  # got no usable usage, the stream was likely interrupted before the
2520
2728
  # final usage chunk arrived. Raise rather than silently reporting zero.
2521
2729
  # One copy for three branches since batch 147.
2522
- usage = _stream_usage(provider_name, usage, supports_stream_usage)
2730
+ usage, unreported = _stream_usage(provider_name, usage,
2731
+ supports_stream_usage)
2523
2732
 
2524
2733
  calls = []
2525
2734
  for idx in sorted(tool_fragments):
@@ -2560,6 +2769,7 @@ def call_model_stream(
2560
2769
 
2561
2770
  yield StreamToken(final_response=ModelResponse(
2562
2771
  text="".join(text_parts), tool_calls=calls, usage=usage,
2772
+ usage_unreported=unreported,
2563
2773
  thinking=_thinking_record(provider_name, model, reasoning_blocks),
2564
2774
  ))
2565
2775
 
package/core/commands.py CHANGED
@@ -119,9 +119,10 @@ _SPECS = (
119
119
  "[--software|--research] [--config]",
120
120
  absent={CLI: "not yet; run venastine --init."}),
121
121
  CommandSpec("kill", "stop a background session", "[session-id]",
122
- absent={CLI: "the CLI's prompt waits until background "
123
- "sessions finish, and Ctrl+C while it waits "
124
- "stops them."}),
122
+ # Batch 265: the prompt no longer waits for them (SS2 as
123
+ # amended), so the reason is the key alone.
124
+ absent={CLI: "Ctrl+C while the CLI waits on background "
125
+ "sessions stops them."}),
125
126
  CommandSpec("memories", "list durable memories visible here"),
126
127
  CommandSpec("mentions", "show file mention status or include ignored "
127
128
  "paths", "[ignored on|off]",
@@ -163,6 +164,9 @@ _SPECS = (
163
164
  CommandSpec("trigger", "override when this chat compacts, for the "
164
165
  "session", "[tokens|off]",
165
166
  absent={CLI: _IN_THE_TUI}),
167
+ # ROADMAP_v3 §97 (UF4): both shells, one report (`core/usage_view.py`).
168
+ CommandSpec("usage", "token counts the provider reported for this "
169
+ "thread"),
166
170
  CommandSpec("window", "override this model's context window for the "
167
171
  "session", "[tokens|off]",
168
172
  absent={CLI: _IN_THE_TUI}),
package/core/loop.py CHANGED
@@ -683,11 +683,18 @@ def _already_said(notices, kind: str) -> bool:
683
683
  # reasoning-only reply ends the turn with a notice. The row's first line is
684
684
  # also the live notice's text, so the line a person sees while the turn
685
685
  # runs is the line its replay draws (RO5).
686
+ #
687
+ # The first line says what did not run is THAT reply, and that results
688
+ # returned before it are real (RO2 as amended in batch 261, the owner's
689
+ # choice). It corrects a model that acts as though calls written in its
690
+ # reasoning took effect, and a bare "nothing ran" could also be read as
691
+ # "the calls earlier in this turn did not run either".
686
692
  HARNESS_REASONING_ONLY = "reasoning_only"
687
693
  REASONING_ONLY_END = "reasoning_only_end"
688
694
  REASONING_ONLY_HEADER = (
689
695
  "[harness] The last reply was reasoning only: no answer and no tool "
690
- "call reached the harness, so nothing ran.")
696
+ "call reached the harness, so nothing in that reply ran. Results "
697
+ "returned before it are real.")
691
698
  _REASONING_ONLY_NUDGE = (
692
699
  REASONING_ONLY_HEADER + "\n"
693
700
  "A tool call written inside reasoning is not run. Make the call through "
@@ -2131,6 +2138,11 @@ class RunAgentLoop:
2131
2138
  turn_output_tokens += usage_out
2132
2139
  turn_prev_input = usage_in
2133
2140
  memory.record_billed(usage_in + usage_out)
2141
+ # ROADMAP_v3 §97 (UF4). Beside billed, on the same object and so
2142
+ # over the same span: what `/usage` shows, the provider's own
2143
+ # counts with the coerced ones left out.
2144
+ memory.record_usage(response.usage,
2145
+ getattr(response, "usage_unreported", ()))
2134
2146
  response.turn_billed_tokens = total_tokens_used
2135
2147
  response.turn_new_tokens = turn_new_tokens
2136
2148
  response.turn_output_tokens = turn_output_tokens
@@ -2395,6 +2407,10 @@ class RunAgentLoop:
2395
2407
  **auth_kwargs,
2396
2408
  ), observe)
2397
2409
  response.thread_id = memory.thread_id
2410
+ # ROADMAP_v3 §97 (UF4). This memory was built for this run, so its
2411
+ # tally is this turn's calls: the CLI's `/usage` adds them up. None
2412
+ # from a memory that keeps none, which the CLI's tally ignores.
2413
+ response.turn_usage = getattr(memory, "usage", None)
2398
2414
  return response
2399
2415
 
2400
2416
  @staticmethod
@@ -2663,4 +2679,8 @@ class RunAgentLoop:
2663
2679
  **auth_kwargs,
2664
2680
  ), observe)
2665
2681
  response.thread_id = memory.thread_id
2682
+ # ROADMAP_v3 §97 (UF4). This memory was built for this run, so its
2683
+ # tally is this turn's calls: the CLI's `/usage` adds them up. None
2684
+ # from a memory that keeps none, which the CLI's tally ignores.
2685
+ response.turn_usage = getattr(memory, "usage", None)
2666
2686
  return response
package/core/memory.py CHANGED
@@ -46,6 +46,7 @@ PERSISTENCE, AND WHY THERE'S NO NORMALIZATION STEP HERE:
46
46
  from typing import Optional
47
47
  from uuid import UUID
48
48
 
49
+ from core.usage_view import UsageTally
49
50
  from storage import (
50
51
  THREAD_KIND_CHAT,
51
52
  create_thread,
@@ -127,6 +128,8 @@ class ConversationMemory:
127
128
  # resumed -- see record_billed for why this one is deliberately not
128
129
  # extra_data like its neighbour.
129
130
  self.billed_tokens = 0
131
+ # ROADMAP_v3 §97 (UF4). Its neighbour's scope, for its reason.
132
+ self.usage = UsageTally()
130
133
  # ROADMAP_v3 §81 (IM3). Images a tool attached for a call whose
131
134
  # result has not been written yet, keyed by the call's id.
132
135
  # add_tool_result takes them into the row it writes; nothing else
@@ -259,6 +262,16 @@ class ConversationMemory:
259
262
  """
260
263
  self.billed_tokens += int(tokens or 0)
261
264
 
265
+ def record_usage(self, usage, unreported=()) -> None:
266
+ """One model call's provider-reported counts, for `/usage`
267
+ (ROADMAP_v3 §97, UF4).
268
+
269
+ record_billed's scope and its reason: not persisted, zero on every
270
+ construction, so `/usage` covers exactly the span the usage line's
271
+ `billed` does. `unreported` is `ModelResponse.usage_unreported`.
272
+ """
273
+ self.usage.add(usage, unreported)
274
+
262
275
  def completed_turns(self) -> int:
263
276
  """How many turns of this thread are already finished (§21 M5/M11).
264
277
 
@@ -57,9 +57,11 @@ which says nothing true. So both questions this module answers walk
57
57
  worth another attempt, and its own sentence is the description.
58
58
  """
59
59
 
60
+ import json
60
61
  from random import random
61
62
  from time import sleep
62
63
  from typing import Optional
64
+ from urllib.parse import urlsplit, urlunsplit
63
65
 
64
66
  #: Beside any 5xx. The same set the openai and anthropic SDKs retry.
65
67
  RETRYABLE_STATUSES = frozenset({408, 409, 429})
@@ -76,6 +78,11 @@ JITTER = 0.25
76
78
  #: sentence and the error object google-genai folds into its message.
77
79
  DESCRIBE_LIMIT = 500
78
80
 
81
+ #: The words `explain_route_miss` adds before the address (batch 258), and
82
+ #: how it knows an exception already carries them -- the lookup and the
83
+ #: call can both reach the same one, and saying it twice says nothing more.
84
+ ROUTE_MISS_MARK = "nothing answers at"
85
+
79
86
  _CONNECTION_NAMES = frozenset({
80
87
  "APIConnectionError", "APITimeoutError", # openai, anthropic
81
88
  "TransportError", "TimeoutException", # httpx: raw mid-stream; google-genai
@@ -272,3 +279,98 @@ def describe(exc: BaseException) -> str:
272
279
  text = text[:DESCRIBE_LIMIT - 1].rstrip() + "…"
273
280
  name = type(exc).__name__
274
281
  return f"{name}: {text}" if text else name
282
+
283
+
284
+ def _bare_address(url: str) -> str:
285
+ """Scheme, host, port and path -- never a query, a fragment or a
286
+ user:password, which an address can carry and a message must not."""
287
+ parts = urlsplit(url)
288
+ host = parts.hostname or ""
289
+ if ":" in host:
290
+ host = f"[{host}]"
291
+ if parts.port is not None:
292
+ host = f"{host}:{parts.port}"
293
+ return urlunsplit((parts.scheme, host, parts.path, "", ""))
294
+
295
+
296
+ def route_miss(exc: BaseException) -> Optional[str]:
297
+ """The address a request was sent to that the server has NO ROUTE for,
298
+ or None when `exc` is anything else (batch 258).
299
+
300
+ A 404 whose body is not JSON. An OpenAI-compatible server answers in
301
+ JSON for everything it understands -- a model it does not have, a model
302
+ without tools, a model that cannot reason -- so a plain body is the
303
+ server's own page-not-found, sent before any model was looked at.
304
+ Measured on a real local Ollama: `/models` and `/chat/completions`
305
+ answer `404 text/plain` "404 page not found", while `/v1/...` answers a
306
+ missing model with a JSON 404 naming it. The openai SDK keeps a body it
307
+ could not parse as the STRING it was (`body`), and the request it sent
308
+ (`request.url`), which is all this reads -- no SDK import, for this
309
+ module's reason.
310
+ """
311
+ if _as_status(getattr(exc, "status_code", None)) != 404:
312
+ return None
313
+ if not isinstance(getattr(exc, "body", None), str):
314
+ return None
315
+ url = getattr(getattr(exc, "request", None), "url", None)
316
+ if url is None:
317
+ return None
318
+ return _bare_address(str(url))
319
+
320
+
321
+ def explain_route_miss(exc: BaseException) -> BaseException:
322
+ """Add what a route miss MEANS to `exc`'s own message, in place, and
323
+ return it (batch 258).
324
+
325
+ "404 page not found" -- or, on openai 3.x, "Error code: 404" -- was the
326
+ whole report, and a reader took it for the model: missing tool support,
327
+ a bad Modelfile. It is the address. The words go ON THE EXCEPTION
328
+ because every surface prints the exception -- the transcript's error
329
+ line, the CLI's, the worker log, `describe` and the context-window
330
+ warning -- and five call sites each adding a hint is five chances to
331
+ miss one. In place, so the type, status and body that `is_transient`
332
+ and every caller read are the ones the SDK set.
333
+ """
334
+ url = route_miss(exc)
335
+ if url is None or ROUTE_MISS_MARK in str(exc):
336
+ return exc
337
+ # Imported here, so this module's own imports stay the standard
338
+ # library's, and read through the module so a test's monkeypatch of
339
+ # LLM_PROVIDERS_FILE is seen.
340
+ import credentials
341
+
342
+ text = (f"{exc} -- {ROUTE_MISS_MARK} {url}. That is the server's "
343
+ f"page-not-found, sent before any model was asked, so the "
344
+ f"address is wrong rather than the model: API_URL in "
345
+ f"{credentials.LLM_PROVIDERS_FILE} is not where this server's "
346
+ f"API is. An OpenAI-compatible server's API_URL usually ends in "
347
+ f"/v1, as a local Ollama's does (http://localhost:11434/v1).")
348
+ exc.args = (text,)
349
+ if hasattr(exc, "message"):
350
+ exc.message = text
351
+ return exc
352
+
353
+
354
+ def refuses_effort(exc: BaseException) -> bool:
355
+ """Whether a refusal MIGHT be about the reasoning effort a request
356
+ carried (batch 258).
357
+
358
+ A 400 or 422 whose message or error object says "reasoning" or
359
+ "thinking". Wide on purpose, and safe because of what it decides: the
360
+ caller sends the request once more WITHOUT the effort and believes the
361
+ answer only if that resend succeeds. A wrong match costs one request and
362
+ changes nothing. A narrow match costs the user a turn that fails: there
363
+ is no standard wording -- a local Ollama says `"llama3.2:3b" does not
364
+ support thinking` (measured), OpenAI-compatible routers name the
365
+ `reasoning_effort` parameter.
366
+ """
367
+ if _as_status(getattr(exc, "status_code", None)) not in (400, 422):
368
+ return False
369
+ body = getattr(exc, "body", None)
370
+ words = str(exc)
371
+ if isinstance(body, (dict, list)):
372
+ words += " " + json.dumps(body, default=str)
373
+ elif isinstance(body, str):
374
+ words += " " + body
375
+ words = words.lower()
376
+ return "reasoning" in words or "thinking" in words