@yahyahammad/venastine 0.3.14 → 0.3.16

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/README.md CHANGED
@@ -388,7 +388,7 @@ where *nothing* matched is treated as a failure. Every number in `04_confidence.
388
388
 
389
389
  ### Different models can check each other
390
390
 
391
- Set `CRITIC_MODEL` and passes 3a, 3b and 6c run on a *different* provider and model from the one that wrote the answer. A model checking its own output brings its own blind spots to the inspection.
391
+ Set `critic_model` in `config.yaml`, or pick one with `/critic` in the TUI, and passes 3a, 3b and 6c run on a *different* provider and model from the one that wrote the answer. A model checking its own output brings its own blind spots to the inspection.
392
392
 
393
393
  **Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs under `ensemble_models` in `config.yaml` (a settings.json key is deliberately absent — choosing providers multiplies spend, so it stays in the harness's own file) and Pass 1 runs once per entry, each candidate on its own provider and model. Fewer than two *distinct* pairs is refused: N copies of one model agree most confidently on that model's systematic errors, which is exactly where agreement has to mean something. Claims extracted from all candidates are pooled. A factual claim no more than half the candidates asserted is *contested*: it keeps the score its evidence earns and goes through the revise-and-revalidate passes to be checked, with the count in its feedback. Since batch 232; it used to be marked down instead, which no revision could undo. A candidate that fails mid-run is named and skipped; if only one survives, the run degrades to the ordinary single-response path rather than scoring an "ensemble of one". Artifacts come out as `01_candidate_1.md`, `01_candidate_2.md`, … numbered to match each claim's `asserted_by_candidates` tags.
394
394
 
@@ -537,8 +537,8 @@ now **closed** under `shlex`, which consumes exactly whitespace, `'`, `"` and `\
537
537
  tokens and the executor's are provably the same list. On Windows this costs a backslash path such
538
538
  as `cat sub\dir\notes.txt`, which moves to the container and fails there — use forward slashes.
539
539
 
540
- **These settings are read once, at startup.** Since batch 40 `SHELL_APPROVAL_MODE`, both fallback
541
- flags and `REDACT_TOOL_OUTPUTS` are bound into a frozen posture (`security/posture.py`) rather than
540
+ **These settings are read once, at startup.** Since batch 40 `shell_approval_mode`, both fallback
541
+ flags and `redact_tool_outputs` are bound into a frozen posture (`security/posture.py`) rather than
542
542
  consulted at each decision, so nothing running in-process can move them mid-session. If any of them
543
543
  is set to something weaker than the shipped default, the harness says so at launch — on stderr, in
544
544
  `app.log`, and as a badge in the TUI sidebar for as long as the session lasts.
@@ -702,7 +702,7 @@ Agent frontmatter fields:
702
702
  | `approval_overrides` | mapping | `{}` | Can only ever *add* prompts, never remove one |
703
703
  | `use_project_context` | bool | `false` | Inject the project's root `AGENTS.md` into the system prompt |
704
704
  | `use_memory` | bool | `true` | Inject durable memories (plain chat counts as opted in) |
705
- | `max_steps` | int ≥ 1 | caller's ceiling | **Replaces** the caller's ceiling rather than narrowing it — a value above `MAX_ITERATIONS` raises it, making this the one frontmatter field that can widen anything; an invalid value is repaired to the default with a warning naming what it read |
705
+ | `max_steps` | int ≥ 1 | caller's ceiling | **Replaces** the caller's ceiling rather than narrowing it — a value above `max_iterations` raises it, making this the one frontmatter field that can widen anything; an invalid value is repaired to the default with a warning naming what it read |
706
706
  | `spawnable` | bool | `false` for your files | Whether `spawn_subagent` may feed this agent |
707
707
  | `spawn_targets` | list | any spawnable agent | Which agents this one may spawn. It only ever narrows, and narrows again for anything it spawns in turn, as described above |
708
708
 
@@ -787,7 +787,7 @@ paths are cached and 200 matches offered; narrow the query when a limit is shown
787
787
  | `/mentions [ignored on\|off]` | Show file mention status or include ignored paths for this session |
788
788
  | `/quit` | Leave the harness, on one invocation — a typed command is already deliberate. `/exit` and `/bye` are the same command under other names; type toward either and the suggestion list says so |
789
789
 
