@yahyahammad/venastine 0.3.14 → 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 |
@@ -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` — 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
@@ -1575,7 +1575,7 @@ def _effort_levels(client, provider_name: str, model: str) -> tuple:
1575
1575
  if levels is None:
1576
1576
  logger.warning(
1577
1577
  "No effort levels known for %r on %s; assuming %s. Add an entry "
1578
- "to config.MODEL_EFFORT_LEVELS if this is wrong.",
1578
+ "to model_effort_levels in config.yaml if this is wrong.",
1579
1579
  model, provider_name, config.DEFAULT_EFFORT_LEVELS,
1580
1580
  )
1581
1581
  levels = list(config.DEFAULT_EFFORT_LEVELS)
@@ -1804,7 +1804,7 @@ def context_window_for(client, provider_name: str, model: str) -> tuple:
1804
1804
  giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
1805
1805
  logger.warning(
1806
1806
  "Could not read a context window for %r from %s (%s); "
1807
- "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
1807
+ "model_context_windows in config.yaml will answer instead.%s",
1808
1808
  model, provider_name, e,
1809
1809
  " Not asking again this session." if giving_up else "")
1810
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 "",
@@ -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:
@@ -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
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.
package/main.py CHANGED
@@ -395,7 +395,7 @@ def _announce_posture() -> None:
395
395
  app.log and, on the CLI, to stderr through the root handler -- it is
396
396
  the record a bug report is triaged against. The stderr banner is for
397
397
  the human at the terminal, who may have set one of these months ago
398
- and forgotten, or may have inherited a config.py from somewhere.
398
+ and forgotten, or may have inherited a config.yaml from somewhere.
399
399
 
400
400
  Silent when the posture is shipped, so this costs nothing in the case
401
401
  that needs nothing said. That is also why it reads `unsafe_reasons()`
@@ -408,7 +408,7 @@ def _announce_posture() -> None:
408
408
  if not reasons:
409
409
  return
410
410
  print("", file=sys.stderr)
411
- print(" !! REDUCED SECURITY POSTURE -- set in config.py", file=sys.stderr)
411
+ print(" !! REDUCED SECURITY POSTURE -- set in config.yaml", file=sys.stderr)
412
412
  for _label, detail in reasons:
413
413
  logger.warning("Reduced security posture: %s", detail)
414
414
  print(f" - {detail}", file=sys.stderr)
@@ -2233,7 +2233,7 @@ def run_research(
2233
2233
  """Run the full deep-research pipeline, write artifacts to disk,
2234
2234
  and print the results. ensemble_mode/ensemble_n come from
2235
2235
  settings.json (§14); None means the pipeline falls back to the
2236
- config.py defaults. authorization (§25) comes from
2236
+ config.yaml defaults. authorization (§25) comes from
2237
2237
  build_research_authorization(); None means no gated tool is reachable,
2238
2238
  which is the behaviour every research run had before §25.
2239
2239
 
@@ -2394,7 +2394,7 @@ def build_parser() -> argparse.ArgumentParser:
2394
2394
  )
2395
2395
  # Defaults are None so that after parsing we can tell an explicit
2396
2396
  # CLI choice from argparse fill-in; resolution happens in main via
2397
- # resolve_runtime_defaults (CLI > settings.json > config.py).
2397
+ # resolve_runtime_defaults (CLI > settings.json > config.yaml).
2398
2398
  parser.add_argument(
2399
2399
  "--provider",
2400
2400
  default=None,
@@ -2420,7 +2420,7 @@ def build_parser() -> argparse.ArgumentParser:
2420
2420
  metavar="LEVEL",
2421
2421
  help="Reasoning effort for chat AND research (typically "
2422
2422
  "low|medium|high; 'auto' sends none). Default: settings.json "
2423
- "'effort' key, else config.DEFAULT_EFFORT.",
2423
+ "'effort' key, else default_effort in config.yaml.",
2424
2424
  )
2425
2425
  # ROADMAP_v2 §25. TWO flags onto ONE dest, in a mutually exclusive
2426
2426
  # group, rather than a single nargs="?" flag with an optional value.
@@ -2457,7 +2457,7 @@ def build_parser() -> argparse.ArgumentParser:
2457
2457
  "Never persisted.",
2458
2458
  )
2459
2459
  # R9/R12. Default None so settings.json can supply it and an explicit
2460
- # flag still wins (§14's CLI > settings.json > config.py precedence,
2460
+ # flag still wins (§14's CLI > settings.json > config.yaml precedence,
2461
2461
  # which only works because argparse defaults stay None).
2462
2462
  #
2463
2463
  # The MODE is persistable where the grant list is not, and the
@@ -2496,7 +2496,7 @@ def build_parser() -> argparse.ArgumentParser:
2496
2496
  action="store_const",
2497
2497
  const=False,
2498
2498
  help="Research mode: skip the post-pipeline review even if "
2499
- "settings.json or config.py turns it on.",
2499
+ "settings.json or config.yaml turns it on.",
2500
2500
  )
2501
2501
  parser.add_argument(
2502
2502
  "--tui",
@@ -2546,7 +2546,7 @@ def build_parser() -> argparse.ArgumentParser:
2546
2546
  metavar="THREAD",
2547
2547
  action="append",
2548
2548
  help="Attach another thread's summary to this session as context. "
2549
- "Repeatable, up to config.MAX_INJECTED_REFS.",
2549
+ "Repeatable, up to max_injected_refs in config.yaml.",
2550
2550
  )
2551
2551
  # ROADMAP_v2 §24. A flag for M21's reason, and the two kind flags exist
2552
2552
  # so a piped run can skip the question rather than being refused.
@@ -2584,7 +2584,7 @@ def build_parser() -> argparse.ArgumentParser:
2584
2584
  def resolve_runtime_defaults(args, settings: dict) -> tuple[str, str]:
2585
2585
  """Provider/model precedence: explicit CLI flag > settings.json
2586
2586
  (trusted project tier already beat user tier inside the loader) >
2587
- config.py constants."""
2587
+ config.yaml's values."""
2588
2588
  provider = args.provider or settings.get("default_provider") or DEFAULT_PROVIDER
2589
2589
  model = args.model or settings.get("default_model") or config.MODEL_NAME
2590
2590
  return provider, model
@@ -70,7 +70,7 @@ SHUTDOWN_TIMEOUT_S = 15.0
70
70
  # F6 (#64): the WHOLE teardown -- polite close, force-cancel, loop-thread
71
71
  # join -- shares this one wall-clock budget, instead of three sequential
72
72
  # SHUTDOWN_TIMEOUT_S waits whose worst case hung a quitting harness ~45s.
73
- # Master value lives in config.py beside the other harness bounds; the
73
+ # Master value lives in config.yaml beside the other harness bounds; the
74
74
  # re-export here keeps it beside its sibling timeouts and gives tests a
75
75
  # single name to shrink.
76
76
  TEARDOWN_BUDGET_S = _harness_config.TEARDOWN_BUDGET_S
@@ -131,7 +131,7 @@ class MemoryManager:
131
131
  if total > cap:
132
132
  logger.warning(
133
133
  "Injecting %s of %s memories; the oldest %s are not in this "
134
- "prompt. Raise config.MAX_INJECTED_MEMORIES or prune with "
134
+ "prompt. Raise max_injected_memories in config.yaml or prune with "
135
135
  "/forget.", cap, total, total - cap)
136
136
  header = (f"{header}\n\nShowing the {cap} most recent of {total}. "
137
137
  f"Older ones exist and are not listed here.")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yahyahammad/venastine",
3
- "version": "0.3.14",
3
+ "version": "0.3.15",
4
4
  "description": "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline.",
5
5
  "keywords": [
6
6
  "agent",
@@ -106,9 +106,9 @@ OMITTED = {
106
106
  "disagreement routes a claim to be checked and subtracts nothing, "
107
107
  "and the loader warns when this is set",
108
108
  "ensemble_mode":
109
- "resolved as `config.ENSEMBLE_MODE if value is None`, so writing "
110
- "`false` is not a restatement of the default but a decision to "
111
- "outrank whatever config.py says later",
109
+ "an unset value defers to config.yaml's own ensemble_mode, so "
110
+ "writing `false` is not a restatement of the default but a "
111
+ "decision to outrank whatever config.yaml says later",
112
112
  "compaction.trigger_tokens":
113
113
  "_trigger_is_configured() is a PRESENCE test: the window-derived "
114
114
  "trigger only applies while no human has named a number. Writing "
@@ -117,7 +117,7 @@ OMITTED = {
117
117
  "much earlier fold with nothing on screen to explain it",
118
118
  "research.subagent_review":
119
119
  "same `is not None` shape as ensemble_mode: an explicit false "
120
- "beats config.SUBAGENT_REVIEW rather than deferring to it",
120
+ "beats config.yaml's subagent_review rather than deferring to it",
121
121
  "tui.theme":
122
122
  "no shipped default to write -- absent, _startup_theme() resolves "
123
123
  "one -- and an invented value would outrank a theme the user "
package/pyproject.toml CHANGED
@@ -18,7 +18,7 @@ build-backend = "setuptools.build_meta"
18
18
 
19
19
  [project]
20
20
  name = "venastine-research-harness"
21
- version = "0.3.14"
21
+ version = "0.3.15"
22
22
  description = "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline."
23
23
  readme = "README.md"
24
24
  # The same words as package.json's `keywords`, in the same order: what a
@@ -19,9 +19,10 @@ the precedent: `tools/builtin/_math_common.py` exists because "an
19
19
  expression string is code", and its docstring lists the escapes that were
20
20
  found before the AST allowlist went in.
21
21
 
22
- So the posture is bound once and frozen (UN1). The `config.py` constants
23
- are still where a HUMAN writes the value; they simply stop being what is
24
- read at the moment a decision is made.
22
+ So the posture is bound once and frozen (UN1). `config.yaml` is still
23
+ where a HUMAN writes the value, and the `config.py` constants that
24
+ publish it simply stop being what is read at the moment a decision is
25
+ made.
25
26
 
26
27
  WHAT THE GUARANTEE IS, AND IS NOT
27
28
  ---------------------------------
@@ -254,7 +255,7 @@ class Posture:
254
255
  if self.shell_approval_mode == "never":
255
256
  reasons.append((
256
257
  "shell: never ask",
257
- "SHELL_APPROVAL_MODE is 'never' -- no shell command is "
258
+ "shell_approval_mode is 'never' -- no shell command is "
258
259
  "ever asked about, including one that reads outside the "
259
260
  "workspace on the host"))
260
261
  elif self.shell_approval_mode == "contained":
@@ -264,7 +265,7 @@ class Posture:
264
265
  # holds a `.venastine/` that code can read it.
265
266
  reasons.append((
266
267
  "shell: contained",
267
- "SHELL_APPROVAL_MODE is 'contained' -- a command that runs "
268
+ "shell_approval_mode is 'contained' -- a command that runs "
268
269
  "in the container without network runs without asking, "
269
270
  "including code the agent wrote itself; host reads and "
270
271
  "network commands still ask"))
@@ -279,7 +280,7 @@ class Posture:
279
280
  "asks, as under tiered")
280
281
  reasons.append((
281
282
  "shell: classified",
282
- "SHELL_APPROVAL_MODE is 'classified' -- a decision model "
283
+ "shell_approval_mode is 'classified' -- a decision model "
283
284
  f"({who}) decides whether a single command that runs in the "
284
285
  "container, and that tiered would ask about, runs without "
285
286
  "asking; compound commands, host reads, the host fallback, "
@@ -293,14 +294,14 @@ class Posture:
293
294
  and self.shell_approval_mode != "always"):
294
295
  reasons.append((
295
296
  "host shell, no ask",
296
- "ALLOW_INSECURE_SANDBOX_FALLBACK and "
297
- "AUTO_APPROVE_SANDBOX_FALLBACK are both on -- unprompted "
297
+ "allow_insecure_sandbox_fallback and "
298
+ "auto_approve_sandbox_fallback are both on -- unprompted "
298
299
  "arbitrary code on the host, with your own file access, "
299
300
  "including writes into this harness's own source"))
300
301
  elif self.allow_insecure_fallback:
301
302
  reasons.append((
302
303
  "host shell fallback",
303
- "ALLOW_INSECURE_SANDBOX_FALLBACK is on -- if no container "
304
+ "allow_insecure_sandbox_fallback is on -- if no container "
304
305
  "runtime (Docker or Podman) can run the sandbox, commands "
305
306
  "run on the host with no filesystem or network isolation"))
306
307
  # ROADMAP_v3 §49 slice 3 (SS41). Reported when it is ENABLED rather
@@ -321,7 +322,7 @@ class Posture:
321
322
  # this is §48 (CE6)'s correction applied to a second pair.
322
323
  if (self.auto_approve_fallback
323
324
  and self.shell_approval_mode not in ("always", "never")):
324
- asking = ("AUTO_APPROVE_SANDBOX_FALLBACK is on as well, so "
325
+ asking = ("auto_approve_sandbox_fallback is on as well, so "
325
326
  "NOTHING there asks first -- that opt-in answers "
326
327
  "for the whole backend, not only for the host "
327
328
  "fallback it is named after. Running as root is "
@@ -332,7 +333,7 @@ class Posture:
332
333
  "runs as root always asks")
333
334
  reasons.append((
334
335
  "wsl backend",
335
- "ALLOW_WSL_BACKEND is on -- the agent can ask for a command "
336
+ "allow_wsl_backend is on -- the agent can ask for a command "
336
337
  "to run in WSL, which is not a sandbox: it reaches this "
337
338
  "harness's own config and authority files, has no memory or "
338
339
  "process limits, and can start Windows programs with your "
@@ -345,7 +346,7 @@ class Posture:
345
346
  if self.allow_ssh_backend:
346
347
  reasons.append((
347
348
  "ssh backend",
348
- "ALLOW_SSH_BACKEND is on -- the agent can ask for a command "
349
+ "allow_ssh_backend is on -- the agent can ask for a command "
349
350
  "to run on the configured remote host, which this harness "
350
351
  "cannot inspect: no isolation, no memory or process limits, "
351
352
  "and credentials it did not issue. Nothing runs there "
@@ -355,7 +356,7 @@ class Posture:
355
356
  if not self.redact_tool_outputs:
356
357
  reasons.append((
357
358
  "no redaction",
358
- "REDACT_TOOL_OUTPUTS is off -- credential-shaped strings "
359
+ "redact_tool_outputs is off -- credential-shaped strings "
359
360
  "in tool results are passed through unredacted"))
360
361
  elif self.redact_off_env:
361
362
  reasons.append((
@@ -3365,7 +3365,7 @@ def _unavailable_message(backend: str = BACKEND_CONTAINER) -> str:
3365
3365
  return (
3366
3366
  "No container runtime can run the sandbox"
3367
3367
  + (f" ({reason})" if reason else "")
3368
- + " and ALLOW_INSECURE_SANDBOX_FALLBACK is False. Install Docker or "
3368
+ + " and allow_insecure_sandbox_fallback is false. Install Docker or "
3369
3369
  "Podman for strong isolation, or set "
3370
3370
  "allow_insecure_sandbox_fallback: true in config.yaml to use the "
3371
3371
  "weaker subprocess fallback (no filesystem isolation, no network "
@@ -281,7 +281,7 @@ def _read_rich(resolved_path: str) -> str:
281
281
  consumer, it sits behind `read`, and `read` is globally denied and
282
282
  cannot be re-enabled at runtime -- so a default install carries neither
283
283
  it nor its eleven transitive distributions. Anyone who reaches here has
284
- enabled `read` in config.py, and the bare ModuleNotFoundError would name
284
+ enabled `read` in config.yaml, and the bare ModuleNotFoundError would name
285
285
  a package they never asked for and cannot place.
286
286
  """
287
287
  try:
@@ -144,7 +144,7 @@ logger = logging.getLogger(__name__)
144
144
  # read the posture at import time**, pinned by
145
145
  # test_posture.py::test_no_module_reads_the_posture_at_import.
146
146
  capability.validate_mode(config.SHELL_APPROVAL_MODE,
147
- "config.SHELL_APPROVAL_MODE")
147
+ "shell_approval_mode in config.yaml")
148
148
 
149
149
  # Compute the shell name once at import time to avoid blocking on
150
150
  # subprocess probes every time the schema is accessed. On Windows this
@@ -625,7 +625,7 @@ def _shell_approval_check(tool_name: str, params: dict) -> bool:
625
625
  """
626
626
  active = posture.current()
627
627
  mode = capability.validate_mode(active.shell_approval_mode,
628
- "config.SHELL_APPROVAL_MODE")
628
+ "shell_approval_mode in config.yaml")
629
629
  if mode == capability.ALWAYS:
630
630
  return True
631
631
  if mode == capability.NEVER:
@@ -878,7 +878,7 @@ def _interactive_approval_check(tool_name: str, params: dict) -> bool:
878
878
  """
879
879
  active = posture.current()
880
880
  mode = capability.validate_mode(active.shell_approval_mode,
881
- "config.SHELL_APPROVAL_MODE")
881
+ "shell_approval_mode in config.yaml")
882
882
  if mode == capability.ALWAYS:
883
883
  return True
884
884
  if mode == capability.NEVER:
@@ -1055,8 +1055,8 @@ def fallback_changed_refusal(command: str, docker_up: bool) -> str | None:
1055
1055
  if active.allow_insecure_fallback and not active.auto_approve_fallback:
1056
1056
  return ("Docker became unavailable after the approval check. "
1057
1057
  "The insecure subprocess fallback requires explicit "
1058
- "per-run approval (AUTO_APPROVE_SANDBOX_FALLBACK is "
1059
- "False). Please retry — the approval prompt will "
1058
+ "per-run approval (auto_approve_sandbox_fallback is "
1059
+ "false in config.yaml). Please retry — the approval prompt will "
1060
1060
  "appear this time.")
1061
1061
  return None
1062
1062
 
@@ -455,7 +455,7 @@ def input_approval_check(tool_name: str, params: dict) -> bool:
455
455
  return False
456
456
  active = posture.current()
457
457
  mode = capability.validate_mode(active.shell_approval_mode,
458
- "config.SHELL_APPROVAL_MODE")
458
+ "shell_approval_mode in config.yaml")
459
459
  if mode == capability.ALWAYS:
460
460
  return True
461
461
  if mode == capability.NEVER:
package/tui/app.py CHANGED
@@ -944,7 +944,7 @@ class VenastineApp(App):
944
944
  self._animations = tui_settings.get("animations", True)
945
945
  # §38 (O6). Render a turn's reasoning inline, or collapse it to the
946
946
  # animated one-line indicator. Defaulted HERE rather than in
947
- # config.py, following `animations` immediately above: config.py
947
+ # config.yaml, following `animations` immediately above: config.yaml
948
948
  # holds no TUI values and is plain-values-only. /thinking flips it
949
949
  # for the session and persists nothing, matching /effort.
950
950
  self._show_thinking = tui_settings.get("show_thinking", True)
@@ -1544,7 +1544,7 @@ class VenastineApp(App):
1544
1544
  from the trace.
1545
1545
 
1546
1546
  "(remembered)" marks a pair restored from the preference store
1547
- rather than resolved from settings.json or config.py (§43, RM3).
1547
+ rather than resolved from settings.json or config.yaml (§43, RM3).
1548
1548
  #138's rule: a launch should not have to be guessed at, and a
1549
1549
  session silently coming up on a model no config file names is
1550
1550
  exactly the confusion this feature would otherwise trade for the
@@ -6128,7 +6128,7 @@ def _cmd_window(app: VenastineApp, args: str) -> None:
6128
6128
  # the best reason to have this command -- a gateway or a self-hosted
6129
6129
  # endpoint can report its own default rather than the deployment's
6130
6130
  # real window -- so refusing would block precisely the case it exists
6131
- # for. The risk is named in the same terms config.py uses for the qwen
6131
+ # for. The risk is named in the same terms config.yaml uses for the qwen
6132
6132
  # entry: erring high means a hard context-limit error mid-run.
6133
6133
  reported = _reported_window(app)
6134
6134
  if reported and tokens > reported:
@@ -6297,9 +6297,10 @@ def _report_override(app: VenastineApp, key: str) -> None:
6297
6297
  elif _reported_window(app) is not None:
6298
6298
  source = f"reported by {app.provider_name}"
6299
6299
  elif compaction._normalized(app.model) in config.MODEL_CONTEXT_WINDOWS:
6300
- source = "config.MODEL_CONTEXT_WINDOWS"
6300
+ source = "model_context_windows in config.yaml"
6301
6301
  else:
6302
- source = "config.DEFAULT_CONTEXT_WINDOW (no entry for this model)"
6302
+ source = ("default_context_window in config.yaml "
6303
+ "(no entry for this model)")
6303
6304
  app._transcript.write_system(
6304
6305
  f"Context window: {effective:,} — {source}.")
6305
6306
  app._transcript.write_system(
@@ -6654,7 +6655,7 @@ def _clear_pipeline_role(app: VenastineApp, role: str, label: str) -> None:
6654
6655
  remaining = pipeline_models.resolve(role)
6655
6656
  if remaining:
6656
6657
  app._transcript.write_system(
6657
- f"config.py still sets {label}: {remaining['provider_name']} | "
6658
+ f"config.yaml still sets {label}: {remaining['provider_name']} | "
6658
6659
  f"{remaining['model']}.")
6659
6660
 
6660
6661
 
package/tui/themes.py CHANGED
@@ -29,8 +29,11 @@ here sets it: these fourteen are RGB palettes, which is the whole
29
29
  premise of the contrast floors they are held to.
30
30
  """
31
31
 
32
+ import colorsys
32
33
  import logging
33
34
 
35
+ from rich.color import Color as RichColor
36
+ from rich.color import ColorSystem
34
37
  from textual.color import Color
35
38
  from textual.theme import Theme
36
39
 
@@ -332,7 +335,102 @@ def _tint(colour: str, background: str,
332
335
  return Color.parse(colour).blend(Color.parse(background), factor).hex
333
336
 
334
337
 
335
- def role_styles(theme: Theme) -> dict[str, str]:
338
+ # Batch 257. How many colours the terminal can show, by the names Rich's
339
+ # `Console.color_system` reports them under. A blended band is designed
340
+ # in truecolour, and Rich ROUNDS every colour to the nearest one the
341
+ # terminal has. On 256 colours that sent dark-plain's added-line band
342
+ # (#1E2F27) to #000000 -- the page's own colour, so the band vanished --
343
+ # while the removed-line band (#35201F) landed on #5f0000 and stayed.
344
+ # Measured on the owner's WSL install, which runs with
345
+ # TERM=xterm-256color and no COLORTERM, so Rich picks 256 there.
346
+ TRUECOLOUR = "truecolor"
347
+ EIGHT_BIT = "256"
348
+ SIXTEEN = frozenset({"standard", "windows"})
349
+
350
+ #: The six hues the xterm cube can draw at a band's depth, in the order
351
+ #: of the hue circle from red. A channel is 1 where that hue has it.
352
+ _CUBE_HUES = ((1, 0, 0), (1, 1, 0), (0, 1, 0), (0, 1, 1), (0, 0, 1),
353
+ (1, 0, 1))
354
+
355
+ #: The same six as the terminal's own colour names, for a sixteen-colour
356
+ #: terminal: the colours git, diff and patch use there.
357
+ _ANSI_HUES = ("red", "yellow", "green", "cyan", "blue", "magenta")
358
+
359
+ #: The cube levels a 256-colour band takes, as (channel absent, channel
360
+ #: present). The cube's levels are 0, 95, 135, 175, 215 and 255.
361
+ #: On a dark page the band is the hue at the cube's first step out of
362
+ #: black (#005f00, #5f0000). On a light page it is the hue two steps in
363
+ #: from white (#afd7af, #d7afaf); one step in (#d7ffd7, #ffd7d7) stands
364
+ #: off light-plain's page at 1.06:1 and 1.13:1, under X7's 1.15 floor.
365
+ _CUBE_DARK = (0, 1)
366
+ _CUBE_LIGHT = (3, 4)
367
+
368
+
369
+ def _hue_sector(colour: str) -> int:
370
+ """Which of the six cube hues `colour` is nearest, as an index into
371
+ `_CUBE_HUES`. Rounding the hue to a sixth of the circle is all the
372
+ resolution a band at one cube step has."""
373
+ red, green, blue = Color.parse(colour).rgb
374
+ hue, _sat, _val = colorsys.rgb_to_hsv(red / 255, green / 255, blue / 255)
375
+ return round(hue * 6) % 6
376
+
377
+
378
+ def _cube_band(colour: str, dark: bool) -> int:
379
+ """`colour`'s hue as a band on the xterm cube, as a colour number.
380
+
381
+ Placed on the cube rather than blended and left to Rich to round,
382
+ because the rounding is what lost the band: the cube is fixed, so
383
+ a band chosen on it is the band the terminal paints. Still derived
384
+ from the theme's own hue (#116), only at the cube's resolution."""
385
+ absent, present = _CUBE_DARK if dark else _CUBE_LIGHT
386
+ red, green, blue = (present if channel else absent
387
+ for channel in _CUBE_HUES[_hue_sector(colour)])
388
+ return 16 + 36 * red + 6 * green + blue
389
+
390
+
391
+ def _as_256(colour: str) -> int:
392
+ """The colour number Rich paints `colour` as on a 256-colour
393
+ terminal: its own downgrade, so the comparison below is against the
394
+ page the reader actually sees."""
395
+ return RichColor.parse(colour).downgrade(ColorSystem.EIGHT_BIT).number
396
+
397
+
398
+ def _diff_styles(palette: dict[str, str], dark: bool,
399
+ depth: str | None) -> tuple[str, str]:
400
+ """The added and removed rows' styles at the terminal's colour depth.
401
+
402
+ Truecolour, and a depth Rich could not name, keep X7's blended band.
403
+ 256 colours put the band on the cube (`_cube_band`). Sixteen colours
404
+ have no band to give, so the row takes the hue as its TEXT colour,
405
+ the ANSI themes' rule. An ANSI theme keeps that rule at every depth:
406
+ its colours are the terminal's own, with no RGB to measure.
407
+
408
+ A 256-colour band that would land on the page's own colour, or on
409
+ the other band, falls back to the sixteen-colour form. No shipped
410
+ theme reaches it (tests/test_themes.py holds that); a theme from
411
+ ctrl+p's list might.
412
+ """
413
+ success, error = palette["success"], palette["error"]
414
+ page, text = palette["background"], palette["foreground"]
415
+ measured = all(c.startswith("#") for c in (success, error, page))
416
+ if not measured:
417
+ add, delete = _tint(success, page), _tint(error, page)
418
+ return (f"{text} on {add}" if add else success,
419
+ f"{text} on {delete}" if delete else error)
420
+ as_text = (_ANSI_HUES[_hue_sector(success)],
421
+ _ANSI_HUES[_hue_sector(error)])
422
+ if depth in SIXTEEN:
423
+ return as_text
424
+ if depth == EIGHT_BIT:
425
+ add, delete = _cube_band(success, dark), _cube_band(error, dark)
426
+ if add == delete or _as_256(page) in (add, delete):
427
+ return as_text
428
+ return f"{text} on color({add})", f"{text} on color({delete})"
429
+ return (f"{text} on {_tint(success, page)}",
430
+ f"{text} on {_tint(error, page)}")
431
+
432
+
433
+ def role_styles(theme: Theme, depth: str | None = TRUECOLOUR) -> dict[str, str]:
336
434
  """Rich style strings keyed by transcript role, for one theme.
337
435
 
338
436
  Roles are what a line MEANS, not where it came from: `pass` covers a
@@ -344,10 +442,16 @@ def role_styles(theme: Theme) -> dict[str, str]:
344
442
  leave a slot at None or fill it with textual's `ansi_*` names,
345
443
  and one of them took the whole app down at mount. `_palette`
346
444
  fills and translates; nothing below can see the difference.
445
+
446
+ `depth` is the terminal's colour depth as Rich names it, and only
447
+ the two diff rows read it (batch 257): they are the one place this
448
+ table sets a background, and a background is what Rich's rounding
449
+ can merge into the page. Every other role is a foreground, which
450
+ rounding moves but cannot hide. The default is truecolour, which is
451
+ what every caller but `styles_for` means.
347
452
  """
348
453
  palette = _palette(theme)
349
- add = _tint(palette["success"], palette["background"])
350
- delete = _tint(palette["error"], palette["background"])
454
+ diff_add, diff_del = _diff_styles(palette, theme.dark, depth)
351
455
  return {
352
456
  # Who is speaking. The hues, because these distinguish identity.
353
457
  "user": f"bold {palette['primary']}",
@@ -443,10 +547,12 @@ def role_styles(theme: Theme) -> dict[str, str]:
443
547
  # was the alternative, and DIFF_TINT's comment above turns that
444
548
  # down for every theme that CAN be measured; picking it for the
445
549
  # one that cannot would be backwards.
446
- "diff_add": (f"{palette['foreground']} on {add}" if add
447
- else palette["success"]),
448
- "diff_del": (f"{palette['foreground']} on {delete}" if delete
449
- else palette["error"]),
550
+ #
551
+ # And unless the terminal cannot show the blend. `_diff_styles`
552
+ # puts the band on the xterm cube at 256 colours and falls back
553
+ # to the foreground form at sixteen (batch 257).
554
+ "diff_add": diff_add,
555
+ "diff_del": diff_del,
450
556
  # Unchanged context recedes: it is there to place the change,
451
557
  # not to be read. `secondary` rather than a dimmed foreground
452
558
  # for X1's reason -- `dim` is an attribute no floor can
@@ -509,6 +615,21 @@ def role_styles(theme: Theme) -> dict[str, str]:
509
615
  _UNSTYLABLE: set[str] = set()
510
616
 
511
617
 
618
+ def colour_depth(app) -> str | None:
619
+ """How many colours `app`'s terminal shows, as Rich names it.
620
+
621
+ Read off Textual's own console, because that console is what renders
622
+ the screen: Rich decides the depth there from COLORTERM and TERM
623
+ (TEXTUAL_COLOR_SYSTEM overrides it), and downgrades every colour to
624
+ it on the way out. None when it cannot be read, which `role_styles`
625
+ treats as truecolour -- what this module did before it asked.
626
+ """
627
+ try:
628
+ return app.console.color_system
629
+ except Exception: # noqa: BLE001 -- no console yet; keep the blend
630
+ return None
631
+
632
+
512
633
  def styles_for(app) -> dict[str, str]:
513
634
  """The active theme's role styles, or unstyled when there is no app.
514
635
 
@@ -550,7 +671,7 @@ def styles_for(app) -> dict[str, str]:
550
671
  if theme is None:
551
672
  return {}
552
673
  try:
553
- return role_styles(theme)
674
+ return role_styles(theme, colour_depth(app))
554
675
  except Exception: # noqa: BLE001 -- a theme this build cannot resolve
555
676
  name = getattr(theme, "name", "?")
556
677
  if name not in _UNSTYLABLE:
package/tui/widgets.py CHANGED
@@ -430,7 +430,7 @@ class PostureBadge(Static):
430
430
  §40 (UN3). The startup banner scrolls away; a posture does not. The
431
431
  case this exists for is not the researcher who just typed a flag --
432
432
  it is the user who set `ALLOW_INSECURE_SANDBOX_FALLBACK` months ago
433
- and forgot, or who inherited a config.py from somewhere. Neither of
433
+ and forgot, or who inherited a config.yaml from somewhere. Neither of
434
434
  them reads app.log.
435
435
 
436
436
  Hidden when the posture is the shipped one, GoalBanner-style, so it