@yahyahammad/venastine 0.3.13 → 0.3.15

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
 
@@ -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 | `low`, `medium`, `high` assumed for unknown models | 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 |
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 |
@@ -1058,7 +1058,7 @@ Deliberately not settings.json keys: editing these means editing the harness's o
1058
1058
 
1059
1059
  **Built:** ROADMAP.md §1–§12 (§10's ensemble mode rebuilt by its revisit — diversity now comes from a roster of different models) and ROADMAP_v2.md §13 (streaming loop), §14 (config loader + workspace trust), §15 (permissions), §16 (TUI), §17 (MCP), §18 (agents), §19 (skills), §20 (post-pipeline review), §21a (compaction + `pin`), §21b (durable memory), §22 (live pipeline progress), §25 (authorised tool use in the pipeline), §26 (research legibility: per-pass tool calls, code-stage announcements, the claims view, role colour, `/copy`), §27 (thread legibility: transcript replay on resume, a conversations-only thread picker), §21c (session summaries and cross-thread referencing — §21 is now complete), §24 (`/init`), §23 (interactive tools: the response channel, per-tool subagent sign-off, `ask_user`, and the todo list), §28 (the shell capability classifier).
1060
1060
 
1061
- **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§59 and §61–§93 are built. The section still to build is §60 (Unified Harness Protocol compliance), specified and awaiting detailed design. §56 lets a decision model approve a single contained shell command under the opt-in `classified` mode; §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. `TECHNICAL_DEBT.md` items 14, 17, 18, 21, 102 and 116 are open, and so is the secrets half of item 97. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
1061
+ **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§59, §61–§93 and §95 are built. The section still to build is §60 (Unified Harness Protocol compliance), specified and awaiting detailed design. §56 lets a decision model approve a single contained shell command under the opt-in `classified` mode; §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. `TECHNICAL_DEBT.md` items 14, 17, 18, 21, 102 and 116 are open, and so is the secrets half of item 97. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
1062
1062
 
1063
1063
  **And both audits are closed.** Both roadmaps being built is not the same as the code
1064
1064
  being clean, and saying only the first would be the "built and runs are different claims"
@@ -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` — 9310 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` — 9461 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
@@ -198,6 +198,25 @@ def accepts_images(provider_name: str) -> bool:
198
198
  return isinstance(entry, dict) and entry.get("accepts_images") is True
199
199
 
200
200
 
201
+ def reasoning_not_echoed(provider_name: str) -> bool:
202
+ """ROADMAP_v3 §95 (RO7). Whether this is an OpenAI-compatible provider
203
+ whose reasoning does NOT go back to it on the next request.
204
+
205
+ The question a reasoning-only reply raises: on that wire `echoes_reasoning`
206
+ is opt-in (§44 WS4), and measured on one provider, a model that never saw
207
+ its earlier reasoning wrote its tool call inside its reasoning on 8 of 23
208
+ replays of a tool-loop step, against 0 of 23 with the reasoning sent back.
209
+ Read with the same truthiness `call_model_stream` gives both flags, so
210
+ this answers what the request will actually do, not what the file
211
+ should have said. Every other provider sends its own reasoning back by
212
+ its own route, and answers False.
213
+ """
214
+ entry = load_provider_data().get(provider_name, {})
215
+ return (isinstance(entry, dict)
216
+ and bool(entry.get("is_v1_compatible", False))
217
+ and not entry.get("echoes_reasoning", False))
218
+
219
+
201
220
  # ============================================================================
202
221
  # ---- Normalized response shape ---------------------------------------------
203
222
  # ============================================================================
@@ -1556,7 +1575,7 @@ def _effort_levels(client, provider_name: str, model: str) -> tuple:
1556
1575
  if levels is None:
1557
1576
  logger.warning(
1558
1577
  "No effort levels known for %r on %s; assuming %s. Add an entry "
1559
- "to config.MODEL_EFFORT_LEVELS if this is wrong.",
1578
+ "to model_effort_levels in config.yaml if this is wrong.",
1560
1579
  model, provider_name, config.DEFAULT_EFFORT_LEVELS,
1561
1580
  )
1562
1581
  levels = list(config.DEFAULT_EFFORT_LEVELS)
@@ -1785,7 +1804,7 @@ def context_window_for(client, provider_name: str, model: str) -> tuple:
1785
1804
  giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
1786
1805
  logger.warning(
1787
1806
  "Could not read a context window for %r from %s (%s); "
1788
- "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
1807
+ "model_context_windows in config.yaml will answer instead.%s",
1789
1808
  model, provider_name, e,
1790
1809
  " Not asking again this session." if giving_up else "")
1791
1810
  if giving_up:
@@ -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 "",
@@ -833,11 +833,15 @@ def compactable_span(memory, current_turn_start: Optional[int] = None,
833
833
  Reading everything from `rows` makes the mismatch unrepresentable
834
834
  rather than merely fixed.
835
835
  """
836
- from storage import _ordered_rows
836
+ from storage import _ordered_rows, starts_turn
837
837
 
838
838
  settings = config_loader.effective_compaction(overrides)
839
839
  rows = _ordered_rows(memory.thread_id)
840
- starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
840
+ # `starts_turn`, not `role == "user"` (ROADMAP_v3 §95, RO3): a harness
841
+ # row the loop wrote inside a turn would otherwise be a fold boundary,
842
+ # and `completed_turns()` -- which this list must agree with -- does
843
+ # not count it.
844
+ starts = [i for i, row in enumerate(rows) if starts_turn(row)]
841
845
  if not starts:
842
846
  return None
843
847
 
@@ -1084,7 +1088,7 @@ def pin_measurements(thread_id, last_n: int, model: Optional[str] = None,
1084
1088
  calls this from outside a run moves.
1085
1089
  """
1086
1090
  from core import config_loader
1087
- from storage import _ordered_rows
1091
+ from storage import _ordered_rows, starts_turn
1088
1092
 
1089
1093
  settings = config_loader.effective_compaction()
1090
1094
  # THE MINIMUM, and the min() is load-bearing rather than defensive.
@@ -1114,7 +1118,9 @@ def pin_measurements(thread_id, last_n: int, model: Optional[str] = None,
1114
1118
  max_tokens = int(config.PIN_MAX_TRIGGER_FRACTION * trigger)
1115
1119
 
1116
1120
  rows = _ordered_rows(thread_id)
1117
- starts = [i for i, row in enumerate(rows) if row["role"] == "user"]
1121
+ # The turns `pin_last` counts, so the cap measures what the pin will
1122
+ # flag (ROADMAP_v3 §95, RO3).
1123
+ starts = [i for i, row in enumerate(rows) if starts_turn(row)]
1118
1124
  bounds = starts + [len(rows)]
1119
1125
 
1120
1126
  def _tokens(lo: int) -> int:
@@ -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
@@ -53,9 +53,11 @@ from core.client import (
53
53
  call_model_stream,
54
54
  context_window_for,
55
55
  effort_for,
56
+ reasoning_not_echoed,
56
57
  )
57
58
  from core.events import LoopEvent
58
59
  from core.memory import ConversationMemory
60
+ from core.replay import reasoning_text
59
61
  from safety.policy_enforcement import redact_diagnostic_text
60
62
 
61
63
  # §27 (T1). The loop is where a thread's kind is DECIDED -- it knows which
@@ -237,7 +239,7 @@ def with_refs(system_prompt: str, memory: ConversationMemory) -> str:
237
239
  if total > cap:
238
240
  logger.warning(
239
241
  "Injecting %s of %s attached references; the rest are not in this "
240
- "prompt. Raise config.MAX_INJECTED_REFS or drop one with "
242
+ "prompt. Raise max_injected_refs in config.yaml or drop one with "
241
243
  "/ref --clear.", cap, total)
242
244
  header = (f"{header}\n\nShowing {cap} of {total} attached references. "
243
245
  f"The others exist and are not included here.")
@@ -426,7 +428,7 @@ def attach_ref(memory: ConversationMemory, thread_id, summary: str,
426
428
  if existing is None and len(refs) >= config.MAX_INJECTED_REFS:
427
429
  return False, (
428
430
  f"Already referencing {len(refs)} conversations, which is the "
429
- 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 "
430
432
  f"first -- none is removed automatically.")
431
433
 
432
434
  entry = {
@@ -668,6 +670,87 @@ def _already_said(notices, kind: str) -> bool:
668
670
  n["kind"] == kind for n in notices)
669
671
 
670
672
 
673
+ # ROADMAP_v3 §95. A REASONING-ONLY reply: the step returned readable
674
+ # reasoning and neither text nor a tool call. Measured on an
675
+ # OpenAI-compatible provider, 33 of its 316 turns came back this way, every
676
+ # one right after a tool result, with the model's tool call written out in
677
+ # its own markup INSIDE the reasoning -- the server only turns markup into a
678
+ # call when it appears after the model's end-of-reasoning delimiter, and
679
+ # reasoning is all this loop received. Before §95 such a step ended the turn
680
+ # as `complete` and said nothing, to the person or to the model.
681
+ #
682
+ # RO2: the loop asks ONCE per run, through a harness row, and a second
683
+ # reasoning-only reply ends the turn with a notice. The row's first line is
684
+ # also the live notice's text, so the line a person sees while the turn
685
+ # runs is the line its replay draws (RO5).
686
+ HARNESS_REASONING_ONLY = "reasoning_only"
687
+ REASONING_ONLY_END = "reasoning_only_end"
688
+ REASONING_ONLY_HEADER = (
689
+ "[harness] The last reply was reasoning only: no answer and no tool "
690
+ "call reached the harness, so nothing ran.")
691
+ _REASONING_ONLY_NUDGE = (
692
+ REASONING_ONLY_HEADER + "\n"
693
+ "A tool call written inside reasoning is not run. Make the call through "
694
+ "the tool-calling interface, or write the answer as the reply itself.")
695
+ _REASONING_ONLY_AGAIN = (
696
+ "The model replied with reasoning only again after the harness asked, "
697
+ "so this turn ends without an answer.")
698
+ _REASONING_ONLY_LAST_STEP = (
699
+ "The model replied with reasoning only on the last step this turn "
700
+ "allows, so it ends without an answer.")
701
+ # (provider, model) pairs whose echo hint was logged this process (RO7).
702
+ # Keyed like context_limit()'s warn-once set and for its reason: a session
703
+ # that switches model must still hear about the second one.
704
+ _reasoning_only_warned: set = set()
705
+
706
+
707
+ def _reasoning_only(response) -> bool:
708
+ """RO1. Readable reasoning, no text and no tool call.
709
+
710
+ READABLE reasoning, through the replay's own reader: a Google signature
711
+ block or Anthropic's `redacted_thinking` carries no prose, and a step
712
+ that held only those had nothing in it to have gone missing. Text that
713
+ is only whitespace counts as none, because none of it reaches a person.
714
+ """
715
+ return (not response.tool_calls
716
+ and not (response.text or "").strip()
717
+ and bool(reasoning_text(response.thinking)))
718
+
719
+
720
+ def _reasoning_only_reply(memory, provider_name, model, notices, *,
721
+ nudge: bool, again: bool):
722
+ """RO2/RO5. Ask the model once more, or say why the turn ends here.
723
+
724
+ Persist before emit (#42): the harness row is written before the
725
+ notice that describes it is yielded. The row is a user-role entry
726
+ because that is the only shape the model can be handed between two
727
+ steps on every wire, and `mid_turn` keeps it from opening a turn (RO3):
728
+ the compaction floor and the reopening request both read a user row as
729
+ the start of one.
730
+ """
731
+ key = (provider_name, model)
732
+ if key not in _reasoning_only_warned and reasoning_not_echoed(
733
+ provider_name):
734
+ _reasoning_only_warned.add(key)
735
+ logger.warning(
736
+ "%s/%s replied with reasoning only: no text and no tool call. "
737
+ "Some models expect their earlier reasoning back during a tool "
738
+ "loop; if this one does, set \"echoes_reasoning\": true for %s "
739
+ "in providers.json.", provider_name, model, provider_name)
740
+ if nudge:
741
+ memory.add_harness_message(
742
+ _REASONING_ONLY_NUDGE,
743
+ {"kind": HARNESS_REASONING_ONLY, "mid_turn": True})
744
+ notice = {"kind": HARNESS_REASONING_ONLY,
745
+ "text": REASONING_ONLY_HEADER}
746
+ else:
747
+ notice = {"kind": REASONING_ONLY_END,
748
+ "text": (_REASONING_ONLY_AGAIN if again
749
+ else _REASONING_ONLY_LAST_STEP)}
750
+ notices.append(notice)
751
+ yield LoopEvent(notice=notice)
752
+
753
+
671
754
  def _compactor_depth(context) -> int:
672
755
  """Where a compaction started from THIS loop sits in the agent stack.
673
756
 
@@ -1772,7 +1855,7 @@ class RunAgentLoop:
1772
1855
  f"max_steps must be a positive integer, got {max_steps!r}. "
1773
1856
  f"Agent definitions carrying an invalid max_steps are "
1774
1857
  f"repaired by the loader to {config.MAX_ITERATIONS} "
1775
- f"(config.MAX_ITERATIONS); direct callers must pass a valid "
1858
+ f"(max_iterations in config.yaml); direct callers must pass a valid "
1776
1859
  f"value themselves.")
1777
1860
  client = api_initialization(provider_name)
1778
1861
  # Validate the level against the model that will RECEIVE it, here
@@ -1894,7 +1977,12 @@ class RunAgentLoop:
1894
1977
  activity=activity, depth=_compactor_depth(context))
1895
1978
 
1896
1979
  response = None
1897
- for _ in range(max_steps):
1980
+ # ROADMAP_v3 §95 (RO2). Whether this run has already asked the model
1981
+ # to follow a reasoning-only reply. ONE ask per run: a model that
1982
+ # answers the ask with reasoning only again is not going to be
1983
+ # talked out of it by a second, and every ask is a billed step.
1984
+ nudged = False
1985
+ for step in range(max_steps):
1898
1986
  # §61 CN2, the step boundary -- and ABOVE the reset below,
1899
1987
  # which is the whole reason it sits here rather than at the
1900
1988
  # foot of the body. The response it reads is the PREVIOUS
@@ -2065,6 +2153,18 @@ class RunAgentLoop:
2065
2153
  return
2066
2154
 
2067
2155
  if not response.tool_calls:
2156
+ # ROADMAP_v3 §95. Below D20 and the budget stop, so the
2157
+ # reasoning-only step is persisted and paid for exactly
2158
+ # like any other, and a turn already over budget stops
2159
+ # rather than spending a step on the ask.
2160
+ if _reasoning_only(response):
2161
+ ask = not nudged and step < max_steps - 1
2162
+ yield from _reasoning_only_reply(
2163
+ memory, provider_name, model, notices,
2164
+ nudge=ask, again=nudged)
2165
+ if ask:
2166
+ nudged = True
2167
+ continue
2068
2168
  response.stop_reason = "complete"
2069
2169
  yield LoopEvent(
2070
2170
  final_response=response, stop_reason=response.stop_reason,
package/core/memory.py CHANGED
@@ -57,6 +57,7 @@ from storage import (
57
57
  pinned_through,
58
58
  save_message,
59
59
  set_pinned,
60
+ starts_turn,
60
61
  turn_start_ids,
61
62
  update_thread_extra,
62
63
  )
@@ -366,7 +367,9 @@ class ConversationMemory:
366
367
  """
367
368
  mark_turn_failed(self.thread_id, error)
368
369
  for entry in reversed(self._messages):
369
- if entry.get("role") == "user":
370
+ # The row storage chose (ROADMAP_v3 §95, RO3): a harness row
371
+ # the loop wrote inside the run did not start it.
372
+ if starts_turn(entry):
370
373
  entry["error"] = error
371
374
  break
372
375
 
@@ -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:
@@ -204,6 +204,21 @@ def _check(raw_text: str, validate: Optional[Callable]) -> None:
204
204
 
205
205
 
206
206
  def _parse_corrective(error: ValueError, raw_text: str) -> str:
207
+ if not raw_text.strip():
208
+ # ROADMAP_v3 §95 (RO6). Nothing to quote, and quoting nothing under
209
+ # "Start of your failed output" was measured to mislead: a model
210
+ # whose whole reply had arrived as reasoning read the empty quote
211
+ # as its reasoning being the invalid output, and resolved to stop
212
+ # reasoning. Say what the harness actually received.
213
+ return (
214
+ "Your last response contained no text at all, so there was no "
215
+ "JSON to parse. Anything written only in your reasoning is not "
216
+ "part of the response, and a tool call written there is not "
217
+ "run.\n\n"
218
+ "Respond again with ONLY valid JSON -- no preamble, no prose, "
219
+ "no code fence, just the JSON your original instructions "
220
+ "asked for."
221
+ )
207
222
  return (
208
223
  f"Your last response did not parse as valid JSON.\n\n"
209
224
  f"Parse error:\n{error}\n\n"
@@ -225,7 +225,10 @@ def _translate(pass_id: str, stream, corpus=None):
225
225
  second rendering of a question already on
226
226
  screen is not observability.
227
227
  notice a pass's compaction notices, forwarded as
228
- trace LINES. M6 makes these backstop-only,
228
+ trace LINES -- and since §95 its
229
+ reasoning-only notices, labelled `notice`
230
+ rather than `compaction` (RO8). M6 makes
231
+ the compaction ones backstop-only,
229
232
  but "rare" is not "silent" -- §21's rule
230
233
  has no exception for the pipeline, and a
231
234
  backstop fold rewrites what the REST of
@@ -266,9 +269,15 @@ def _translate(pass_id: str, stream, corpus=None):
266
269
  yield PipelineEvent(kind="pass_activity", pass_id=pass_id,
267
270
  chars=streamed)
268
271
  if event.notice:
272
+ # ROADMAP_v3 §95 (RO8). Labelled by what the notice IS: the loop
273
+ # emits a reasoning-only notice inside a pass too, and the trace
274
+ # called every notice a compaction.
275
+ what = ("compaction"
276
+ if str(event.notice.get("kind", "")).startswith(
277
+ "compaction") else "notice")
269
278
  yield PipelineEvent(
270
279
  kind="trace_line",
271
- text=f"compaction during {pass_id}: {event.notice['text']}")
280
+ text=f"{what} during {pass_id}: {event.notice['text']}")
272
281
  if event.tool_call_start:
273
282
  name = event.tool_call_start.get("name")
274
283
  names[event.tool_call_start.get("id")] = name
@@ -346,7 +355,7 @@ def _check_not_truncated(pass_id: str, response, trace: list[str] | None):
346
355
  f"condition returns the last response as it stands, so a pass "
347
356
  f"cut off mid-tool-call yields an empty string -- and every "
348
357
  f"later pass would be working from nothing. "
349
- f"(config.MAX_ITERATIONS and a configured settings.json "
358
+ f"(max_iterations in config.yaml and a configured settings.json "
350
359
  f"max_token_budget spend cap are the two ceilings that "
351
360
  f"produce this.)"
352
361
  )
@@ -1174,8 +1183,8 @@ def stream_deep_research_pipeline(
1174
1183
  # §45 (SQ7): through pipeline_models.resolve rather than
1175
1184
  # config.CRITIC_MODEL directly, so a `/critic` choice reaches the CLI,
1176
1185
  # the TUI and a spawned run alike. That function owns the precedence —
1177
- # the user-tier store outranks config.py — and owning it in one place
1178
- # 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
1179
1188
  # the methodology's own "a model must not check its own output" was
1180
1189
  # available only to whoever could edit the checkout.
1181
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
package/logging_setup.py CHANGED
@@ -44,7 +44,7 @@ _DEFAULT_DATEFMT = "%Y-%m-%d %H:%M:%S"
44
44
  _DEFAULT_LOG_FILE = "logs/app.log"
45
45
  _DEFAULT_LEVEL = "INFO"
46
46
 
47
- # Rotation defaults live here, not in config.py: this file owns the
47
+ # Rotation defaults live here, not in config.yaml: this file owns the
48
48
  # logging concern end-to-end (mirrors how ROADMAP.md §2 keeps the whole
49
49
  # logging subsystem in one file). Bump via the function signature if
50
50
  # needed; there is no project-wide reason to surface them as config yet.