790
- Keys: **ctrl+c** twice quits — the first press arms it and the footer changes to say so, and it goes back to `Quit` after a couple of seconds; a **ctrl+c** over selected text copies instead and arms nothing, so nothing you copy can end the session. **ctrl+q** quits on a single press, from anywhere, including under a dialog · **ctrl+t** thread picker · **ctrl+l** claims view · **ctrl+j** (or **shift+enter**) newline in the prompt · **shift+tab** in the prompt switches to the next agent in `config.yaml`'s `agent_cycle` (default → plan → build as shipped) · **up/down** and **enter**/**tab** to pick a slash command, **escape** to dismiss the list · **ctrl+click** a URL in an answer — or in a tool line — to open it, or the name on a `spawn_subagent` line to read what that agent did, or the name on a `shell_background`, `shell_monitor` or `shell_interactive` line to read that session -- its command, why it was started, what it printed, and what became of it. A session the harness no longer holds (it aged out, or you restarted) opens the same way and shows what the agent was given, saying so; a live one refreshes as it writes. While sessions are running the sidebar lists them, and clicking a row opens it; **ctrl+g** lists the runs going on right now and opens one from the keyboard · **ctrl+b** stops a background session, and always asks which one rather than killing on a single press. While background sessions are running the prompt and most commands are refused — `ctrl+b`, `/kill`, answering a dialog and quitting stay usable, because they are the ways out.
790
+ Keys: **ctrl+c** twice quits — the first press arms it and the footer changes to say so, and it goes back to `Quit` after a couple of seconds; a **ctrl+c** over selected text copies instead and arms nothing, so nothing you copy can end the session. **ctrl+q** quits on a single press, from anywhere, including under a dialog · **ctrl+t** thread picker · **ctrl+l** claims view · **ctrl+j** (or **shift+enter**) newline in the prompt · **shift+tab** in the prompt switches to the next agent in `config.yaml`'s `agent_cycle` (default → plan → build as shipped) · **up/down** and **enter**/**tab** to pick a slash command, **escape** to dismiss the list · **ctrl+click** a URL in an answer — or in a tool line — to open it, or the name on a `spawn_subagent` line to read what that agent did, or the name on a `shell_background`, `shell_monitor` or `shell_interactive` line to read that session -- its command, why it was started, what it printed, and what became of it. A session the harness no longer holds (it aged out, or you restarted) opens the same way and shows what the agent was given, saying so; a live one refreshes as it writes. The sidebar lists the running sessions, then the five that finished most recently, each marked with how it ended (`☑` exit 0, `☒` with its exit code, `killed`, `timed out` or `failed`), and clicking a row opens it; **ctrl+g** lists the runs going on right now and opens one from the keyboard · **ctrl+b** stops a background session, and always asks which one rather than killing on a single press. While background sessions are running the prompt and most commands are refused — `ctrl+b`, `/kill`, answering a dialog and quitting stay usable, because they are the ways out.
791
791
 
792
792
  Answers are rendered rather than printed as their source: tables become grids, headings and `**bold**` take weight, `*emphasis*` and `~~strike~~` take their own marks, code fences are highlighted, and a list item that runs past the edge wraps **under its own text** instead of back to the margin. A line indented four spaces or more is left exactly as written, so a code sample keeps its operators and its `#` comments. What is deliberately not rendered: block quotes, horizontal rules, heading *levels* (a `#` and a `######` look the same), and anything at all inside a reasoning block. `/copy` always hands back the markdown the model wrote — the rendering is what the screen does, never what is stored.
793
793
 
@@ -840,7 +840,7 @@ and letting it fall through would approve the next call on the strength of it. T
840
840
  answer to the prompt about to appear, and the terminal has been buffering it for you.
841
841
 
842
842
  **A deadline belongs to a run, not to a question.** An approval asked during an attended research run
843
- expires after `ATTENDED_APPROVAL_TIMEOUT_S` (600s) and denies that call, because there is a run
843
+ expires after `attended_approval_timeout_s` (600s) and denies that call, because there is a run
844
844
  waiting on the answer and it has to keep moving. `--init`'s prompts have no run behind them, so they
845
845
  wait as long as you need — and they do not print a `(600s)` they would not honour.
846
846
 
@@ -894,14 +894,14 @@ Everything `python main.py` accepts. Wherever a value can come from more than on
894
894
 
895
895
  Effort asks a reasoning model how long to think before answering. It rides every chat turn, every research pass, every JSON-retry correction, the reviewer and its re-synthesis — a retry is the same pass continuing, so it inherits the level rather than dropping it.
896
896
 
897
- Where a level comes from, in order: `--effort` > top-level `effort` in `settings.json` > `config.DEFAULT_EFFORT` (shipped `"high"`). Inside the TUI, `tui.effort` persists separately and wins there. `auto` is the off switch at either layer — with the default now high, `--effort auto` restores send-nothing behaviour.
897
+ Where a level comes from, in order: `--effort` > top-level `effort` in `settings.json` > `default_effort` in `config.yaml` (shipped `"high"`). Inside the TUI, `tui.effort` persists separately and wins there. `auto` is the off switch at either layer — with the default now high, `--effort auto` restores send-nothing behaviour.
898
898
 
899
899
  A level is validated against the model that will **receive** it, not the one it was chosen for:
900
900
 
901
901
  | Provider | Levels | Where the set comes from |
902
902
  |---|---|---|
903
903
  | Anthropic | `low`, `medium`, `high`, `xhigh`, `max` — whichever the model reports supported | Queried live from the Models API, so newly released Anthropic models need no entry anywhere |
904
- | OpenAI-compatible | `low`, `medium`, `high` assumed for unknown models | Static table (`config.MODEL_EFFORT_LEVELS`). Known non-reasoning models — gpt-4o family, gpt-3.5 — ship with *empty* lists, meaning "takes no effort parameter": a requested level is dropped cleanly instead of 400ing every call. An unlisted model gets the assumption plus a WARNING naming it |
904
+ | OpenAI-compatible | `default_effort_levels` assumed for unknown models (shipped: `low` through `ultra`) | Static table (`model_effort_levels` in `config.yaml`). Known non-reasoning models — gpt-4o family, gpt-3.5 — ship with *empty* lists, meaning "takes no effort parameter": a requested level is dropped cleanly instead of 400ing every call. An unlisted model gets the assumption plus a WARNING naming it. If it then refuses the level with a 400 that mentions reasoning or thinking — a local model that cannot reason does — the same request is sent once more without it; if that succeeds, the model gets no effort for the rest of the session, and a WARNING says which `model_effort_levels` entry makes that permanent |
905
905
  | Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary and sent as `thinking_budget`. On since batch 172, when the `google-genai` pin moved to 2.29.0; an unlisted Gemini model gets the default level set plus a WARNING, like any other unlisted model |
906
906
 
907
907
  **Seeing the thinking is separate from doing it.** Effort is what makes the model reason; whether the API hands those thoughts back to the client is a different question, and the answer varies by provider. Reasoning streams into the transcript on **Anthropic** and on OpenAI-compatible providers that send it — DeepSeek, Qwen, Z.AI, OpenRouter. It is absent on **OpenAI**, whose Chat Completions endpoint returns no reasoning text at all, and on **Google**, whose request deliberately does not ask for thought summaries: those would be billed as extra output for something the model produces either way. On those two the turn still thinks; you just do not see it. `tui.show_thinking` and `/thinking` control the display, never the reasoning.
@@ -922,9 +922,9 @@ Three things can end a turn or pass early:
922
922
 
923
923
  The CLI names the figures behind an early stop — billed this turn, and the thread's measured context size — rather than a bare reason, because "budget exceeded" invites exactly the misreading that there is a size problem.
924
924
 
925
- Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 20-second wall clock (`tool_compute_timeout_s`) and are told which tool and which limit stopped them; pre-granted tool calls cap at 150 per research run (`MAX_GRANTED_TOOL_CALLS`), degrading to asking when exhausted; subagent nesting stops at depth 2 (`SUBAGENT_MAX_DEPTH`) and at most three subagents of one turn run at once (`SUBAGENT_MAX_PARALLEL`), with anything beyond that running in waves; attended prompts expire after 600 seconds (`ATTENDED_APPROVAL_TIMEOUT_S`), denying that one call while the run continues.
925
+ Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 20-second wall clock (`tool_compute_timeout_s`) and are told which tool and which limit stopped them; pre-granted tool calls cap at 150 per research run (`max_granted_tool_calls`), degrading to asking when exhausted; subagent nesting stops at depth 2 (`subagent_max_depth`) and at most three subagents of one turn run at once (`subagent_max_parallel`), with anything beyond that running in waves; attended prompts expire after 600 seconds (`attended_approval_timeout_s`), denying that one call while the run continues.
926
926
 
927
- Subagents spawned in one model response run **concurrently**, up to `SUBAGENT_MAX_PARALLEL`. Their answers come back to the model in the order it asked for them however they finish, one approval question reaches you at a time, and the sidebar draws them as a tree rather than a chain. The database runs in SQLite's WAL mode to keep their writes from contending, which means `app.db` is accompanied by `app.db-wal` and `app.db-shm` while the harness is open — both are gitignored, and excluded from `git archive`, because a WAL file holds recently written messages.
927
+ Subagents spawned in one model response run **concurrently**, up to `subagent_max_parallel`. Their answers come back to the model in the order it asked for them however they finish, one approval question reaches you at a time, and the sidebar draws them as a tree rather than a chain. The database runs in SQLite's WAL mode to keep their writes from contending, which means `app.db` is accompanied by `app.db-wal` and `app.db-shm` while the harness is open — both are gitignored, and excluded from `git archive`, because a WAL file holds recently written messages.
928
928
 
929
929
  **Network limits are off by default.** For a metered connection, `config.yaml` can cap what the harness pulls and pushes over a rolling window, 24 hours unless you change it, with a separate ceiling in decimal megabytes for each of three kinds of traffic: the network tools, the model provider's API, and MCP servers reached over HTTP. A local Ollama or a local MCP server need not count against an allowance, so each is switched on by its own ceiling. A call that would pass its ceiling is refused with a reason that says when room returns; one already running is never cut off, so a meter can end up over by one response. Counts are kept in `~/.config/venastine/network.db`, shared by every harness process, written at most once a minute, and pruned as they leave the window. Shell commands, `stdio` MCP servers, sign-in traffic and TLS overhead are not counted, and `web_search`'s figure is an estimate (its client cannot be counted). `/network` shows the meters, and the sidebar shows them while any is on.
930
930
 
@@ -1027,7 +1027,7 @@ Deliberately not settings.json keys: editing these means editing the harness's o
1027
1027
 
1028
1028
  | Variable | Default | Controls |
1029
1029
  |---|---|---|
1030
- | `AGENT_MODEL` | `claude-sonnet-5` | Built-in default model (`config.MODEL_NAME`) — still loses to settings.json and `--model` |
1030
+ | `AGENT_MODEL` | `claude-sonnet-5` | Built-in default model (`model_name` in `config.yaml`) — still loses to settings.json and `--model` |
1031
1031
  | `AGENT_PROVIDERS_FILE` | `providers.json` | Credential-file location |
1032
1032
  | `APP_DB_PATH` | `app.db` | SQLite database path |
1033
1033
  | `AGENT_OUTPUT_DIR` | `./output` | Research artifacts root |
@@ -1043,8 +1043,8 @@ Deliberately not settings.json keys: editing these means editing the harness's o
1043
1043
 
1044
1044
  | Field | Meaning |
1045
1045
  |---|---|
1046
- | `API_URL` | Endpoint base URL; empty for ANTHROPIC and GOOGLE, which use their SDKs' defaults |
1047
- | `API_KEY` | The credential, stored directly |
1046
+ | `API_URL` | Endpoint base URL; empty for ANTHROPIC and GOOGLE, which use their SDKs' defaults. For an OpenAI-compatible server it is the address the harness adds `/chat/completions` and `/models` to, so it usually ends in `/v1`: a local Ollama is `http://localhost:11434/v1`. Without the `/v1` the server answers `404 page not found`, and the harness's error says it is the address, not the model |
1047
+ | `API_KEY` | The credential, stored directly. A local OpenAI-compatible server that needs none can leave it empty: the harness sends a placeholder, because the openai SDK will not build a client with an empty key |
1048
1048
  | `is_v1_compatible` | `true` routes the provider through the OpenAI-compatible translation |
1049
1049
  | `supports_stream_usage` | Promises streamed responses carry token usage. If a stream then ends with none, the harness **raises** rather than accounting zero tokens — a silent zero would disable the budget stop condition while looking healthy. Endpoints that don't return streaming usage ship with `false` |
1050
1050
  | `echoes_reasoning` | Opt in to sending this provider's own reasoning back on the next request (§44). Off everywhere by default: there is no standard for it the way there is for receiving reasoning — DeepSeek documents that `reasoning_content` must not be supplied on input and returns a 400, while OpenRouter accepts it for some models and ignores it for others. Anthropic needs no flag; its thinking blocks are signed and are echoed to the model that produced them automatically |
@@ -1077,7 +1077,7 @@ note that shell approval is governed solely by `shell_approval_mode` -- `tool_ap
1077
1077
  deliberately has no `shell` key, so an old file carrying one is refused at startup
1078
1078
  naming the key — see `tests/BREAKING_CHANGES.md` §24.
1079
1079
 
1080
- Run the test suite with `pytest` — 9358 tests, fully offline, no API keys needed. Since batch 243 the suite holds itself to that: a test that asks DNS for a name, or writes into your home folder, fails by name, and every test process runs with HOME pointing at a throwaway folder of its own. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Eight further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, one runs an external program through the host fallback shell, one builds the hosted bundle's Docker image, and three run the installers' uv path against a real uv (`pytest -m integration`).
1080
+ Run the test suite with `pytest` — 9510 tests, fully offline, no API keys needed. Since batch 243 the suite holds itself to that: a test that asks DNS for a name, or writes into your home folder, fails by name, and every test process runs with HOME pointing at a throwaway folder of its own. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Eight further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, one runs an external program through the host fallback shell, one builds the hosted bundle's Docker image, and three run the installers' uv path against a real uv (`pytest -m integration`).
1081
1081
 
1082
1082
  ## Documentation
1083
1083
 
package/config.py CHANGED
@@ -1,6 +1,8 @@
1
1
  """config.py -- the harness's settings, as module attributes.
2
2
 
3
- THE VALUES LIVE IN `config.yaml` NOW. This module is the compatibility layer
3
+ NOT A FILE TO EDIT. To change a setting, edit `config.yaml`; every
4
+ message the harness shows names that file and its lower-case keys
5
+ (batch 257). THE VALUES LIVE IN `config.yaml` NOW. This module is the compatibility layer
4
6
  that publishes them: it reads the file once, through `config_schema.py`, and
5
7
  binds each value as a plain module global, so `config.MAX_TOKENS` means what
6
8
  it always meant to the 30 production modules and ~60 test files that read it.
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
@@ -1238,6 +1253,12 @@ def _messages_for_provider(provider_name: str, neutral_messages: list[dict],
1238
1253
  # Anthropic branch queries the API once per process rather than per call.
1239
1254
  _effort_levels_cache: dict[tuple[str, str], list[str]] = {}
1240
1255
 
1256
+ # (provider_name, model, level) whose drop effort_for has already reported.
1257
+ # Batch 258: a model that refused effort is recorded as taking none, and
1258
+ # effort_for then drops the chosen level on every turn -- said once, not
1259
+ # once per message.
1260
+ _effort_drops_said: set[tuple[str, str, str]] = set()
1261
+
1241
1262
  # (provider_name, model) -> context window in tokens, or None for "asked,
1242
1263
  # and this provider does not report one". Same lazy, once-per-process
1243
1264
  # posture as the effort cache above; see context_window_for() for why None
@@ -1422,9 +1443,13 @@ def effort_for(client, provider_name: str, model: str,
1422
1443
  "Could not verify effort %r for %s/%s; sending it unverified.",
1423
1444
  requested, provider_name, model)
1424
1445
  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")
1446
+ said = (provider_name, model, requested)
1447
+ if said not in _effort_drops_said:
1448
+ _effort_drops_said.add(said)
1449
+ logger.warning(
1450
+ "Dropping effort %r: %s/%s accepts %s. Sending no effort "
1451
+ "parameter.", requested, provider_name, model,
1452
+ levels or "no effort control")
1428
1453
  return None
1429
1454
 
1430
1455
 
@@ -1575,7 +1600,7 @@ def _effort_levels(client, provider_name: str, model: str) -> tuple:
1575
1600
  if levels is None:
1576
1601
  logger.warning(
1577
1602
  "No effort levels known for %r on %s; assuming %s. Add an entry "
1578
- "to config.MODEL_EFFORT_LEVELS if this is wrong.",
1603
+ "to model_effort_levels in config.yaml if this is wrong.",
1579
1604
  model, provider_name, config.DEFAULT_EFFORT_LEVELS,
1580
1605
  )
1581
1606
  levels = list(config.DEFAULT_EFFORT_LEVELS)
@@ -1689,7 +1714,16 @@ def _model_info(client, model):
1689
1714
  raise
1690
1715
  try:
1691
1716
  entries = list(listing())
1692
- except Exception:
1717
+ except Exception as listing_error:
1718
+ # BATCH 258: one exception to the rule below. `/models` is the
1719
+ # route EVERY OpenAI-compatible server has, so a page-not-found
1720
+ # there is not about this model -- it is the address, and the
1721
+ # most useful thing this lookup can say (core/provider_errors.
1722
+ # route_miss). The per-id route cannot carry that alone: some
1723
+ # providers have no such route for ids with a slash.
1724
+ if provider_errors.route_miss(listing_error):
1725
+ raise provider_errors.explain_route_miss(
1726
+ listing_error) from None
1693
1727
  # The listing is not a second opinion about the retrieve; it is
1694
1728
  # the same question by another route. Report the FIRST failure,
1695
1729
  # which is the one that names the endpoint the caller asked for.
@@ -1804,7 +1838,7 @@ def context_window_for(client, provider_name: str, model: str) -> tuple:
1804
1838
  giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
1805
1839
  logger.warning(
1806
1840
  "Could not read a context window for %r from %s (%s); "
1807
- "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
1841
+ "model_context_windows in config.yaml will answer instead.%s",
1808
1842
  model, provider_name, e,
1809
1843
  " Not asking again this session." if giving_up else "")
1810
1844
  if giving_up:
@@ -2023,11 +2057,14 @@ def _chatgpt_open(client, request: dict):
2023
2057
  them (CG10). A refresh that could not be made at all is a
2024
2058
  `ConnectionError`, which the loop retries like any dropped connection.
2025
2059
 
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`.
2060
+ ONE OF THE TWO RESENDS THIS FILE MAKES, and neither is a retry in
2061
+ AGENTS.md's sense, which this file does not own: nothing was wrong with
2062
+ the request or the weather, the credential was stale, and the second
2063
+ attempt is made with a different one. The other is
2064
+ `_resend_without_effort` (batch 258), the same kind: a different
2065
+ request, never the same one again. Every retry for a failure the
2066
+ provider might not repeat is still `core/loop.py`'s, asked of
2067
+ `core/provider_errors.py`.
2031
2068
  """
2032
2069
  from core import chatgpt_auth
2033
2070
 
@@ -2192,6 +2229,50 @@ def _chatgpt_stream(client, model: str, items: list, system_prompt: str,
2192
2229
  # ---- Streaming call + helpers -----------------------------------------------
2193
2230
  # ============================================================================
2194
2231
 
2232
+ def _resend_without_effort(client, provider_name: str, model: str,
2233
+ kwargs: dict, thinking: dict, sampling: dict,
2234
+ temperature, effort: Optional[str], refusal):
2235
+ """Send an OpenAI-compatible request once more, without the reasoning
2236
+ effort a model refused, and return its stream (batch 258).
2237
+
2238
+ THE SECOND RESEND THIS FILE MAKES, and it is CG10's kind, not a retry:
2239
+ the request was wrong for this model, and the second attempt is a
2240
+ different request. `default_effort: high` ships, and a model with no
2241
+ `model_effort_levels` entry is assumed to take every level, so a local
2242
+ model that cannot reason was sent `reasoning_effort` on its first turn
2243
+ and refused it -- a local Ollama: `"llama3.2:3b" does not support
2244
+ thinking`, a 400 (measured). The owner chose to drop it and resend.
2245
+
2246
+ BELIEVED ONLY IF THE RESEND SUCCEEDS. `provider_errors.refuses_effort`
2247
+ matches widely, because no two servers word this alike; what makes
2248
+ that safe is here. A resend that fails too means the effort was not
2249
+ the cause, so the FIRST refusal is raised -- it is about the request
2250
+ the user's settings made -- and nothing is recorded. A resend that
2251
+ succeeds records the model as taking no effort for the life of the
2252
+ process (`_effort_levels`' cache), so effort_for drops the level from
2253
+ then on and the picker stops offering one.
2254
+
2255
+ `sampling` is rebuilt for no effort: on OPENAI the effort decides
2256
+ whether a temperature may be sent at all (`_sampling_kwargs`).
2257
+ """
2258
+ resend = {key: value for key, value in kwargs.items()
2259
+ if key not in thinking and key not in sampling}
2260
+ resend.update(_sampling_kwargs(provider_name, model, temperature, None))
2261
+ try:
2262
+ stream = client.chat.completions.create(**resend)
2263
+ except Exception:
2264
+ raise refusal from None
2265
+ _effort_levels_cache[(provider_name, model)] = []
2266
+ logger.warning(
2267
+ "%s/%s refused reasoning effort %r (%s). Sent again without it, "
2268
+ "which it accepted, so no effort is sent to this model again this "
2269
+ "session. To make that permanent, add %r: [] under "
2270
+ "model_effort_levels in config.yaml.",
2271
+ provider_name, model, effort, provider_errors.describe(refusal),
2272
+ model)
2273
+ return stream
2274
+
2275
+
2195
2276
  def call_model_stream(
2196
2277
  client,
2197
2278
  provider_name: str,
@@ -2450,7 +2531,17 @@ def call_model_stream(
2450
2531
  usage = {"input_tokens": None, "output_tokens": None}
2451
2532
 
2452
2533
  finish_reason = None
2453
- for chunk in client.chat.completions.create(**openai_kwargs):
2534
+ try:
2535
+ stream = client.chat.completions.create(**openai_kwargs)
2536
+ except Exception as refusal:
2537
+ if not (thinking and provider_errors.refuses_effort(refusal)):
2538
+ # Batch 258: a page-not-found names the address, not a model.
2539
+ provider_errors.explain_route_miss(refusal)
2540
+ raise
2541
+ stream = _resend_without_effort(
2542
+ client, provider_name, model, openai_kwargs, thinking, sampling,
2543
+ temperature, effort, refusal)
2544
+ for chunk in stream:
2454
2545
  if chunk.choices:
2455
2546
  # W4 (#37): free -- chunk.choices[0] is already read here. The
2456
2547
  # provider sets this on the last content chunk, and `or
@@ -310,7 +310,7 @@ def context_limit(model: str, provider_name: Optional[str] = None) -> int:
310
310
  logger.warning(
311
311
  "No context window known for model %r%s; assuming %s. Set it "
312
312
  "with /window (remembered for this model) or add it to "
313
- "config.MODEL_CONTEXT_WINDOWS -- the compaction trigger, the "
313
+ "model_context_windows in config.yaml -- the compaction trigger, the "
314
314
  "research backstop and the summarizer's input budget all "
315
315
  "fire against this number.", model,
316
316
  f" on {provider_name}" if provider_name else "",
@@ -538,7 +538,7 @@ def _parse_md_file(path: str, kind: str, tier: str, category: str = ""):
538
538
  if not valid:
539
539
  logger.warning(
540
540
  "Agent file %s: max_steps must be a positive integer, got "
541
- "%r; defaulting to %s (config.MAX_ITERATIONS).",
541
+ "%r; defaulting to %s (max_iterations in config.yaml).",
542
542
  path, max_steps, config_schema.current().max_iterations)
543
543
  max_steps = None
544
544
  # Booleans are VALIDATED, not coerced. bool("false") is True, so
@@ -79,7 +79,7 @@ logger = logging.getLogger(__name__)
79
79
  # parking, so what is left unbounded is a UI thread that is alive and
80
80
  # wedged, where nothing else in the shell answers either.
81
81
  # A deadline here would need this leaf module to know a number that
82
- # belongs to config.py, and the failure it would prevent is one no shell
82
+ # belongs to config.yaml, and the failure it would prevent is one no shell
83
83
  # can currently produce. Shutdown does not wait either: the TUI's release
84
84
  # unblocks the holder, and every queued worker then finds `_shutting_down`
85
85
  # already true and returns its declining default without pushing a screen.
package/core/loop.py CHANGED
@@ -239,7 +239,7 @@ def with_refs(system_prompt: str, memory: ConversationMemory) -> str:
239
239
  if total > cap:
240
240
  logger.warning(
241
241
  "Injecting %s of %s attached references; the rest are not in this "
242
- "prompt. Raise config.MAX_INJECTED_REFS or drop one with "
242
+ "prompt. Raise max_injected_refs in config.yaml or drop one with "
243
243
  "/ref --clear.", cap, total)
244
244
  header = (f"{header}\n\nShowing {cap} of {total} attached references. "
245
245
  f"The others exist and are not included here.")
@@ -428,7 +428,7 @@ def attach_ref(memory: ConversationMemory, thread_id, summary: str,
428
428
  if existing is None and len(refs) >= config.MAX_INJECTED_REFS:
429
429
  return False, (
430
430
  f"Already referencing {len(refs)} conversations, which is the "
431
- f"limit (config.MAX_INJECTED_REFS). Drop one with /ref --clear "
431
+ f"limit (max_injected_refs in config.yaml). Drop one with /ref --clear "
432
432
  f"first -- none is removed automatically.")
433
433
 
434
434
  entry = {
@@ -1855,7 +1855,7 @@ class RunAgentLoop:
1855
1855
  f"max_steps must be a positive integer, got {max_steps!r}. "
1856
1856
  f"Agent definitions carrying an invalid max_steps are "
1857
1857
  f"repaired by the loader to {config.MAX_ITERATIONS} "
1858
- f"(config.MAX_ITERATIONS); direct callers must pass a valid "
1858
+ f"(max_iterations in config.yaml); direct callers must pass a valid "
1859
1859
  f"value themselves.")
1860
1860
  client = api_initialization(provider_name)
1861
1861
  # Validate the level against the model that will RECEIVE it, here
@@ -7,8 +7,8 @@ ROADMAP_v2 §45 (SQ7). A research run reaches for three models: the
7
7
  generator (the session pair, `/model`), the CRITIC that grounds and
8
8
  critiques its claims (§11), and — since §45 — the EMBEDDER that scores how
9
9
  close a source is to the claim it was cited for. Only the first has ever
10
- been reachable without editing installed source. `CRITIC_MODEL` has sat in
11
- `config.py` since §11, which means the routing this project's own
10
+ been reachable without editing installed source. `critic_model` has sat in
11
+ the harness's own config (`config.py`, now `config.yaml`) since §11, which means the routing this project's own
12
12
  methodology calls essential ("a model checking its own output for errors
13
13
  shares that model's blind spots") was available only to whoever could edit
14
14
  the checkout.
@@ -27,10 +27,10 @@ which part in a run — and `model_windows.py` is next door as the example
27
27
  of when a second file is right instead (it holds a different kind of fact,
28
28
  keyed on a pair rather than naming one).
29
29
 
30
- PRECEDENCE: THE STORE OUTRANKS `config.py`. The opposite of
30
+ PRECEDENCE: THE STORE OUTRANKS `config.yaml`. The opposite of
31
31
  `model_windows`, and for the opposite reason — there, a configured value
32
32
  could be confidently wrong about a deployment, so the person won. Here
33
- `config.py` is the harness's own default and the store is a choice
33
+ `config.yaml` is the harness's own default and the store is a choice
34
34
  someone made at a command prompt for this account, which is `/model`
35
35
  outranking `config.MODEL_NAME` exactly.
36
36
 
@@ -63,7 +63,7 @@ from json_store import read_versioned, write_json_atomic
63
63
  logger = logging.getLogger(__name__)
64
64
 
65
65
  # Bumped when the SHAPE changes. An unknown version reads as an empty
66
- # store, which costs the remembered roles and falls back to config.py --
66
+ # store, which costs the remembered roles and falls back to config.yaml --
67
67
  # there is nothing here that was consented to, so the MCP store's careful
68
68
  # legacy handling has no counterpart.
69
69
  STORE_VERSION = 1
@@ -74,7 +74,7 @@ STORE_VERSION = 1
74
74
  # module exists to remove for CRITIC_MODEL.
75
75
  ROLES = ("critic", "embedder", "subagent")
76
76
 
77
- # Which config.py constant answers when the store is silent. None means
77
+ # Which config.yaml value answers when the store is silent. None means
78
78
  # nothing does: `subagent` is remembered or unset (§57, SM5).
79
79
  _FALLBACK_ATTR = {"critic": "CRITIC_MODEL", "embedder": "EMBEDDER_MODEL",
80
80
  "subagent": None}
@@ -89,7 +89,7 @@ def store_path() -> str:
89
89
 
90
90
  def _read_raw() -> dict:
91
91
  data = read_versioned(store_path(), STORE_VERSION,
92
- "falling back to config.py for pipeline models.")
92
+ "falling back to config.yaml for pipeline models.")
93
93
  roles = data.get("roles")
94
94
  return roles if isinstance(roles, dict) else {}
95
95
 
@@ -128,7 +128,7 @@ def _valid(entry) -> bool:
128
128
 
129
129
 
130
130
  def remembered(role: str) -> Optional[dict]:
131
- """What the user chose for `role`, or None. Ignores config.py."""
131
+ """What the user chose for `role`, or None. Ignores config.yaml."""
132
132
  entry = _read_raw().get(role)
133
133
  if not _valid(entry):
134
134
  return None
@@ -136,7 +136,7 @@ def remembered(role: str) -> Optional[dict]:
136
136
 
137
137
 
138
138
  def resolve(role: str) -> Optional[dict]:
139
- """The pair actually in force for `role`: the store, else config.py,
139
+ """The pair actually in force for `role`: the store, else config.yaml,
140
140
  else None.
141
141
 
142
142
  THE ONE READER FOR THE PIPELINE. `orchestrator` and every shell ask
@@ -171,7 +171,7 @@ def forget(role: str) -> str:
171
171
  Three outcomes rather than a bool, following model_windows: the shell
172
172
  says a different sentence for each, and a failed write reported as
173
173
  "nothing was set" would be a lie about a file the user can go and
174
- read. Note that "removed" does not mean the role is unset -- config.py
174
+ read. Note that "removed" does not mean the role is unset -- config.yaml
175
175
  may still answer, and the shell says so.
176
176
  """
177
177
  if role not in ROLES:
@@ -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
@@ -355,7 +355,7 @@ def _check_not_truncated(pass_id: str, response, trace: list[str] | None):
355
355
  f"condition returns the last response as it stands, so a pass "
356
356
  f"cut off mid-tool-call yields an empty string -- and every "
357
357
  f"later pass would be working from nothing. "
358
- f"(config.MAX_ITERATIONS and a configured settings.json "
358
+ f"(max_iterations in config.yaml and a configured settings.json "
359
359
  f"max_token_budget spend cap are the two ceilings that "
360
360
  f"produce this.)"
361
361
  )
@@ -1183,8 +1183,8 @@ def stream_deep_research_pipeline(
1183
1183
  # §45 (SQ7): through pipeline_models.resolve rather than
1184
1184
  # config.CRITIC_MODEL directly, so a `/critic` choice reaches the CLI,
1185
1185
  # the TUI and a spawned run alike. That function owns the precedence —
1186
- # the user-tier store outranks config.py — and owning it in one place
1187
- # is the point: §11 gave this routing to config.py alone, which meant
1186
+ # the user-tier store outranks config.yaml — and owning it in one place
1187
+ # is the point: §11 gave this routing to the harness config alone, which meant
1188
1188
  # the methodology's own "a model must not check its own output" was
1189
1189
  # available only to whoever could edit the checkout.
1190
1190
  critic = pipeline_models.resolve("critic")
@@ -218,7 +218,7 @@ def run_review(run, model: str, provider_name: str, authorization=None,
218
218
  # claim from "it found sixty and you saw the worst twenty-five".
219
219
  run.log(
220
220
  f"Review: {len(findings)} finding(s) returned, showing the first "
221
- f"{config.MAX_REVIEW_FINDINGS} (config.MAX_REVIEW_FINDINGS).")
221
+ f"{config.MAX_REVIEW_FINDINGS} (max_review_findings in config.yaml).")
222
222
  findings = findings[:config.MAX_REVIEW_FINDINGS]
223
223
 
224
224
  return findings, response.thread_id
@@ -48,7 +48,7 @@ logger = logging.getLogger(__name__)
48
48
 
49
49
  # Country-code second-level registries that gate registration the way the
50
50
  # bare TLDs do -- `gov.uk`, `ac.uk`, `edu.au`, `mil.br`. DERIVED rather
51
- # than enumerated in config.py: the list is `{kind}.{cc}` across every
51
+ # than enumerated in config.yaml: the list is `{kind}.{cc}` across every
52
52
  # ccTLD, which is several hundred rows to write and one rule to state.
53
53
  #
54
54
  # `ac` is here and NOT in the bare-TLD table on purpose: `.ac` alone is