@yahyahammad/venastine 0.3.8 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
package/config_edit.py CHANGED
@@ -1,1301 +1,1301 @@
1
- """config_edit.py -- the catalogue behind `/config`, and the writer under it.
2
-
3
- WHY THIS IS NOT IN `tui/`. AGENTS.md's rule for §16 is that the TUI is a
4
- SHELL rather than a feature home: anything implemented there is invisible to
5
- the CLI and to the research pipeline, which is why the question tool, the
6
- todo list, `/init` and session summaries are all specified outside it. The
7
- catalogue, the value grammar and the writer are the feature; `/config` is one
8
- surface over them, and a command-line surface can be added later without
9
- moving a line.
10
-
11
- WHY IT IS NOT IN `config_schema.py` EITHER. That module is the READER, and it
12
- carries a stated rule that it imports nothing first-party -- `config.py` and
13
- `core/config_loader.py` both sit on top of it, and an edge from there into
14
- `core/` puts the cycle back by a longer route. This module needs that edge:
15
- answering "what outranks this key" means reading `core/config_loader`'s
16
- settings tables. Nothing imports this module except `tui/` and `main.py`, so
17
- the cycle cannot form from this end either.
18
-
19
- FOUR RULES, all of them load-bearing.
20
-
21
- 1. A PROPOSED CHANGE IS VALIDATED AS THE BYTES IT WILL BECOME. `propose()`
22
- applies the edit to a round-trip tree, dumps it to text, re-parses THAT
23
- TEXT with `config_schema`'s own safe reader, and validates the result. Not
24
- the in-memory tree: the round-trip parser hands back its own scalar types,
25
- and what the next launch reads is bytes. Validating anything else would be
26
- certifying a document nobody will ever load.
27
-
28
- 2. THE WRITE PRESERVES EVERYTHING IT DID NOT CHANGE. `config.yaml` is 845
29
- lines, of which roughly 600 are the comments that say what each value does
30
- and which keys are AUTHORITY. A dump through `typ="safe"` would erase all
31
- of them, so the round-trip parser is configured here to reproduce this
32
- file exactly -- measured, byte for byte -- and a one-value change comes
33
- out as a one-line diff.
34
-
35
- 3. NOTHING HERE APPLIES A CHANGE TO A RUNNING PROCESS. `config.py` binds at
36
- import and `security/posture.py` depends on that (UN1); `tools/builtin/
37
- shell.py` validates the approval mode at ITS import. A reload would leave
38
- the frozen posture disagreeing with the file it came from. So the writer
39
- writes, and `RestartRequest` is how the change reaches a process that will
40
- read it.
41
-
42
- 4. THE AUTHORITY KEYS ARE MARKED, NOT BLOCKED (batch 84). `config_schema.
43
- HARNESS_AUTHORITY_KEYS` used to mean "no in-session surface may write
44
- this". It now means "no UNATTENDED surface may": a settings file still
45
- cannot reach these keys, nor an environment variable, nor a tool call.
46
- A person typing at the prompt can, behind a confirmation that names what
47
- the key permits.
48
-
49
- STATE THE FILE-TOOL HALF ACCURATELY -- this said "the file tools refuse
50
- the harness install tree" for three batches and they do not. Measured:
51
- `file_ops._protected_path_error` denies a path carrying a `.venastine`
52
- SEGMENT and nothing else, so `<install>/config.yaml` comes back allowed.
53
- What actually holds is weaker and still real: `write` and `edit` ship
54
- DENIED in `tool_permissions` and cannot be enabled at runtime, and
55
- `security/protected_paths` makes a workspace overlapping the harness tree
56
- a startup error -- so the install tree is never inside the workspace and
57
- a write there is approval-gated rather than auto-approved. That module's
58
- own docstring is why the wording matters: a half-understood control is
59
- worse than none.
60
- `AUTHORITY_EFFECT` below is that sentence, per key, and it is the reason
61
- the gate is not a generic "are you sure".
62
- """
63
-
64
- from __future__ import annotations
65
-
66
- import dataclasses
67
- import io
68
- import os
69
- import tempfile
70
- import types
71
- import typing
72
- from typing import Any, Optional
73
-
74
- from ruamel.yaml import YAML
75
- from ruamel.yaml.error import YAMLError
76
-
77
- import config_schema
78
-
79
- # The two nested tables, whose leaves are addressed `<table>.<tool>`. Named
80
- # once: the catalogue skips them as rows of their own and expands them
81
- # instead, and every other reference derives from this.
82
- TABLES = ("tool_permissions", "tool_approvals")
83
-
84
- #: What each authority key actually permits, in one sentence, for the
85
- #: confirmation that gates it. NOT a generic "are you sure" -- the whole
86
- #: argument for letting a slash command write these is that the person is
87
- #: told what they are turning on, so a missing entry here is a missing gate.
88
- #: `tests/test_config_edit.py` holds this against HARNESS_AUTHORITY_KEYS.
89
- AUTHORITY_EFFECT = {
90
- "shell_approval_mode": (
91
- "how often a shell command stops to ask you. `contained` runs any "
92
- "code the agent writes inside the container without asking, and "
93
- "`never` runs every command the agent writes without asking, "
94
- "including in a session where untrusted content is already in the "
95
- "context window."),
96
- "allow_insecure_sandbox_fallback": (
97
- "whether a shell command may run WITHOUT the container when neither "
98
- "Docker nor Podman can run one -- on the host, with your files."),
99
- "auto_approve_sandbox_fallback": (
100
- "whether that fallback to the host happens without asking you "
101
- "first."),
102
- "allow_wsl_backend": (
103
- "whether the agent may ask for a command to run in WSL instead "
104
- "of the container. WSL is not a sandbox: it reaches this "
105
- "harness's own config and authority files, has no memory or "
106
- "process limits, and can start Windows programs with your full "
107
- "authority."),
108
- "allow_ssh_backend": (
109
- "whether the agent may ask for a command to run on the remote "
110
- "host you configured, instead of the container. That is another "
111
- "machine this harness cannot inspect: no isolation, no memory or "
112
- "process limits, and it uses credentials you issued. Nothing "
113
- "runs there without asking you first."),
114
- "redact_tool_outputs": (
115
- "whether secrets are stripped from tool output before it reaches "
116
- "the model and the transcript."),
117
- "ensemble_models": (
118
- "which providers N research passes are sent to. Every entry is a "
119
- "provider that receives your research content."),
120
- "critic_model": (
121
- "which provider the grounding and critic passes are sent to. It "
122
- "receives the claims and the sources."),
123
- "embedder_model": (
124
- "which provider claim and source text is sent to for similarity "
125
- "scoring."),
126
- "tool_permissions": (
127
- "whether a tool may be called at all. This is the global floor -- "
128
- "no agent, skill or approval can widen it (D14)."),
129
- "tool_approvals": (
130
- "whether a tool stops to ask you before it runs. Turning one off "
131
- "removes a prompt you would otherwise see."),
132
- }
133
-
134
- #: config.yaml key -> the settings.json path that outranks it. Declared here
135
- #: rather than derived, because only one of the three sources IS a table:
136
- #: `_COMPACTION_DEFAULTS` maps settings key to field name and is inverted
137
- #: below, while the confidence and source-scoring defaults are hand-written
138
- #: return dicts and the top-level three are resolved in `main.py`. A test
139
- #: holds every name here against the schema and against the loader's known
140
- #: keys, so an added settings key that silently stops matching shows up as a
141
- #: failure rather than as a `/config` that quietly reports the wrong winner.
142
- _SETTINGS_OVERRIDES = {
143
- "model_name": "default_model",
144
- "default_effort": "effort",
145
- "ensemble_mode": "ensemble_mode",
146
- "authority_adjustment_cap": "source_scoring.authority_adjustment_cap",
147
- "scholar_venue_weight": "source_scoring.venue_weight",
148
- "scholar_citation_weight": "source_scoring.citation_weight",
149
- "scholar_author_weight": "source_scoring.author_weight",
150
- "scholar_h_saturation": "source_scoring.h_saturation",
151
- "scholar_min_cohort_size": "source_scoring.min_cohort_size",
152
- "scholar_min_citation_age_days": "source_scoring.min_citation_age_days",
153
- # main.py:resolve_review states the precedence in so many words --
154
- # `research.subagent_review > config.SUBAGENT_REVIEW` -- and this table
155
- # was missing it, so `/config subagent_review` reported nothing
156
- # outranking a key a settings file silently wins.
157
- "subagent_review": "research.subagent_review",
158
- }
159
-
160
-
161
- def settings_overrides() -> dict:
162
- """`{config.yaml key: settings.json path}`, compaction included.
163
-
164
- The seven compaction keys come from `core/config_loader`'s own table
165
- rather than being retyped, which is the same anti-drift move that table
166
- was created for: it maps settings key to schema field, so inverting it
167
- is the whole mapping with no second copy to go stale.
168
- """
169
- from core.config_loader import _COMPACTION_DEFAULTS
170
-
171
- merged = dict(_SETTINGS_OVERRIDES)
172
- for key, field in _COMPACTION_DEFAULTS.items():
173
- merged[field] = f"compaction.{key}"
174
- return merged
175
-
176
-
177
- @dataclasses.dataclass(frozen=True)
178
- class KeyRow:
179
- """One addressable name in `config.yaml`, as `/config` shows it.
180
-
181
- `name` is what the user types: a top-level key, or `<table>.<tool>` for
182
- the 45 leaves of the two permission tables. All 23 tool names appear in
183
- `tool_permissions`; all but `shell` appear in `tool_approvals`, whose
184
- approval is governed solely by `shell_approval_mode` -- so the prefix
185
- is not decoration, it is the only thing that tells
186
- `tool_permissions.shell` from `tool_approvals.read`.
187
-
188
- TWO VALUES, NOT ONE, and keeping them apart is batch 85's whole subject.
189
- `in_file` is what `config.yaml` says: the thing `/config` edits and the
190
- thing the next launch will read. `in_session` is what THIS process is
191
- running, bound at import and never re-read. They start equal for every
192
- key without an environment variable, and a write here moves the first
193
- without moving the second.
194
-
195
- One field for both was the defect. `/config` reported the SESSION's
196
- value everywhere -- the panel's `now`, the `(was ...)` on a write, the
197
- authority modal -- while writing against the FILE, so a second change to
198
- the same key in one session reported the value it had at launch as the
199
- one being replaced. The file was always right; only the reporting drifted,
200
- and only once someone did what `/config` is for.
201
- """
202
-
203
- name: str
204
- kind: str # "scalar" | "pair" | "container"
205
- values: str # the possible values, as a person reads them
206
- in_file: Any # what config.yaml says right now
207
- in_session: Any # what this process is running
208
- authority: bool
209
- #: The remembered `/model` pair, if the preference store holds one.
210
- #:
211
- #: A STORE FACT, not a session claim: it says what the user last chose,
212
- #: which the session runs only when no flag pinned the launch and the
213
- #: staleness key still matches -- facts `explain()` (which is told
214
- #: whether they hold) turns into the authoritative sentence. Set on the
215
- #: `model_name` row only; every other row carries None. Display-only:
216
- #: `pending` and every write path ignore it.
217
- remembered: Optional[tuple[str, str]] = None
218
- #: The environment variable that beats this key, `$`-prefixed, if any.
219
- #: STRUCTURED rather than folded into one display string: `pending` and
220
- #: `explain` both have to READ the variable's name, and a key can be
221
- #: outranked by a variable AND a settings.json key at once -- `model_name`
222
- #: is. One field for both meant whichever was found first was the only
223
- #: one ever reported, and the one that lost was `settings.json
224
- #: default_model`: the tier that arrives with a directory you cloned.
225
- environment_variable: Optional[str] = None
226
- #: The `settings.json` path that beats this key, if any.
227
- settings_key: Optional[str] = None
228
- #: True when the field is a string, so typed text is taken VERBATIM
229
- #: rather than parsed as YAML. Read off the annotation by `describe`,
230
- #: not recovered from `values` -- see that function.
231
- takes_text: bool = False
232
- #: True when the field accepts None, so a word in `NULL_WORDS` clears it.
233
- nullable: bool = False
234
-
235
- @property
236
- def outranked_by(self) -> Optional[str]:
237
- """Every source that beats this key, for display. None if none do."""
238
- sources = []
239
- if self.environment_variable:
240
- sources.append(f"${self.environment_variable}")
241
- if self.settings_key:
242
- sources.append(f"settings.json {self.settings_key}")
243
- return " and ".join(sources) if sources else None
244
-
245
- @property
246
- def settable(self) -> bool:
247
- return self.kind in ("scalar", "pair")
248
-
249
- @property
250
- def pending(self) -> bool:
251
- """Written, and waiting for a restart to take effect.
252
-
253
- NOT simply "the two differ". For the five keys with an environment
254
- variable the two differ from launch with nothing pending at all --
255
- the variable won when the file was read and will win again next
256
- time -- so a difference there says nothing about whether anyone
257
- changed anything. `outranked_by` already names the variable; this
258
- asks whether it is actually set.
259
-
260
- Every other key had the two equal at launch by construction, so a
261
- difference IS a change made since. That is why no snapshot of the
262
- file is taken at startup: there is nothing a snapshot would know
263
- that this does not.
264
-
265
- A CONTAINER IS NEVER PENDING. The document hands back the list or
266
- dict YAML spells where the model holds the frozenset or tuple its
267
- consumers rely on, so the two differ for every one of the sixteen,
268
- always -- and nothing can write one from here anyway, so there is
269
- nothing for such a row to be pending about. Without this line every
270
- container row read `pending restart` from launch.
271
- """
272
- if not self.settable:
273
- return False
274
- if self.in_file == self.in_session:
275
- return False
276
- if self.environment_variable:
277
- return os.environ.get(self.environment_variable) is None
278
- return True
279
-
280
- @property
281
- def summary(self) -> str:
282
- """The one-line description the suggestion panel draws.
283
-
284
- Values first, current second: the panel gives an entry two rendered
285
- rows and DROPS the rest, so the order is what survives a narrow
286
- terminal. What someone browsing needs is what they are allowed to
287
- type; the value in the file is the useful second half.
288
-
289
- THE FILE'S VALUE, because this panel is an editor and the file is
290
- what it edits. `pending` is how the running process gets its say in
291
- the one word that fits; the sentence naming what is still in force
292
- belongs in `explain()`, which has a whole transcript to write into
293
- instead of half a row. The last two parts are terse for the same
294
- reason.
295
- """
296
- parts = [self.values, f"now {shown(self.in_file)}"]
297
- if self.remembered is not None:
298
- provider, model = self.remembered
299
- parts.append(f"remembered {provider} | {model}")
300
- if self.pending:
301
- parts.append("pending restart")
302
- if self.outranked_by:
303
- parts.append(self.outranked_by)
304
- if self.authority:
305
- parts.append("authority")
306
- return " · ".join(parts)
307
-
308
-
309
- # ---------------------------------------------------------------------------
310
- # ---- Reading and writing the document -------------------------------------
311
- # ---------------------------------------------------------------------------
312
-
313
- def _round_trip() -> YAML:
314
- """The comment-preserving parser, configured to reproduce THIS file.
315
-
316
- Every setting here was measured against `config.yaml` rather than
317
- chosen: with the four below, a load-then-dump reproduces all 28,177
318
- bytes exactly, and without any one of them it does not.
319
-
320
- * `preserve_quotes` -- a quoted scalar stays quoted.
321
- * `indent(sequence=4, offset=2)` -- ruamel's default un-indents a
322
- list under its key, which moved every entry of the six list-valued
323
- keys two columns left.
324
- * the `null` representer -- ruamel writes a None as an EMPTY value,
325
- so `ensemble_models: null` became `ensemble_models:` and four other
326
- keys with it. Empty parses back to None, so this is cosmetic, but a
327
- write that silently reformats five lines it was not asked to touch
328
- is a write nobody can review.
329
- * `width` -- the default wraps long scalars at 80 columns, which
330
- would reflow the URL and the docker image tag.
331
-
332
- `typ="safe"` stays the READ path in `config_schema`, deliberately: that
333
- is the one that runs at every startup, and safe mode refuses
334
- `!!python/...` tags outright. This parser exists for the write path
335
- only, which is what `config_schema._reader` says it is for.
336
- """
337
- yaml = YAML(typ="rt")
338
- yaml.preserve_quotes = True
339
- yaml.width = 4096
340
- yaml.indent(mapping=2, sequence=4, offset=2)
341
- yaml.representer.add_representer(
342
- type(None),
343
- lambda representer, data: representer.represent_scalar(
344
- "tag:yaml.org,2002:null", "null"))
345
- return yaml
346
-
347
-
348
- def read_text() -> tuple[str, str]:
349
- """`(text, newline)` for the live document.
350
-
351
- The newline is carried out and back rather than normalised away. This
352
- repo is developed on Windows with `core.autocrlf=true`, so a worktree
353
- copy of a tracked file can be CRLF even though the index is LF and this
354
- particular file is LF today. ruamel emits `\\n` whatever it read, so a
355
- write that did not put the convention back would rewrite all 845 lines
356
- of a CRLF checkout to report a one-line change.
357
- """
358
- with open(config_schema.CONFIG_PATH, encoding="utf-8",
359
- newline="") as handle:
360
- raw = handle.read()
361
- newline = "\r\n" if "\r\n" in raw else "\n"
362
- return raw.replace("\r\n", "\n"), newline
363
-
364
-
365
- #: `((path, mtime_ns, size), tree)` for the last document parsed, or None.
366
- _document_cache = None
367
-
368
-
369
- def document(fresh: bool = False):
370
- """The live `config.yaml` as a round-trip tree, comments attached.
371
-
372
- CACHED ON THE FILE'S OWN STAMP, because `catalogue()` reads this on
373
- every keystroke the suggestion panel sees and parsing 845 lines costs
374
- about 70ms against the 0.7ms everything else in that path costs. A
375
- `stat` is microseconds, and the document changes about as often as a
376
- person types a `/config` command.
377
-
378
- `write()` clears the cache outright rather than trusting the stamp, and
379
- that is not belt-and-braces: `max_tokens: 16000` and `max_tokens: 18000`
380
- are the SAME SIZE, so mtime would be carrying the whole comparison, and
381
- two writes inside one filesystem timestamp tick would be invisible. The
382
- stamp stays for the case `write()` cannot see -- someone editing the
383
- file in another window while the harness is up.
384
-
385
- `fresh=True` skips it entirely, for a caller that is about to write.
386
- """
387
- global _document_cache
388
- path = config_schema.CONFIG_PATH
389
- stamp = None
390
- if not fresh:
391
- try:
392
- status = os.stat(path)
393
- stamp = (path, status.st_mtime_ns, status.st_size)
394
- except OSError:
395
- # Unreadable is `read_text`'s error to raise, with its message.
396
- stamp = None
397
- if stamp is not None and _document_cache is not None:
398
- cached_stamp, tree = _document_cache
399
- if cached_stamp == stamp:
400
- return tree
401
-
402
- text, _ = read_text()
403
- try:
404
- tree = _round_trip().load(io.StringIO(text))
405
- except YAMLError as exc:
406
- # TRANSLATED, NOT PROPAGATED, and `config_schema.read_document`
407
- # already chose this shape for the same question one module over.
408
- # Every reader in this file is reached from a slash command or a
409
- # keystroke, and a ruamel error derives from `Exception` and
410
- # nothing narrower -- so the shell either catches everything or
411
- # catches this. It should catch this.
412
- #
413
- # THE DIAGNOSIS IS SOUND RATHER THAN A GUESS: `config.py` reads
414
- # and validates this file at import, so the process could not
415
- # have started if it did not parse. If it does not parse now, it
416
- # has been edited since -- which is the workflow `explain()`
417
- # recommends in so many words.
418
- raise ValueError(
419
- f"{config_schema.CONFIG_PATH} can no longer be parsed "
420
- f"({exc}). It parsed when this session started, so it has "
421
- f"been edited since and the edit left it structurally "
422
- f"broken. Fix the file; the running session is unaffected "
423
- f"until you relaunch.") from exc
424
- if stamp is not None:
425
- # RE-STAT AFTER THE READ. The stamp above was taken BEFORE it, so an
426
- # external save landing between the two stored the new tree under
427
- # the old file's stamp -- and the next keystroke's stat then matched
428
- # it and served a parse of a file that no longer existed in that
429
- # form. Cheap to close, and a cache that can be one save stale is
430
- # worse than one that simply misses.
431
- try:
432
- after = os.stat(path)
433
- stamp = (path, after.st_mtime_ns, after.st_size)
434
- except OSError:
435
- stamp = None
436
- if stamp is not None:
437
- _document_cache = (stamp, tree)
438
- return tree
439
-
440
-
441
- def forget_document() -> None:
442
- """Drop the cached parse. Called by `write()`, and by tests."""
443
- global _document_cache
444
- _document_cache = None
445
-
446
-
447
- def _dump(tree) -> str:
448
- stream = io.StringIO()
449
- _round_trip().dump(tree, stream)
450
- return stream.getvalue()
451
-
452
-
453
- def _in_file(tree, name: str):
454
- """What the document says for one addressable name, or `ValueError`.
455
-
456
- THE DOCUMENT CAN DISAGREE WITH THE SCHEMA, and that is not a
457
- programming error here -- it is the documented workflow. `config.py`
458
- binds at import and nothing re-reads the file (UN1), while
459
- `explain()` tells every container row to "Edit it in config.yaml",
460
- so a hand-edit made mid-session leaves the process holding valid
461
- values over a file that no longer has the key.
462
-
463
- KeyError AND TypeError, because the file can go two ways and both
464
- were measured: a deleted or renamed key raises `KeyError`, and a
465
- table flattened to a scalar (`tool_permissions: off`) raises
466
- `TypeError: string indices must be integers` from the SECOND
467
- subscript. Neither is a `ValueError`, which is what the shell
468
- catches, and neither says which file it is about.
469
-
470
- REPLACES `get_leaf`, which answered the same question with no
471
- caller anywhere in the repository and would have been a third copy
472
- of this one.
473
- """
474
- try:
475
- if "." in name:
476
- table, leaf = name.split(".", 1)
477
- return tree[table][leaf]
478
- return tree[name]
479
- except KeyError:
480
- raise ValueError(
481
- f"{config_schema.CONFIG_PATH} no longer has a key called "
482
- f"{name}. It had one when this session started, so the file "
483
- f"has been edited since; relaunch to pick the change "
484
- f"up.") from None
485
- except TypeError as exc:
486
- raise ValueError(
487
- f"{config_schema.CONFIG_PATH} can no longer be read for "
488
- f"{name} ({exc}) -- the block it lives in is no longer a "
489
- f"table. It was one when this session started, so the file "
490
- f"has been edited since; relaunch to pick the change "
491
- f"up.") from exc
492
-
493
-
494
- def place(tree, name: str, value: Any) -> None:
495
- """Set a dotted name, keeping the prose that FOLLOWS it. Rule 2's teeth.
496
-
497
- `tree[name] = value` loses comments, in two different ways, and both
498
- were found by running it rather than by reading ruamel. Each costs the
499
- user documentation out of their own file, silently, on a write that
500
- reported itself as a one-line change.
501
-
502
- ONE: THE TEXT AFTER A BLOCK SEQUENCE IS ANCHORED TO ITS LAST INDEX.
503
- `node.ca.items[5]` on a six-entry list, not the key in the parent. So
504
- replacing `models_rejecting_sampling_params` took the
505
- `# Critic and embedder routing` banner and the AUTHORITY note under it
506
- with it -- six lines. Mutating the node in place does not help; measured.
507
-
508
- TWO: A VALUE THAT CHANGES SHAPE MOVES ITS PARENT'S COMMENT BETWEEN TWO
509
- SLOTS. For a scalar the following text sits in `ca.items[name][2]`; when
510
- the value becomes a block mapping ruamel moves it to slot 3 and emits it
511
- after the block. Going back -- `/config critic_model off` after setting
512
- a provider -- it writes a scalar again and slot 3 is never emitted, so
513
- `embedder_model`'s three-line AUTHORITY comment was deleted from the
514
- file. ruamel handles scalar -> block by itself; this handles the return
515
- trip, and the leading newline is what makes the result byte-identical to
516
- the document before the round trip rather than merely comment-complete.
517
- """
518
- from ruamel.yaml.comments import CommentedMap, CommentedSeq
519
- from ruamel.yaml.tokens import CommentToken
520
-
521
- parent, key = tree, name
522
- if "." in name:
523
- table, key = name.split(".", 1)
524
- parent = tree[table]
525
- was = parent.get(key)
526
-
527
- if isinstance(value, (list, dict)):
528
- new = (CommentedMap(value) if isinstance(value, dict)
529
- else CommentedSeq(value))
530
- anchors = getattr(getattr(was, "ca", None), "items", None)
531
- if anchors and len(new):
532
- old_keys = (list(was.keys()) if isinstance(was, dict)
533
- else list(range(len(was))))
534
- new_keys = (list(new.keys()) if isinstance(new, dict)
535
- else list(range(len(new))))
536
- if old_keys and old_keys[-1] in anchors:
537
- new.ca.items[new_keys[-1]] = anchors[old_keys[-1]]
538
- parent[key] = new
539
- return
540
-
541
- parent[key] = value
542
- if not isinstance(was, (list, dict)):
543
- return
544
- slot = getattr(getattr(parent, "ca", None), "items", {}).get(key)
545
- if slot and slot[3]:
546
- slot[2] = CommentToken("\n" + "".join(tok.value for tok in slot[3]),
547
- slot[3][0].start_mark)
548
- slot[3] = None
549
-
550
-
551
- def write(text: str, newline: str = "\n") -> None:
552
- """Replace `config.yaml` with `text`, atomically. Raises OSError.
553
-
554
- Temp file plus `os.replace`, which is `json_store.write_json_atomic`'s
555
- reasoning applied to the one file in this project that is not JSON: a
556
- truncate-then-write leaves the document empty for the length of the
557
- write and permanently damaged if the process dies inside it, and THIS
558
- document is the one without which nothing starts at all.
559
-
560
- Not that function itself, which serialises JSON and would have to grow
561
- a "or just write these bytes" mode to be shared.
562
- """
563
- path = config_schema.CONFIG_PATH
564
- # A UNIQUE NAME, not a fixed `config.yaml.tmp` sibling. Two writers --
565
- # a `/config` write and the launcher's merge in another process -- raced
566
- # on the one name, and a failed `os.replace` (a read-only file on
567
- # Windows, where opening the temp still succeeds) left the leftover in
568
- # the install tree forever. `_validate_candidate` below already does it
569
- # this way.
570
- handle_fd, tmp = tempfile.mkstemp(prefix="config.", suffix=".writing.yaml",
571
- dir=os.path.dirname(path))
572
- try:
573
- with open(handle_fd, "w", encoding="utf-8", newline="") as handle:
574
- handle.write(text.replace("\n", newline))
575
- os.replace(tmp, path)
576
- except BaseException:
577
- try:
578
- os.unlink(tmp)
579
- except OSError:
580
- pass # the temp file may not exist; the original error is what is raised
581
- raise
582
- # See `document()`: a one-value change can leave the size identical, so
583
- # the stamp alone would not always notice our own write.
584
- forget_document()
585
-
586
-
587
- # ---------------------------------------------------------------------------
588
- # ---- Describing a key -----------------------------------------------------
589
- # ---------------------------------------------------------------------------
590
-
591
- def shown(value: Any) -> str:
592
- """A value as `config.yaml` spells it, for a one-line description."""
593
- if value is None:
594
- return "null"
595
- if isinstance(value, bool):
596
- return "true" if value else "false"
597
- if isinstance(value, str):
598
- return value or '""'
599
- if isinstance(value, (list, tuple, frozenset)):
600
- return f"{len(value)} entries"
601
- if isinstance(value, dict):
602
- return f"{len(value)} entries"
603
- return str(value)
604
-
605
-
606
- def _bounds(metadata) -> dict:
607
- """`{'gt': 0}` and friends, out of pydantic's constraint objects.
608
-
609
- Read off the metadata rather than off the annotation alias, because the
610
- alias is erased by the time `model_fields` is built: `PositiveInt` and a
611
- hand-written `Annotated[int, Field(gt=0)]` are indistinguishable here,
612
- which is the right outcome -- the description follows the CONSTRAINT, so
613
- a new range shape needs no entry anywhere in this file.
614
- """
615
- out = {}
616
- for item in metadata:
617
- for attribute in ("gt", "ge", "lt", "le", "min_length"):
618
- value = getattr(item, attribute, None)
619
- if value is not None:
620
- out[attribute] = value
621
- return out
622
-
623
-
624
- def _number_phrase(noun: str, bounds: dict) -> str:
625
- if bounds.get("ge") == 0.0 and bounds.get("le") == 1.0:
626
- return f"{noun} from 0 to 1"
627
- if "ge" in bounds and "le" in bounds:
628
- # #213's `Port`, and any closed range after it.
629
- return f"{noun} from {bounds['ge']} to {bounds['le']}"
630
- if bounds.get("gt") == 0:
631
- return f"{noun}, above 0"
632
- if bounds.get("ge") == 0:
633
- return f"{noun}, 0 or more"
634
- return noun
635
-
636
-
637
- def describe(name: str, annotation, metadata) -> tuple:
638
- """`(kind, possible values, takes_text, nullable)` for one field.
639
-
640
- The phrasing is generated from the schema rather than written down per
641
- key, and that is the point: `config.yaml` already carries a comment
642
- saying what every value DOES, and a second hand-written copy of what it
643
- may BE is the copy that goes stale. One function for all of them.
644
-
645
- THE LAST TWO ARE FACTS, NOT PHRASING, and they are returned rather than
646
- re-derived because `parse_value` used to recover them by reading the
647
- PHRASING back -- `row.values.startswith("text")` and `"null" in
648
- row.values`. That made a display string load-bearing for parsing: the
649
- day a `Literal` gains an option whose first word is `text`, that field
650
- silently stops being parsed as YAML while the panel still offers it a
651
- closed vocabulary, with nothing raising. The annotation is right here.
652
- """
653
- origin = typing.get_origin(annotation)
654
- args = typing.get_args(annotation)
655
- bounds = _bounds(metadata)
656
-
657
- if origin is typing.Literal:
658
- return "scalar", " | ".join(str(a) for a in args), False, False
659
- if annotation is bool:
660
- return "scalar", "true | false", False, False
661
- if annotation is int:
662
- return "scalar", _number_phrase("whole number", bounds), False, False
663
- if annotation is float:
664
- return "scalar", _number_phrase("number", bounds), False, False
665
- if annotation is str:
666
- return ("scalar", "text, not empty" if bounds.get("min_length")
667
- else "text", True, False)
668
- if origin is typing.Union or origin is types.UnionType:
669
- inner = [a for a in args if a is not type(None)]
670
- if inner == [str]:
671
- return "scalar", "text, or null", True, True
672
- if inner and typing.get_origin(inner[0]) is dict:
673
- return "pair", "<name>, or <PROVIDER> <name>, or off", False, True
674
- return "container", "a list, or null", False, True
675
- if origin is dict:
676
- return "container", "a table", False, False
677
- return "container", "a list", False, False
678
-
679
-
680
- # ---------------------------------------------------------------------------
681
- # ---- The catalogue --------------------------------------------------------
682
- # ---------------------------------------------------------------------------
683
-
684
- def catalogue(remembered_pair: Optional[tuple[str, str]] = None) -> list[KeyRow]:
685
- """Every addressable name, in `config.yaml`'s own order.
686
-
687
- FILE ORDER, not alphabetical, and it is worth saying why: the schema
688
- declares its fields in the order the file writes them, under the same
689
- section banners, so browsing the panel walks the document. Alphabetical
690
- would interleave the sandbox with the scholar lookup and put
691
- `compaction_*` in front of the model the harness runs on.
692
-
693
- The two tables are expanded rather than listed, because a row that says
694
- `tool_permissions · 23 entries` is not something anyone can act on, and
695
- the 58 leaves are exactly the rows a person comes here for.
696
-
697
- BOTH VALUES COME FROM HERE: the file's, parsed through the cached
698
- document, and the session's, off the model bound at import. See
699
- `KeyRow` for why one of them was not enough. `remembered_pair` is the
700
- `/model` store's whole pair, or None; it is carried on the `model_name`
701
- row's `remembered` field and changes nothing else.
702
- """
703
- config = config_schema.current()
704
- tree = document()
705
- authority = config_schema.HARNESS_AUTHORITY_KEYS
706
- overrides = settings_overrides()
707
- environment = {key.lower(): variable
708
- for key, variable in config_schema.ENV_OVERRIDES.items()}
709
-
710
- rows = []
711
- for name, field in config_schema.HarnessConfig.model_fields.items():
712
- if name in TABLES:
713
- table = getattr(config, name)
714
- tools = list(type(table).model_fields)
715
- # THE TABLE ITSELF GETS A ROW, ahead of its leaves. Without one
716
- # `/config tool_permissions` answered "tool_permissions is not a
717
- # key in config.yaml" -- false three times over: it is a key, it
718
- # is a top-level block in the file, and it is one of the nine
719
- # AUTHORITY keys. A container row is what the other 17 containers
720
- # already get: explained and counted, with the leaves set
721
- # individually.
722
- rows.append(KeyRow(
723
- name=name,
724
- kind="container",
725
- values=f"{len(tools)} tools, each true | false",
726
- in_file=_in_file(tree, name),
727
- in_session=table,
728
- authority=True))
729
- for tool in tools:
730
- leaf = f"{name}.{tool}"
731
- rows.append(KeyRow(
732
- name=leaf,
733
- kind="scalar",
734
- values="true | false",
735
- in_file=_in_file(tree, leaf),
736
- in_session=getattr(table, tool),
737
- authority=True))
738
- continue
739
- kind, values, takes_text, nullable = describe(
740
- name, field.annotation, field.metadata)
741
- # EVERY SOURCE, not the first one found. An `if/elif` reported
742
- # `model_name` as outranked by `$AGENT_MODEL` and never mentioned
743
- # `settings.json default_model` -- the tier that arrives with a
744
- # directory you cloned, and the one a person most needs told about.
745
- variable = environment.get(name)
746
- settings_key = overrides.get(name)
747
- rows.append(KeyRow(
748
- name=name,
749
- kind=kind,
750
- values=values,
751
- # The raw document's own types for a container -- a list where
752
- # the model holds a frozenset or a tuple. Never compared for a
753
- # container, because `pending` is about the settable rows and a
754
- # container cannot be written from here.
755
- in_file=_in_file(tree, name),
756
- in_session=getattr(config, name),
757
- authority=name in authority,
758
- environment_variable=variable,
759
- settings_key=settings_key,
760
- takes_text=takes_text,
761
- nullable=nullable,
762
- remembered=(remembered_pair if name == "model_name" else None)))
763
- return rows
764
-
765
-
766
- def pending_changes() -> list:
767
- """The rows written this session and waiting on a restart.
768
-
769
- Settable rows only: a container's file value is a list where the model
770
- holds a frozenset or a tuple, so the two differ by construction and
771
- would report as pending forever. Nothing can write one from here in any
772
- case, so there is nothing for such a row to be pending about.
773
- """
774
- return [row for row in catalogue() if row.settable and row.pending]
775
-
776
-
777
- def find(name: str,
778
- remembered_pair: Optional[tuple[str, str]] = None) -> Optional[KeyRow]:
779
- """The row called `name`, or None. Exact match, never a prefix.
780
-
781
- CASE-INSENSITIVE, because every key in this file is lowercase and the
782
- names people arrive with are not: `config.py` publishes them as
783
- `MAX_TOKENS` and the documentation quotes both spellings. There is no
784
- ambiguity to protect -- two rows differing only in case cannot exist,
785
- since the schema's field names are the source of them. Prefix matching
786
- in `matching()` is folded the same way, so what the panel completes and
787
- what `find` resolves stay one rule.
788
- """
789
- wanted = name.lower()
790
- for row in catalogue(remembered_pair):
791
- if row.name.lower() == wanted:
792
- return row
793
- return None
794
-
795
-
796
- def matching(prefix: str,
797
- remembered_pair: Optional[tuple[str, str]] = None) -> list[KeyRow]:
798
- """Every row whose name starts with `prefix`, in catalogue order.
799
-
800
- Substring would be friendlier and is deliberately not done: the panel
801
- completes what it draws into the prompt, and a match in the MIDDLE of a
802
- name completes to something that does not contain what was typed, which
803
- reads as the harness ignoring the keystrokes.
804
-
805
- Case-folded, for `find`'s reason: typing `MAX_` should offer the same
806
- rows `max_` does, or the completion and the lookup disagree about what
807
- the user meant.
808
- """
809
- wanted = prefix.lower()
810
- return [row for row in catalogue(remembered_pair)
811
- if row.name.lower().startswith(wanted)]
812
-
813
-
814
- def file_value(name: str, tree=None) -> Any:
815
- """What `config.yaml` itself says for `name`. `KeyRow.in_file`'s source.
816
-
817
- Kept as its own function for the callers that want one name without
818
- building 166 rows to get it. `tree` is for a caller asking about many
819
- at once, and matters less than it did now that `document()` caches.
820
- """
821
- if tree is None:
822
- tree = document()
823
- return _in_file(tree, name)
824
-
825
-
826
- def explain(name: str, *,
827
- remembered: Optional[tuple[str, str]] = None,
828
- cli_pinned: bool = False,
829
- session_pair: Optional[tuple[str, str]] = None) -> list[str]:
830
- """The lines `/config <key>` writes. Plain facts, no styling.
831
-
832
- HERE RATHER THAN IN THE HANDLER, for AGENTS.md's §16 rule: the terminal
833
- is a shell, so what there is to SAY about a key is this module's, and
834
- drawing it is `tui/app.py`'s. It also means the sentences are testable
835
- without a terminal, which is where every one of them is checked.
836
-
837
- `remembered` is the `/model` store's whole pair, if one is stored;
838
- `cli_pinned` says a --provider/--model flag named this launch; and
839
- `session_pair` is the provider/model actually running. All three are
840
- read only for `model_name` -- the one key whose session value can come
841
- from somewhere `catalogue()` cannot see -- and default to saying
842
- nothing, so every existing caller keeps its current sentences.
843
- """
844
- row = find(name, remembered)
845
- if row is None:
846
- return [f"{name} is not a key in config.yaml."]
847
-
848
- lines = [f"{row.name}: {shown(row.in_file)}"]
849
- lines.append(f"Takes {row.values}.")
850
- if row.kind == "container":
851
- # The session's copy, not the document's: `todo_statuses` is a tuple
852
- # here and a list there, and the tuple is what the code sees.
853
- lines.extend(_entries(row.in_session))
854
-
855
- if row.pending:
856
- running = shown(row.in_session)
857
- if name == "model_name" and session_pair is not None:
858
- running = f"{session_pair[0]} | {session_pair[1]}"
859
- lines.append(
860
- f"Written this session. This one is still running "
861
- f"{running} and will pick the new value up at the "
862
- f"next launch.")
863
-
864
- if name == "model_name" and remembered is not None:
865
- provider, model = remembered
866
- if session_pair == remembered and not cli_pinned:
867
- lines.append(
868
- f"This session is running {provider} | {model}, remembered "
869
- f"with /model. A /config write here changes the harness "
870
- f"default, not the remembered choice: it still wins at the "
871
- f"next launch. Choose again with /model to move it.")
872
- else:
873
- lines.append(
874
- f"A remembered {provider} | {model} is stored, but this "
875
- f"session is not running it.")
876
- elif (name == "model_name" and cli_pinned
877
- and session_pair is not None):
878
- lines.append(
879
- f"This launch was pinned with --provider/--model, so this "
880
- f"session is running {session_pair[0]} | {session_pair[1]}.")
881
-
882
- if row.environment_variable:
883
- variable = row.environment_variable
884
- memory_wins = (
885
- name == "model_name" and remembered is not None
886
- and session_pair == remembered and not cli_pinned)
887
- if os.environ.get(variable) is not None:
888
- if memory_wins:
889
- lines.append(
890
- f"{variable} is set to {shown(row.in_session)}, but the "
891
- f"remembered pair above outranks it this session -- only "
892
- f"a --provider/--model flag outranks a remembered choice.")
893
- else:
894
- lines.append(
895
- f"{variable} is set to {shown(row.in_session)}, so that is "
896
- f"what this session is using and what the next launch will "
897
- f"use too. config.yaml says {shown(row.in_file)}, and a "
898
- f"write here changes that rather than what is in force.")
899
- else:
900
- lines.append(
901
- f"{variable} would override this if it were set.")
902
- elif row.outranked_by:
903
- lines.extend(_settings_tier_lines(row))
904
-
905
- # THE WORKSPACE PAIR (TECHNICAL_DEBT 28, batch 111). Two keys, one
906
- # question between them, and the person reading either is the person
907
- # about to assume the other. Said HERE rather than only in the launch
908
- # refusal, because a refusal arrives after the decision and this
909
- # arrives during it.
910
- if name in ("workspace_dir", "workspace_is_project"):
911
- lines.extend(_workspace_pair(name))
912
-
913
- if row.authority:
914
- key = authority_key(name)
915
- lines.append(f"AUTHORITY. This decides {AUTHORITY_EFFECT[key]}")
916
- lines.append(
917
- "No settings file, environment variable or tool call can reach "
918
- "it. Changing it here asks first.")
919
- if row.kind == "pair":
920
- role = "critic" if name == "critic_model" else "embedder"
921
- lines.append(
922
- f"/{role} sets this for the next run without a restart, and is "
923
- f"remembered per user; this sets the harness default.")
924
- if row.kind == "pair":
925
- lines.append(
926
- f"Set it with: /config {name} <PROVIDER> <name>, or "
927
- f"/config {name} off")
928
- elif row.settable:
929
- lines.append(f"Set it with: /config {name} <value>")
930
- else:
931
- lines.append(
932
- "Edit it in config.yaml. CONFIG_ARCHITECTURE.md says why it is "
933
- "what it is.")
934
- return lines
935
-
936
-
937
- def _settings_tier_lines(row) -> list[str]:
938
- """Whether a settings.json IS outranking this key, or merely could.
939
-
940
- TECHNICAL_DEBT 12, batch 111. This used to be one sentence -- "a
941
- project or user settings.json CAN win over whatever is written here"
942
- -- which is a static possibility stated in a process that knows the
943
- answer. `core/config_loader.settings_sources()` records which tier
944
- wrote each setting, so the live case can name the tier and the value
945
- and leave the reader with nothing to go and check.
946
-
947
- THE OLD SENTENCE IS KEPT for the case where nothing speaks, because
948
- there it is the whole truth and it is still worth saying: the reason
949
- this key can be overridden is not visible from the key.
950
-
951
- THE VALUE COMES FROM THE SETTINGS TIER, NOT FROM `row.in_session`, and
952
- that is a trap worth naming. For a compaction key `in_session` is
953
- `config.COMPACTION_*` -- what `config.yaml` said, bound at import --
954
- because the settings merge happens inside `effective_compaction` and
955
- never reaches the `config` module at all. So the two-values rule this
956
- module is built on has a third value here, and `in_session` is the
957
- wrong one of the three to quote in a sentence about what is winning.
958
- """
959
- from core import config_loader
960
-
961
- tier = config_loader.settings_sources().get(row.settings_key)
962
- if tier is None:
963
- return [f"A {row.outranked_by} key outranks this one, so a project "
964
- f"or user settings.json can win over whatever is written "
965
- f"here."]
966
-
967
- whose = {"project": "This project's", "user": "Your"}.get(
968
- tier, f"A {tier}")
969
- return [f"{whose} settings.json sets {row.settings_key} to "
970
- f"{shown(_settings_value(row.settings_key))}, so that is what "
971
- f"is in force and config.yaml's {shown(row.in_file)} is not. A "
972
- f"write here does not change it -- the settings file wins "
973
- f"again at the next launch."]
974
-
975
-
976
- def _settings_value(path: str) -> Any:
977
- """What the merged settings hold at a dotted *path*, one level deep.
978
-
979
- One level because `_NESTED_SETTINGS` is one level; a deeper path
980
- cannot exist, and inventing a general walker for it would be code
981
- written against a shape the validator refuses.
982
- """
983
- from core import config_loader
984
-
985
- settings = config_loader.get_settings()
986
- section, _, leaf = path.partition(".")
987
- if not leaf:
988
- return settings.get(section)
989
- return (settings.get(section) or {}).get(leaf)
990
-
991
-
992
- def _workspace_pair(name: str) -> list[str]:
993
- """What `explain` says about `workspace_dir` / `workspace_is_project`.
994
-
995
- TECHNICAL_DEBT 28. The two keys answer different questions -- where the
996
- file tools may write, and where the WORK is -- and for one release the
997
- second question had no key at all, so writing the first and expecting
998
- both was the obvious mistake to make. These sentences exist to make it
999
- the unobvious one.
1000
-
1001
- THE SESSION ANSWERS "is it", THE FILE ANSWERS "what is written", and
1002
- keeping those apart is this module's whole subject (batch 85). `/config
1003
- workspace_is_project true` writes the file and leaves the running
1004
- process exactly where it was until a restart, so a line that read the
1005
- file would tell someone their project had already moved when it had
1006
- not -- in a sentence added to the file that states the rule.
1007
-
1008
- The session's answer is `derived_values(current())` rather than
1009
- `config.WORKSPACE_DIR_EXPLICIT`, because this module imports no
1010
- first-party name but `config_schema` and that function IS the
1011
- definition of the value; asking it is how these lines cannot drift
1012
- from what `main()` will do.
1013
- """
1014
- row = find("workspace_is_project")
1015
- in_file = bool(row and row.in_file)
1016
- session = config_schema.current()
1017
- now = bool(config_schema.derived_values(session)["WORKSPACE_DIR_EXPLICIT"])
1018
- variable = os.environ.get("AGENT_WORKSPACE") is not None
1019
-
1020
- if name == "workspace_dir":
1021
- lines = [
1022
- "This is the file tools' root. Whether it is also the PROJECT "
1023
- "-- what workspace trust asks about, which .venastine/ is read, "
1024
- "where /init writes, what memories belong to -- is the separate "
1025
- "question workspace_is_project answers."]
1026
- if now:
1027
- named = ("$AGENT_WORKSPACE" if variable
1028
- else "workspace_is_project")
1029
- lines.append(
1030
- f"It IS the project in this session, because {named} says "
1031
- f"so, so moving this path moves the work with it.")
1032
- else:
1033
- lines.append(
1034
- "It is NOT the project in this session: nothing named it, "
1035
- "so the project is the directory you launched from. Set "
1036
- "workspace_is_project true to change that.")
1037
- if in_file is not bool(session.workspace_is_project):
1038
- lines.append(
1039
- f"config.yaml now says workspace_is_project: "
1040
- f"{shown(in_file)}, which this session has not picked up. "
1041
- f"The next launch will.")
1042
- return lines
1043
-
1044
- lines = [
1045
- "True means the workspace above is also the project: workspace "
1046
- "trust, the .venastine/ tier, /init's destination and "
1047
- "project-scoped memories all move to it. Naming AGENT_WORKSPACE "
1048
- "does the same thing; this is the way to say it in the file."]
1049
- if variable:
1050
- lines.append(
1051
- "$AGENT_WORKSPACE is set, so the workspace is already the "
1052
- "project this session whatever this key says. The two are OR'd "
1053
- "-- there is no precedence between them to get wrong.")
1054
- return lines
1055
-
1056
-
1057
- def _entries(value: Any, cap: int = 12) -> list[str]:
1058
- """A container's contents, capped, one per line.
1059
-
1060
- CAPPED because `domain_authority_suffixes` has 105 entries and the
1061
- transcript is a conversation, not a pager. The cap says how many are
1062
- not shown rather than trailing off, for the same reason the suggestion
1063
- panel's title counts what it did not draw.
1064
- """
1065
- if isinstance(value, dict):
1066
- items = [f" {key}: {shown(item)}" for key, item in value.items()]
1067
- elif isinstance(value, (list, tuple, frozenset)):
1068
- items = [f" {shown(item)}" for item in sorted(value, key=str)]
1069
- else:
1070
- return []
1071
- if len(items) <= cap:
1072
- return items
1073
- return items[:cap] + [f" … and {len(items) - cap} more, in config.yaml"]
1074
-
1075
-
1076
- def authority_key(name: str) -> Optional[str]:
1077
- """The authority key `name` belongs to, or None.
1078
-
1079
- A leaf answers with its TABLE: `tool_permissions.shell` is gated because
1080
- `tool_permissions` is, and the sentence the confirmation shows is the
1081
- table's.
1082
- """
1083
- root = name.split(".", 1)[0]
1084
- return root if root in config_schema.HARNESS_AUTHORITY_KEYS else None
1085
-
1086
-
1087
- # ---------------------------------------------------------------------------
1088
- # ---- Proposing a change ---------------------------------------------------
1089
- # ---------------------------------------------------------------------------
1090
-
1091
- #: The words that mean "no value" wherever `/config` takes one.
1092
- #:
1093
- #: PUBLIC, and `auto` is in it, because `tui/app._config_set` carried its own
1094
- #: copy with `auto` and this one without -- so `/config critic_model auto`
1095
- #: cleared the key while `/config default_effort auto` wrote the literal
1096
- #: string and was refused by the schema. One word, two behaviours, decided by
1097
- #: which branch a key happened to take. The value grammar lives here by this
1098
- #: module's own rule; the terminal reads it.
1099
- NULL_WORDS = ("null", "none", "off", "clear", "auto")
1100
-
1101
-
1102
- def _unquoted(text: str) -> str:
1103
- """`"x"` and `'x'` mean x, for the fields that take their text verbatim.
1104
-
1105
- The only way to type an EMPTY string, which is what one shipped value
1106
- is: `scholar_mailto` is `''` in the file, and without this there is no
1107
- way to put it back. Typing `""` would set the two-character string
1108
- `""` -- silently, so the key meant to carry an email address would
1109
- carry a pair of quotes and OpenAlex would be sent them.
1110
-
1111
- It also covers quoting out of habit, which the verbatim rule would
1112
- otherwise take at its word.
1113
- """
1114
- if len(text) >= 2 and text[0] == text[-1] and text[0] in "\"'":
1115
- return text[1:-1]
1116
- return text
1117
-
1118
-
1119
- def parse_value(row: KeyRow, text: str) -> Any:
1120
- """Typed text, as the value the schema will be handed.
1121
-
1122
- THE STRING FIELDS TAKE THEIR TEXT VERBATIM, and that exception is the
1123
- whole reason this is not one `yaml.load` call. `sandbox_docker_image` is
1124
- `docker.io/library/python:3.13-slim`, `scholar_api_url` is a URL and
1125
- `db_path` is a path:
1126
- handing those to a YAML parser asks it to guess, and the day a value
1127
- contains `: ` it would guess "mapping" and the error would talk about a
1128
- dict the user never typed.
1129
-
1130
- Everything else IS parsed as YAML, so `true`, `0.4`, `18000` and `null`
1131
- mean in the prompt exactly what they mean in the file -- and a value of
1132
- the wrong shape is refused by the schema a moment later, naming the key,
1133
- rather than by a second type system invented here.
1134
- """
1135
- text = text.strip()
1136
- if not text:
1137
- raise ValueError(f"{row.name} needs a value. It takes {row.values}.")
1138
- if row.takes_text:
1139
- if row.nullable and text.lower() in NULL_WORDS:
1140
- return None
1141
- return _unquoted(text)
1142
- if row.nullable and text.lower() in NULL_WORDS:
1143
- return None
1144
- try:
1145
- return YAML(typ="safe").load(io.StringIO(text))
1146
- except Exception:
1147
- # Unparseable as YAML is still a legal thing to have typed; let the
1148
- # schema be the one that says what was wrong with it.
1149
- return text
1150
-
1151
-
1152
- def _validate_candidate(candidate: str, name: str, value: Any) -> None:
1153
- """Run `candidate` past the loader as a FILE. Raises ValueError.
1154
-
1155
- THROUGH THE SEAM, not through a reader assembled here.
1156
- `config_schema.load(path=...)` was built in batch 83 for exactly this
1157
- caller: it validates a candidate on its own terms, with no environment
1158
- overlay and without touching the live cache, because the file is what
1159
- the next launch reads and the environment it will read it under is not
1160
- knowable now. A candidate missing `db_path` is refused here even in a
1161
- shell where `APP_DB_PATH` happens to be set, which is the property that
1162
- makes "this file will start" mean something.
1163
-
1164
- The temp file sits beside `config.yaml` rather than in the system temp
1165
- directory, so it lands on the same filesystem as the write that may
1166
- follow and cannot be redirected somewhere unwritable by an environment
1167
- variable.
1168
-
1169
- The message is re-led rather than passed through: the loader names the
1170
- file it was handed, and "config.a7f3.proposed.yaml is not valid" tells
1171
- a person nothing. Everything after that first line -- the key, the
1172
- problem, one line per fault -- is the loader's and is kept verbatim.
1173
- """
1174
- directory = os.path.dirname(config_schema.CONFIG_PATH)
1175
- try:
1176
- handle, path = tempfile.mkstemp(prefix="config.",
1177
- suffix=".proposed.yaml", dir=directory)
1178
- except OSError:
1179
- # A GLOBAL npm PREFIX OWNED BY ROOT is an ordinary install, and the
1180
- # directory above is not writable there. Without this the first
1181
- # `/config` write of such a session raised PermissionError out of the
1182
- # command handler and took the app down -- before anything could tell
1183
- # the user the far more useful fact that the file cannot be written.
1184
- # The same fallback `config_update._validates` carries.
1185
- handle, path = tempfile.mkstemp(prefix="config.",
1186
- suffix=".proposed.yaml")
1187
- try:
1188
- with open(handle, "w", encoding="utf-8", newline="") as stream:
1189
- stream.write(candidate)
1190
- try:
1191
- config_schema.load(path=path)
1192
- except ValueError as exc:
1193
- detail = str(exc)
1194
- _, _, rest = detail.partition("):\n")
1195
- raise ValueError(
1196
- f"{name} = {shown(value)} was refused:\n"
1197
- + (rest or detail)) from None
1198
- finally:
1199
- try:
1200
- os.unlink(path)
1201
- except OSError:
1202
- # A leftover temp file is untidy, not a failure to report over
1203
- # the outcome of the validation the caller asked for.
1204
- pass
1205
-
1206
-
1207
- def _changed_lines(before: str, after: str) -> list:
1208
- """`(line number, old, new)` for what actually moved between two texts.
1209
-
1210
- ALIGNED, not zipped. `zip(old, new)` assumes the documents stay the same
1211
- length: setting `critic_model` from `null` to a provider pair grows the
1212
- file by two lines, and every line after the edit then pairs against its
1213
- neighbour -- measured at 707 of 847 lines reported as changed for a
1214
- one-line edit. It also stopped at the shorter document, so a change that
1215
- only removes lines under-reported.
1216
-
1217
- Line numbers are the NEW document's, because what the caller shows is
1218
- the file as it will be.
1219
- """
1220
- import difflib
1221
-
1222
- old, new = before.split("\n"), after.split("\n")
1223
- changed = []
1224
- matcher = difflib.SequenceMatcher(None, old, new, autojunk=False)
1225
- for tag, i1, i2, j1, j2 in matcher.get_opcodes():
1226
- if tag == "equal":
1227
- continue
1228
- for offset in range(max(i2 - i1, j2 - j1)):
1229
- a = old[i1 + offset] if i1 + offset < i2 else ""
1230
- b = new[j1 + offset] if j1 + offset < j2 else ""
1231
- changed.append((j1 + offset + 1, a, b))
1232
- return changed
1233
-
1234
-
1235
- @dataclasses.dataclass(frozen=True)
1236
- class Proposal:
1237
- """A validated change that has not been written yet."""
1238
-
1239
- name: str
1240
- before: Any
1241
- after: Any
1242
- text: str # the whole document, as it would be written
1243
- newline: str
1244
- lines: list # the changed lines, `(number, old, new)`
1245
-
1246
-
1247
- def propose(name: str, value: Any) -> Proposal:
1248
- """Validate `name = value` against the whole document. Raises ValueError.
1249
-
1250
- THE WHOLE DOCUMENT, not the one field, and that is what makes this worth
1251
- routing through the file at all: `config_schema` carries cross-field
1252
- invariants that a per-field check cannot see -- a compaction strategy has
1253
- to appear in the roster beside it, a similarity band's floor has to be
1254
- under its ceiling, every domain suffix has to name a class that exists.
1255
- Setting one key can break one of those, and the failure belongs here,
1256
- before the write, rather than at the next launch.
1257
- """
1258
- row = find(name)
1259
- if row is None:
1260
- raise ValueError(f"{name} is not a key in config.yaml.")
1261
- if not row.settable:
1262
- raise ValueError(
1263
- f"{name} holds {shown(row.in_session)} and is edited in "
1264
- f"config.yaml directly, not from here.")
1265
-
1266
- text, newline = read_text()
1267
- tree = _round_trip().load(io.StringIO(text))
1268
- place(tree, name, value)
1269
- candidate = _dump(tree)
1270
- _validate_candidate(candidate, name, value)
1271
-
1272
- changed = _changed_lines(text, candidate)
1273
- # `in_file`, not `in_session`: "was" is about the value this write is
1274
- # REPLACING, which is the document's. The two are the same until the
1275
- # first write of a session, which is why taking the wrong one read as
1276
- # correct for as long as nobody changed two values in one sitting.
1277
- return Proposal(name=name, before=row.in_file, after=value,
1278
- text=candidate, newline=newline, lines=changed)
1279
-
1280
-
1281
- # ---------------------------------------------------------------------------
1282
- # ---- Asking for a restart -------------------------------------------------
1283
- # ---------------------------------------------------------------------------
1284
-
1285
- @dataclasses.dataclass(frozen=True)
1286
- class RestartRequest:
1287
- """"Relaunch this harness so a written change takes effect."
1288
-
1289
- Lives here rather than in `tui/` or `main.py` because both ends need
1290
- it: the TUI exits with one, `main.py` acts on one, and a record they
1291
- both import from a leaf module is cheaper than an edge between them.
1292
-
1293
- It carries FACTS, not arguments. Which flags express "this thread, this
1294
- model" is `main.py`'s question, and it is the module that owns the
1295
- parser those flags belong to.
1296
- """
1297
-
1298
- key: str
1299
- thread_id: Optional[str] = None
1300
- provider: Optional[str] = None
1301
- model: Optional[str] = None
1
+ """config_edit.py -- the catalogue behind `/config`, and the writer under it.
2
+
3
+ WHY THIS IS NOT IN `tui/`. AGENTS.md's rule for §16 is that the TUI is a
4
+ SHELL rather than a feature home: anything implemented there is invisible to
5
+ the CLI and to the research pipeline, which is why the question tool, the
6
+ todo list, `/init` and session summaries are all specified outside it. The
7
+ catalogue, the value grammar and the writer are the feature; `/config` is one
8
+ surface over them, and a command-line surface can be added later without
9
+ moving a line.
10
+
11
+ WHY IT IS NOT IN `config_schema.py` EITHER. That module is the READER, and it
12
+ carries a stated rule that it imports nothing first-party -- `config.py` and
13
+ `core/config_loader.py` both sit on top of it, and an edge from there into
14
+ `core/` puts the cycle back by a longer route. This module needs that edge:
15
+ answering "what outranks this key" means reading `core/config_loader`'s
16
+ settings tables. Nothing imports this module except `tui/` and `main.py`, so
17
+ the cycle cannot form from this end either.
18
+
19
+ FOUR RULES, all of them load-bearing.
20
+
21
+ 1. A PROPOSED CHANGE IS VALIDATED AS THE BYTES IT WILL BECOME. `propose()`
22
+ applies the edit to a round-trip tree, dumps it to text, re-parses THAT
23
+ TEXT with `config_schema`'s own safe reader, and validates the result. Not
24
+ the in-memory tree: the round-trip parser hands back its own scalar types,
25
+ and what the next launch reads is bytes. Validating anything else would be
26
+ certifying a document nobody will ever load.
27
+
28
+ 2. THE WRITE PRESERVES EVERYTHING IT DID NOT CHANGE. `config.yaml` is 845
29
+ lines, of which roughly 600 are the comments that say what each value does
30
+ and which keys are AUTHORITY. A dump through `typ="safe"` would erase all
31
+ of them, so the round-trip parser is configured here to reproduce this
32
+ file exactly -- measured, byte for byte -- and a one-value change comes
33
+ out as a one-line diff.
34
+
35
+ 3. NOTHING HERE APPLIES A CHANGE TO A RUNNING PROCESS. `config.py` binds at
36
+ import and `security/posture.py` depends on that (UN1); `tools/builtin/
37
+ shell.py` validates the approval mode at ITS import. A reload would leave
38
+ the frozen posture disagreeing with the file it came from. So the writer
39
+ writes, and `RestartRequest` is how the change reaches a process that will
40
+ read it.
41
+
42
+ 4. THE AUTHORITY KEYS ARE MARKED, NOT BLOCKED (batch 84). `config_schema.
43
+ HARNESS_AUTHORITY_KEYS` used to mean "no in-session surface may write
44
+ this". It now means "no UNATTENDED surface may": a settings file still
45
+ cannot reach these keys, nor an environment variable, nor a tool call.
46
+ A person typing at the prompt can, behind a confirmation that names what
47
+ the key permits.
48
+
49
+ STATE THE FILE-TOOL HALF ACCURATELY -- this said "the file tools refuse
50
+ the harness install tree" for three batches and they do not. Measured:
51
+ `file_ops._protected_path_error` denies a path carrying a `.venastine`
52
+ SEGMENT and nothing else, so `<install>/config.yaml` comes back allowed.
53
+ What actually holds is weaker and still real: `write` and `edit` ship
54
+ DENIED in `tool_permissions` and cannot be enabled at runtime, and
55
+ `security/protected_paths` makes a workspace overlapping the harness tree
56
+ a startup error -- so the install tree is never inside the workspace and
57
+ a write there is approval-gated rather than auto-approved. That module's
58
+ own docstring is why the wording matters: a half-understood control is
59
+ worse than none.
60
+ `AUTHORITY_EFFECT` below is that sentence, per key, and it is the reason
61
+ the gate is not a generic "are you sure".
62
+ """
63
+
64
+ from __future__ import annotations
65
+
66
+ import dataclasses
67
+ import io
68
+ import os
69
+ import tempfile
70
+ import types
71
+ import typing
72
+ from typing import Any, Optional
73
+
74
+ from ruamel.yaml import YAML
75
+ from ruamel.yaml.error import YAMLError
76
+
77
+ import config_schema
78
+
79
+ # The two nested tables, whose leaves are addressed `<table>.<tool>`. Named
80
+ # once: the catalogue skips them as rows of their own and expands them
81
+ # instead, and every other reference derives from this.
82
+ TABLES = ("tool_permissions", "tool_approvals")
83
+
84
+ #: What each authority key actually permits, in one sentence, for the
85
+ #: confirmation that gates it. NOT a generic "are you sure" -- the whole
86
+ #: argument for letting a slash command write these is that the person is
87
+ #: told what they are turning on, so a missing entry here is a missing gate.
88
+ #: `tests/test_config_edit.py` holds this against HARNESS_AUTHORITY_KEYS.
89
+ AUTHORITY_EFFECT = {
90
+ "shell_approval_mode": (
91
+ "how often a shell command stops to ask you. `contained` runs any "
92
+ "code the agent writes inside the container without asking, and "
93
+ "`never` runs every command the agent writes without asking, "
94
+ "including in a session where untrusted content is already in the "
95
+ "context window."),
96
+ "allow_insecure_sandbox_fallback": (
97
+ "whether a shell command may run WITHOUT the container when neither "
98
+ "Docker nor Podman can run one -- on the host, with your files."),
99
+ "auto_approve_sandbox_fallback": (
100
+ "whether that fallback to the host happens without asking you "
101
+ "first."),
102
+ "allow_wsl_backend": (
103
+ "whether the agent may ask for a command to run in WSL instead "
104
+ "of the container. WSL is not a sandbox: it reaches this "
105
+ "harness's own config and authority files, has no memory or "
106
+ "process limits, and can start Windows programs with your full "
107
+ "authority."),
108
+ "allow_ssh_backend": (
109
+ "whether the agent may ask for a command to run on the remote "
110
+ "host you configured, instead of the container. That is another "
111
+ "machine this harness cannot inspect: no isolation, no memory or "
112
+ "process limits, and it uses credentials you issued. Nothing "
113
+ "runs there without asking you first."),
114
+ "redact_tool_outputs": (
115
+ "whether secrets are stripped from tool output before it reaches "
116
+ "the model and the transcript."),
117
+ "ensemble_models": (
118
+ "which providers N research passes are sent to. Every entry is a "
119
+ "provider that receives your research content."),
120
+ "critic_model": (
121
+ "which provider the grounding and critic passes are sent to. It "
122
+ "receives the claims and the sources."),
123
+ "embedder_model": (
124
+ "which provider claim and source text is sent to for similarity "
125
+ "scoring."),
126
+ "tool_permissions": (
127
+ "whether a tool may be called at all. This is the global floor -- "
128
+ "no agent, skill or approval can widen it (D14)."),
129
+ "tool_approvals": (
130
+ "whether a tool stops to ask you before it runs. Turning one off "
131
+ "removes a prompt you would otherwise see."),
132
+ }
133
+
134
+ #: config.yaml key -> the settings.json path that outranks it. Declared here
135
+ #: rather than derived, because only one of the three sources IS a table:
136
+ #: `_COMPACTION_DEFAULTS` maps settings key to field name and is inverted
137
+ #: below, while the confidence and source-scoring defaults are hand-written
138
+ #: return dicts and the top-level three are resolved in `main.py`. A test
139
+ #: holds every name here against the schema and against the loader's known
140
+ #: keys, so an added settings key that silently stops matching shows up as a
141
+ #: failure rather than as a `/config` that quietly reports the wrong winner.
142
+ _SETTINGS_OVERRIDES = {
143
+ "model_name": "default_model",
144
+ "default_effort": "effort",
145
+ "ensemble_mode": "ensemble_mode",
146
+ "authority_adjustment_cap": "source_scoring.authority_adjustment_cap",
147
+ "scholar_venue_weight": "source_scoring.venue_weight",
148
+ "scholar_citation_weight": "source_scoring.citation_weight",
149
+ "scholar_author_weight": "source_scoring.author_weight",
150
+ "scholar_h_saturation": "source_scoring.h_saturation",
151
+ "scholar_min_cohort_size": "source_scoring.min_cohort_size",
152
+ "scholar_min_citation_age_days": "source_scoring.min_citation_age_days",
153
+ # main.py:resolve_review states the precedence in so many words --
154
+ # `research.subagent_review > config.SUBAGENT_REVIEW` -- and this table
155
+ # was missing it, so `/config subagent_review` reported nothing
156
+ # outranking a key a settings file silently wins.
157
+ "subagent_review": "research.subagent_review",
158
+ }
159
+
160
+
161
+ def settings_overrides() -> dict:
162
+ """`{config.yaml key: settings.json path}`, compaction included.
163
+
164
+ The seven compaction keys come from `core/config_loader`'s own table
165
+ rather than being retyped, which is the same anti-drift move that table
166
+ was created for: it maps settings key to schema field, so inverting it
167
+ is the whole mapping with no second copy to go stale.
168
+ """
169
+ from core.config_loader import _COMPACTION_DEFAULTS
170
+
171
+ merged = dict(_SETTINGS_OVERRIDES)
172
+ for key, field in _COMPACTION_DEFAULTS.items():
173
+ merged[field] = f"compaction.{key}"
174
+ return merged
175
+
176
+
177
+ @dataclasses.dataclass(frozen=True)
178
+ class KeyRow:
179
+ """One addressable name in `config.yaml`, as `/config` shows it.
180
+
181
+ `name` is what the user types: a top-level key, or `<table>.<tool>` for
182
+ the 45 leaves of the two permission tables. All 23 tool names appear in
183
+ `tool_permissions`; all but `shell` appear in `tool_approvals`, whose
184
+ approval is governed solely by `shell_approval_mode` -- so the prefix
185
+ is not decoration, it is the only thing that tells
186
+ `tool_permissions.shell` from `tool_approvals.read`.
187
+
188
+ TWO VALUES, NOT ONE, and keeping them apart is batch 85's whole subject.
189
+ `in_file` is what `config.yaml` says: the thing `/config` edits and the
190
+ thing the next launch will read. `in_session` is what THIS process is
191
+ running, bound at import and never re-read. They start equal for every
192
+ key without an environment variable, and a write here moves the first
193
+ without moving the second.
194
+
195
+ One field for both was the defect. `/config` reported the SESSION's
196
+ value everywhere -- the panel's `now`, the `(was ...)` on a write, the
197
+ authority modal -- while writing against the FILE, so a second change to
198
+ the same key in one session reported the value it had at launch as the
199
+ one being replaced. The file was always right; only the reporting drifted,
200
+ and only once someone did what `/config` is for.
201
+ """
202
+
203
+ name: str
204
+ kind: str # "scalar" | "pair" | "container"
205
+ values: str # the possible values, as a person reads them
206
+ in_file: Any # what config.yaml says right now
207
+ in_session: Any # what this process is running
208
+ authority: bool
209
+ #: The remembered `/model` pair, if the preference store holds one.
210
+ #:
211
+ #: A STORE FACT, not a session claim: it says what the user last chose,
212
+ #: which the session runs only when no flag pinned the launch and the
213
+ #: staleness key still matches -- facts `explain()` (which is told
214
+ #: whether they hold) turns into the authoritative sentence. Set on the
215
+ #: `model_name` row only; every other row carries None. Display-only:
216
+ #: `pending` and every write path ignore it.
217
+ remembered: Optional[tuple[str, str]] = None
218
+ #: The environment variable that beats this key, `$`-prefixed, if any.
219
+ #: STRUCTURED rather than folded into one display string: `pending` and
220
+ #: `explain` both have to READ the variable's name, and a key can be
221
+ #: outranked by a variable AND a settings.json key at once -- `model_name`
222
+ #: is. One field for both meant whichever was found first was the only
223
+ #: one ever reported, and the one that lost was `settings.json
224
+ #: default_model`: the tier that arrives with a directory you cloned.
225
+ environment_variable: Optional[str] = None
226
+ #: The `settings.json` path that beats this key, if any.
227
+ settings_key: Optional[str] = None
228
+ #: True when the field is a string, so typed text is taken VERBATIM
229
+ #: rather than parsed as YAML. Read off the annotation by `describe`,
230
+ #: not recovered from `values` -- see that function.
231
+ takes_text: bool = False
232
+ #: True when the field accepts None, so a word in `NULL_WORDS` clears it.
233
+ nullable: bool = False
234
+
235
+ @property
236
+ def outranked_by(self) -> Optional[str]:
237
+ """Every source that beats this key, for display. None if none do."""
238
+ sources = []
239
+ if self.environment_variable:
240
+ sources.append(f"${self.environment_variable}")
241
+ if self.settings_key:
242
+ sources.append(f"settings.json {self.settings_key}")
243
+ return " and ".join(sources) if sources else None
244
+
245
+ @property
246
+ def settable(self) -> bool:
247
+ return self.kind in ("scalar", "pair")
248
+
249
+ @property
250
+ def pending(self) -> bool:
251
+ """Written, and waiting for a restart to take effect.
252
+
253
+ NOT simply "the two differ". For the five keys with an environment
254
+ variable the two differ from launch with nothing pending at all --
255
+ the variable won when the file was read and will win again next
256
+ time -- so a difference there says nothing about whether anyone
257
+ changed anything. `outranked_by` already names the variable; this
258
+ asks whether it is actually set.
259
+
260
+ Every other key had the two equal at launch by construction, so a
261
+ difference IS a change made since. That is why no snapshot of the
262
+ file is taken at startup: there is nothing a snapshot would know
263
+ that this does not.
264
+
265
+ A CONTAINER IS NEVER PENDING. The document hands back the list or
266
+ dict YAML spells where the model holds the frozenset or tuple its
267
+ consumers rely on, so the two differ for every one of the sixteen,
268
+ always -- and nothing can write one from here anyway, so there is
269
+ nothing for such a row to be pending about. Without this line every
270
+ container row read `pending restart` from launch.
271
+ """
272
+ if not self.settable:
273
+ return False
274
+ if self.in_file == self.in_session:
275
+ return False
276
+ if self.environment_variable:
277
+ return os.environ.get(self.environment_variable) is None
278
+ return True
279
+
280
+ @property
281
+ def summary(self) -> str:
282
+ """The one-line description the suggestion panel draws.
283
+
284
+ Values first, current second: the panel gives an entry two rendered
285
+ rows and DROPS the rest, so the order is what survives a narrow
286
+ terminal. What someone browsing needs is what they are allowed to
287
+ type; the value in the file is the useful second half.
288
+
289
+ THE FILE'S VALUE, because this panel is an editor and the file is
290
+ what it edits. `pending` is how the running process gets its say in
291
+ the one word that fits; the sentence naming what is still in force
292
+ belongs in `explain()`, which has a whole transcript to write into
293
+ instead of half a row. The last two parts are terse for the same
294
+ reason.
295
+ """
296
+ parts = [self.values, f"now {shown(self.in_file)}"]
297
+ if self.remembered is not None:
298
+ provider, model = self.remembered
299
+ parts.append(f"remembered {provider} | {model}")
300
+ if self.pending:
301
+ parts.append("pending restart")
302
+ if self.outranked_by:
303
+ parts.append(self.outranked_by)
304
+ if self.authority:
305
+ parts.append("authority")
306
+ return " · ".join(parts)
307
+
308
+
309
+ # ---------------------------------------------------------------------------
310
+ # ---- Reading and writing the document -------------------------------------
311
+ # ---------------------------------------------------------------------------
312
+
313
+ def _round_trip() -> YAML:
314
+ """The comment-preserving parser, configured to reproduce THIS file.
315
+
316
+ Every setting here was measured against `config.yaml` rather than
317
+ chosen: with the four below, a load-then-dump reproduces all 28,177
318
+ bytes exactly, and without any one of them it does not.
319
+
320
+ * `preserve_quotes` -- a quoted scalar stays quoted.
321
+ * `indent(sequence=4, offset=2)` -- ruamel's default un-indents a
322
+ list under its key, which moved every entry of the six list-valued
323
+ keys two columns left.
324
+ * the `null` representer -- ruamel writes a None as an EMPTY value,
325
+ so `ensemble_models: null` became `ensemble_models:` and four other
326
+ keys with it. Empty parses back to None, so this is cosmetic, but a
327
+ write that silently reformats five lines it was not asked to touch
328
+ is a write nobody can review.
329
+ * `width` -- the default wraps long scalars at 80 columns, which
330
+ would reflow the URL and the docker image tag.
331
+
332
+ `typ="safe"` stays the READ path in `config_schema`, deliberately: that
333
+ is the one that runs at every startup, and safe mode refuses
334
+ `!!python/...` tags outright. This parser exists for the write path
335
+ only, which is what `config_schema._reader` says it is for.
336
+ """
337
+ yaml = YAML(typ="rt")
338
+ yaml.preserve_quotes = True
339
+ yaml.width = 4096
340
+ yaml.indent(mapping=2, sequence=4, offset=2)
341
+ yaml.representer.add_representer(
342
+ type(None),
343
+ lambda representer, data: representer.represent_scalar(
344
+ "tag:yaml.org,2002:null", "null"))
345
+ return yaml
346
+
347
+
348
+ def read_text() -> tuple[str, str]:
349
+ """`(text, newline)` for the live document.
350
+
351
+ The newline is carried out and back rather than normalised away. This
352
+ repo is developed on Windows with `core.autocrlf=true`, so a worktree
353
+ copy of a tracked file can be CRLF even though the index is LF and this
354
+ particular file is LF today. ruamel emits `\\n` whatever it read, so a
355
+ write that did not put the convention back would rewrite all 845 lines
356
+ of a CRLF checkout to report a one-line change.
357
+ """
358
+ with open(config_schema.CONFIG_PATH, encoding="utf-8",
359
+ newline="") as handle:
360
+ raw = handle.read()
361
+ newline = "\r\n" if "\r\n" in raw else "\n"
362
+ return raw.replace("\r\n", "\n"), newline
363
+
364
+
365
+ #: `((path, mtime_ns, size), tree)` for the last document parsed, or None.
366
+ _document_cache = None
367
+
368
+
369
+ def document(fresh: bool = False):
370
+ """The live `config.yaml` as a round-trip tree, comments attached.
371
+
372
+ CACHED ON THE FILE'S OWN STAMP, because `catalogue()` reads this on
373
+ every keystroke the suggestion panel sees and parsing 845 lines costs
374
+ about 70ms against the 0.7ms everything else in that path costs. A
375
+ `stat` is microseconds, and the document changes about as often as a
376
+ person types a `/config` command.
377
+
378
+ `write()` clears the cache outright rather than trusting the stamp, and
379
+ that is not belt-and-braces: `max_tokens: 16000` and `max_tokens: 18000`
380
+ are the SAME SIZE, so mtime would be carrying the whole comparison, and
381
+ two writes inside one filesystem timestamp tick would be invisible. The
382
+ stamp stays for the case `write()` cannot see -- someone editing the
383
+ file in another window while the harness is up.
384
+
385
+ `fresh=True` skips it entirely, for a caller that is about to write.
386
+ """
387
+ global _document_cache
388
+ path = config_schema.CONFIG_PATH
389
+ stamp = None
390
+ if not fresh:
391
+ try:
392
+ status = os.stat(path)
393
+ stamp = (path, status.st_mtime_ns, status.st_size)
394
+ except OSError:
395
+ # Unreadable is `read_text`'s error to raise, with its message.
396
+ stamp = None
397
+ if stamp is not None and _document_cache is not None:
398
+ cached_stamp, tree = _document_cache
399
+ if cached_stamp == stamp:
400
+ return tree
401
+
402
+ text, _ = read_text()
403
+ try:
404
+ tree = _round_trip().load(io.StringIO(text))
405
+ except YAMLError as exc:
406
+ # TRANSLATED, NOT PROPAGATED, and `config_schema.read_document`
407
+ # already chose this shape for the same question one module over.
408
+ # Every reader in this file is reached from a slash command or a
409
+ # keystroke, and a ruamel error derives from `Exception` and
410
+ # nothing narrower -- so the shell either catches everything or
411
+ # catches this. It should catch this.
412
+ #
413
+ # THE DIAGNOSIS IS SOUND RATHER THAN A GUESS: `config.py` reads
414
+ # and validates this file at import, so the process could not
415
+ # have started if it did not parse. If it does not parse now, it
416
+ # has been edited since -- which is the workflow `explain()`
417
+ # recommends in so many words.
418
+ raise ValueError(
419
+ f"{config_schema.CONFIG_PATH} can no longer be parsed "
420
+ f"({exc}). It parsed when this session started, so it has "
421
+ f"been edited since and the edit left it structurally "
422
+ f"broken. Fix the file; the running session is unaffected "
423
+ f"until you relaunch.") from exc
424
+ if stamp is not None:
425
+ # RE-STAT AFTER THE READ. The stamp above was taken BEFORE it, so an
426
+ # external save landing between the two stored the new tree under
427
+ # the old file's stamp -- and the next keystroke's stat then matched
428
+ # it and served a parse of a file that no longer existed in that
429
+ # form. Cheap to close, and a cache that can be one save stale is
430
+ # worse than one that simply misses.
431
+ try:
432
+ after = os.stat(path)
433
+ stamp = (path, after.st_mtime_ns, after.st_size)
434
+ except OSError:
435
+ stamp = None
436
+ if stamp is not None:
437
+ _document_cache = (stamp, tree)
438
+ return tree
439
+
440
+
441
+ def forget_document() -> None:
442
+ """Drop the cached parse. Called by `write()`, and by tests."""
443
+ global _document_cache
444
+ _document_cache = None
445
+
446
+
447
+ def _dump(tree) -> str:
448
+ stream = io.StringIO()
449
+ _round_trip().dump(tree, stream)
450
+ return stream.getvalue()
451
+
452
+
453
+ def _in_file(tree, name: str):
454
+ """What the document says for one addressable name, or `ValueError`.
455
+
456
+ THE DOCUMENT CAN DISAGREE WITH THE SCHEMA, and that is not a
457
+ programming error here -- it is the documented workflow. `config.py`
458
+ binds at import and nothing re-reads the file (UN1), while
459
+ `explain()` tells every container row to "Edit it in config.yaml",
460
+ so a hand-edit made mid-session leaves the process holding valid
461
+ values over a file that no longer has the key.
462
+
463
+ KeyError AND TypeError, because the file can go two ways and both
464
+ were measured: a deleted or renamed key raises `KeyError`, and a
465
+ table flattened to a scalar (`tool_permissions: off`) raises
466
+ `TypeError: string indices must be integers` from the SECOND
467
+ subscript. Neither is a `ValueError`, which is what the shell
468
+ catches, and neither says which file it is about.
469
+
470
+ REPLACES `get_leaf`, which answered the same question with no
471
+ caller anywhere in the repository and would have been a third copy
472
+ of this one.
473
+ """
474
+ try:
475
+ if "." in name:
476
+ table, leaf = name.split(".", 1)
477
+ return tree[table][leaf]
478
+ return tree[name]
479
+ except KeyError:
480
+ raise ValueError(
481
+ f"{config_schema.CONFIG_PATH} no longer has a key called "
482
+ f"{name}. It had one when this session started, so the file "
483
+ f"has been edited since; relaunch to pick the change "
484
+ f"up.") from None
485
+ except TypeError as exc:
486
+ raise ValueError(
487
+ f"{config_schema.CONFIG_PATH} can no longer be read for "
488
+ f"{name} ({exc}) -- the block it lives in is no longer a "
489
+ f"table. It was one when this session started, so the file "
490
+ f"has been edited since; relaunch to pick the change "
491
+ f"up.") from exc
492
+
493
+
494
+ def place(tree, name: str, value: Any) -> None:
495
+ """Set a dotted name, keeping the prose that FOLLOWS it. Rule 2's teeth.
496
+
497
+ `tree[name] = value` loses comments, in two different ways, and both
498
+ were found by running it rather than by reading ruamel. Each costs the
499
+ user documentation out of their own file, silently, on a write that
500
+ reported itself as a one-line change.
501
+
502
+ ONE: THE TEXT AFTER A BLOCK SEQUENCE IS ANCHORED TO ITS LAST INDEX.
503
+ `node.ca.items[5]` on a six-entry list, not the key in the parent. So
504
+ replacing `models_rejecting_sampling_params` took the
505
+ `# Critic and embedder routing` banner and the AUTHORITY note under it
506
+ with it -- six lines. Mutating the node in place does not help; measured.
507
+
508
+ TWO: A VALUE THAT CHANGES SHAPE MOVES ITS PARENT'S COMMENT BETWEEN TWO
509
+ SLOTS. For a scalar the following text sits in `ca.items[name][2]`; when
510
+ the value becomes a block mapping ruamel moves it to slot 3 and emits it
511
+ after the block. Going back -- `/config critic_model off` after setting
512
+ a provider -- it writes a scalar again and slot 3 is never emitted, so
513
+ `embedder_model`'s three-line AUTHORITY comment was deleted from the
514
+ file. ruamel handles scalar -> block by itself; this handles the return
515
+ trip, and the leading newline is what makes the result byte-identical to
516
+ the document before the round trip rather than merely comment-complete.
517
+ """
518
+ from ruamel.yaml.comments import CommentedMap, CommentedSeq
519
+ from ruamel.yaml.tokens import CommentToken
520
+
521
+ parent, key = tree, name
522
+ if "." in name:
523
+ table, key = name.split(".", 1)
524
+ parent = tree[table]
525
+ was = parent.get(key)
526
+
527
+ if isinstance(value, (list, dict)):
528
+ new = (CommentedMap(value) if isinstance(value, dict)
529
+ else CommentedSeq(value))
530
+ anchors = getattr(getattr(was, "ca", None), "items", None)
531
+ if anchors and len(new):
532
+ old_keys = (list(was.keys()) if isinstance(was, dict)
533
+ else list(range(len(was))))
534
+ new_keys = (list(new.keys()) if isinstance(new, dict)
535
+ else list(range(len(new))))
536
+ if old_keys and old_keys[-1] in anchors:
537
+ new.ca.items[new_keys[-1]] = anchors[old_keys[-1]]
538
+ parent[key] = new
539
+ return
540
+
541
+ parent[key] = value
542
+ if not isinstance(was, (list, dict)):
543
+ return
544
+ slot = getattr(getattr(parent, "ca", None), "items", {}).get(key)
545
+ if slot and slot[3]:
546
+ slot[2] = CommentToken("\n" + "".join(tok.value for tok in slot[3]),
547
+ slot[3][0].start_mark)
548
+ slot[3] = None
549
+
550
+
551
+ def write(text: str, newline: str = "\n") -> None:
552
+ """Replace `config.yaml` with `text`, atomically. Raises OSError.
553
+
554
+ Temp file plus `os.replace`, which is `json_store.write_json_atomic`'s
555
+ reasoning applied to the one file in this project that is not JSON: a
556
+ truncate-then-write leaves the document empty for the length of the
557
+ write and permanently damaged if the process dies inside it, and THIS
558
+ document is the one without which nothing starts at all.
559
+
560
+ Not that function itself, which serialises JSON and would have to grow
561
+ a "or just write these bytes" mode to be shared.
562
+ """
563
+ path = config_schema.CONFIG_PATH
564
+ # A UNIQUE NAME, not a fixed `config.yaml.tmp` sibling. Two writers --
565
+ # a `/config` write and the launcher's merge in another process -- raced
566
+ # on the one name, and a failed `os.replace` (a read-only file on
567
+ # Windows, where opening the temp still succeeds) left the leftover in
568
+ # the install tree forever. `_validate_candidate` below already does it
569
+ # this way.
570
+ handle_fd, tmp = tempfile.mkstemp(prefix="config.", suffix=".writing.yaml",
571
+ dir=os.path.dirname(path))
572
+ try:
573
+ with open(handle_fd, "w", encoding="utf-8", newline="") as handle:
574
+ handle.write(text.replace("\n", newline))
575
+ os.replace(tmp, path)
576
+ except BaseException:
577
+ try:
578
+ os.unlink(tmp)
579
+ except OSError:
580
+ pass # the temp file may not exist; the original error is what is raised
581
+ raise
582
+ # See `document()`: a one-value change can leave the size identical, so
583
+ # the stamp alone would not always notice our own write.
584
+ forget_document()
585
+
586
+
587
+ # ---------------------------------------------------------------------------
588
+ # ---- Describing a key -----------------------------------------------------
589
+ # ---------------------------------------------------------------------------
590
+
591
+ def shown(value: Any) -> str:
592
+ """A value as `config.yaml` spells it, for a one-line description."""
593
+ if value is None:
594
+ return "null"
595
+ if isinstance(value, bool):
596
+ return "true" if value else "false"
597
+ if isinstance(value, str):
598
+ return value or '""'
599
+ if isinstance(value, (list, tuple, frozenset)):
600
+ return f"{len(value)} entries"
601
+ if isinstance(value, dict):
602
+ return f"{len(value)} entries"
603
+ return str(value)
604
+
605
+
606
+ def _bounds(metadata) -> dict:
607
+ """`{'gt': 0}` and friends, out of pydantic's constraint objects.
608
+
609
+ Read off the metadata rather than off the annotation alias, because the
610
+ alias is erased by the time `model_fields` is built: `PositiveInt` and a
611
+ hand-written `Annotated[int, Field(gt=0)]` are indistinguishable here,
612
+ which is the right outcome -- the description follows the CONSTRAINT, so
613
+ a new range shape needs no entry anywhere in this file.
614
+ """
615
+ out = {}
616
+ for item in metadata:
617
+ for attribute in ("gt", "ge", "lt", "le", "min_length"):
618
+ value = getattr(item, attribute, None)
619
+ if value is not None:
620
+ out[attribute] = value
621
+ return out
622
+
623
+
624
+ def _number_phrase(noun: str, bounds: dict) -> str:
625
+ if bounds.get("ge") == 0.0 and bounds.get("le") == 1.0:
626
+ return f"{noun} from 0 to 1"
627
+ if "ge" in bounds and "le" in bounds:
628
+ # #213's `Port`, and any closed range after it.
629
+ return f"{noun} from {bounds['ge']} to {bounds['le']}"
630
+ if bounds.get("gt") == 0:
631
+ return f"{noun}, above 0"
632
+ if bounds.get("ge") == 0:
633
+ return f"{noun}, 0 or more"
634
+ return noun
635
+
636
+
637
+ def describe(name: str, annotation, metadata) -> tuple:
638
+ """`(kind, possible values, takes_text, nullable)` for one field.
639
+
640
+ The phrasing is generated from the schema rather than written down per
641
+ key, and that is the point: `config.yaml` already carries a comment
642
+ saying what every value DOES, and a second hand-written copy of what it
643
+ may BE is the copy that goes stale. One function for all of them.
644
+
645
+ THE LAST TWO ARE FACTS, NOT PHRASING, and they are returned rather than
646
+ re-derived because `parse_value` used to recover them by reading the
647
+ PHRASING back -- `row.values.startswith("text")` and `"null" in
648
+ row.values`. That made a display string load-bearing for parsing: the
649
+ day a `Literal` gains an option whose first word is `text`, that field
650
+ silently stops being parsed as YAML while the panel still offers it a
651
+ closed vocabulary, with nothing raising. The annotation is right here.
652
+ """
653
+ origin = typing.get_origin(annotation)
654
+ args = typing.get_args(annotation)
655
+ bounds = _bounds(metadata)
656
+
657
+ if origin is typing.Literal:
658
+ return "scalar", " | ".join(str(a) for a in args), False, False
659
+ if annotation is bool:
660
+ return "scalar", "true | false", False, False
661
+ if annotation is int:
662
+ return "scalar", _number_phrase("whole number", bounds), False, False
663
+ if annotation is float:
664
+ return "scalar", _number_phrase("number", bounds), False, False
665
+ if annotation is str:
666
+ return ("scalar", "text, not empty" if bounds.get("min_length")
667
+ else "text", True, False)
668
+ if origin is typing.Union or origin is types.UnionType:
669
+ inner = [a for a in args if a is not type(None)]
670
+ if inner == [str]:
671
+ return "scalar", "text, or null", True, True
672
+ if inner and typing.get_origin(inner[0]) is dict:
673
+ return "pair", "<name>, or <PROVIDER> <name>, or off", False, True
674
+ return "container", "a list, or null", False, True
675
+ if origin is dict:
676
+ return "container", "a table", False, False
677
+ return "container", "a list", False, False
678
+
679
+
680
+ # ---------------------------------------------------------------------------
681
+ # ---- The catalogue --------------------------------------------------------
682
+ # ---------------------------------------------------------------------------
683
+
684
+ def catalogue(remembered_pair: Optional[tuple[str, str]] = None) -> list[KeyRow]:
685
+ """Every addressable name, in `config.yaml`'s own order.
686
+
687
+ FILE ORDER, not alphabetical, and it is worth saying why: the schema
688
+ declares its fields in the order the file writes them, under the same
689
+ section banners, so browsing the panel walks the document. Alphabetical
690
+ would interleave the sandbox with the scholar lookup and put
691
+ `compaction_*` in front of the model the harness runs on.
692
+
693
+ The two tables are expanded rather than listed, because a row that says
694
+ `tool_permissions · 23 entries` is not something anyone can act on, and
695
+ the 58 leaves are exactly the rows a person comes here for.
696
+
697
+ BOTH VALUES COME FROM HERE: the file's, parsed through the cached
698
+ document, and the session's, off the model bound at import. See
699
+ `KeyRow` for why one of them was not enough. `remembered_pair` is the
700
+ `/model` store's whole pair, or None; it is carried on the `model_name`
701
+ row's `remembered` field and changes nothing else.
702
+ """
703
+ config = config_schema.current()
704
+ tree = document()
705
+ authority = config_schema.HARNESS_AUTHORITY_KEYS
706
+ overrides = settings_overrides()
707
+ environment = {key.lower(): variable
708
+ for key, variable in config_schema.ENV_OVERRIDES.items()}
709
+
710
+ rows = []
711
+ for name, field in config_schema.HarnessConfig.model_fields.items():
712
+ if name in TABLES:
713
+ table = getattr(config, name)
714
+ tools = list(type(table).model_fields)
715
+ # THE TABLE ITSELF GETS A ROW, ahead of its leaves. Without one
716
+ # `/config tool_permissions` answered "tool_permissions is not a
717
+ # key in config.yaml" -- false three times over: it is a key, it
718
+ # is a top-level block in the file, and it is one of the nine
719
+ # AUTHORITY keys. A container row is what the other 17 containers
720
+ # already get: explained and counted, with the leaves set
721
+ # individually.
722
+ rows.append(KeyRow(
723
+ name=name,
724
+ kind="container",
725
+ values=f"{len(tools)} tools, each true | false",
726
+ in_file=_in_file(tree, name),
727
+ in_session=table,
728
+ authority=True))
729
+ for tool in tools:
730
+ leaf = f"{name}.{tool}"
731
+ rows.append(KeyRow(
732
+ name=leaf,
733
+ kind="scalar",
734
+ values="true | false",
735
+ in_file=_in_file(tree, leaf),
736
+ in_session=getattr(table, tool),
737
+ authority=True))
738
+ continue
739
+ kind, values, takes_text, nullable = describe(
740
+ name, field.annotation, field.metadata)
741
+ # EVERY SOURCE, not the first one found. An `if/elif` reported
742
+ # `model_name` as outranked by `$AGENT_MODEL` and never mentioned
743
+ # `settings.json default_model` -- the tier that arrives with a
744
+ # directory you cloned, and the one a person most needs told about.
745
+ variable = environment.get(name)
746
+ settings_key = overrides.get(name)
747
+ rows.append(KeyRow(
748
+ name=name,
749
+ kind=kind,
750
+ values=values,
751
+ # The raw document's own types for a container -- a list where
752
+ # the model holds a frozenset or a tuple. Never compared for a
753
+ # container, because `pending` is about the settable rows and a
754
+ # container cannot be written from here.
755
+ in_file=_in_file(tree, name),
756
+ in_session=getattr(config, name),
757
+ authority=name in authority,
758
+ environment_variable=variable,
759
+ settings_key=settings_key,
760
+ takes_text=takes_text,
761
+ nullable=nullable,
762
+ remembered=(remembered_pair if name == "model_name" else None)))
763
+ return rows
764
+
765
+
766
+ def pending_changes() -> list:
767
+ """The rows written this session and waiting on a restart.
768
+
769
+ Settable rows only: a container's file value is a list where the model
770
+ holds a frozenset or a tuple, so the two differ by construction and
771
+ would report as pending forever. Nothing can write one from here in any
772
+ case, so there is nothing for such a row to be pending about.
773
+ """
774
+ return [row for row in catalogue() if row.settable and row.pending]
775
+
776
+
777
+ def find(name: str,
778
+ remembered_pair: Optional[tuple[str, str]] = None) -> Optional[KeyRow]:
779
+ """The row called `name`, or None. Exact match, never a prefix.
780
+
781
+ CASE-INSENSITIVE, because every key in this file is lowercase and the
782
+ names people arrive with are not: `config.py` publishes them as
783
+ `MAX_TOKENS` and the documentation quotes both spellings. There is no
784
+ ambiguity to protect -- two rows differing only in case cannot exist,
785
+ since the schema's field names are the source of them. Prefix matching
786
+ in `matching()` is folded the same way, so what the panel completes and
787
+ what `find` resolves stay one rule.
788
+ """
789
+ wanted = name.lower()
790
+ for row in catalogue(remembered_pair):
791
+ if row.name.lower() == wanted:
792
+ return row
793
+ return None
794
+
795
+
796
+ def matching(prefix: str,
797
+ remembered_pair: Optional[tuple[str, str]] = None) -> list[KeyRow]:
798
+ """Every row whose name starts with `prefix`, in catalogue order.
799
+
800
+ Substring would be friendlier and is deliberately not done: the panel
801
+ completes what it draws into the prompt, and a match in the MIDDLE of a
802
+ name completes to something that does not contain what was typed, which
803
+ reads as the harness ignoring the keystrokes.
804
+
805
+ Case-folded, for `find`'s reason: typing `MAX_` should offer the same
806
+ rows `max_` does, or the completion and the lookup disagree about what
807
+ the user meant.
808
+ """
809
+ wanted = prefix.lower()
810
+ return [row for row in catalogue(remembered_pair)
811
+ if row.name.lower().startswith(wanted)]
812
+
813
+
814
+ def file_value(name: str, tree=None) -> Any:
815
+ """What `config.yaml` itself says for `name`. `KeyRow.in_file`'s source.
816
+
817
+ Kept as its own function for the callers that want one name without
818
+ building 166 rows to get it. `tree` is for a caller asking about many
819
+ at once, and matters less than it did now that `document()` caches.
820
+ """
821
+ if tree is None:
822
+ tree = document()
823
+ return _in_file(tree, name)
824
+
825
+
826
+ def explain(name: str, *,
827
+ remembered: Optional[tuple[str, str]] = None,
828
+ cli_pinned: bool = False,
829
+ session_pair: Optional[tuple[str, str]] = None) -> list[str]:
830
+ """The lines `/config <key>` writes. Plain facts, no styling.
831
+
832
+ HERE RATHER THAN IN THE HANDLER, for AGENTS.md's §16 rule: the terminal
833
+ is a shell, so what there is to SAY about a key is this module's, and
834
+ drawing it is `tui/app.py`'s. It also means the sentences are testable
835
+ without a terminal, which is where every one of them is checked.
836
+
837
+ `remembered` is the `/model` store's whole pair, if one is stored;
838
+ `cli_pinned` says a --provider/--model flag named this launch; and
839
+ `session_pair` is the provider/model actually running. All three are
840
+ read only for `model_name` -- the one key whose session value can come
841
+ from somewhere `catalogue()` cannot see -- and default to saying
842
+ nothing, so every existing caller keeps its current sentences.
843
+ """
844
+ row = find(name, remembered)
845
+ if row is None:
846
+ return [f"{name} is not a key in config.yaml."]
847
+
848
+ lines = [f"{row.name}: {shown(row.in_file)}"]
849
+ lines.append(f"Takes {row.values}.")
850
+ if row.kind == "container":
851
+ # The session's copy, not the document's: `todo_statuses` is a tuple
852
+ # here and a list there, and the tuple is what the code sees.
853
+ lines.extend(_entries(row.in_session))
854
+
855
+ if row.pending:
856
+ running = shown(row.in_session)
857
+ if name == "model_name" and session_pair is not None:
858
+ running = f"{session_pair[0]} | {session_pair[1]}"
859
+ lines.append(
860
+ f"Written this session. This one is still running "
861
+ f"{running} and will pick the new value up at the "
862
+ f"next launch.")
863
+
864
+ if name == "model_name" and remembered is not None:
865
+ provider, model = remembered
866
+ if session_pair == remembered and not cli_pinned:
867
+ lines.append(
868
+ f"This session is running {provider} | {model}, remembered "
869
+ f"with /model. A /config write here changes the harness "
870
+ f"default, not the remembered choice: it still wins at the "
871
+ f"next launch. Choose again with /model to move it.")
872
+ else:
873
+ lines.append(
874
+ f"A remembered {provider} | {model} is stored, but this "
875
+ f"session is not running it.")
876
+ elif (name == "model_name" and cli_pinned
877
+ and session_pair is not None):
878
+ lines.append(
879
+ f"This launch was pinned with --provider/--model, so this "
880
+ f"session is running {session_pair[0]} | {session_pair[1]}.")
881
+
882
+ if row.environment_variable:
883
+ variable = row.environment_variable
884
+ memory_wins = (
885
+ name == "model_name" and remembered is not None
886
+ and session_pair == remembered and not cli_pinned)
887
+ if os.environ.get(variable) is not None:
888
+ if memory_wins:
889
+ lines.append(
890
+ f"{variable} is set to {shown(row.in_session)}, but the "
891
+ f"remembered pair above outranks it this session -- only "
892
+ f"a --provider/--model flag outranks a remembered choice.")
893
+ else:
894
+ lines.append(
895
+ f"{variable} is set to {shown(row.in_session)}, so that is "
896
+ f"what this session is using and what the next launch will "
897
+ f"use too. config.yaml says {shown(row.in_file)}, and a "
898
+ f"write here changes that rather than what is in force.")
899
+ else:
900
+ lines.append(
901
+ f"{variable} would override this if it were set.")
902
+ elif row.outranked_by:
903
+ lines.extend(_settings_tier_lines(row))
904
+
905
+ # THE WORKSPACE PAIR (TECHNICAL_DEBT 28, batch 111). Two keys, one
906
+ # question between them, and the person reading either is the person
907
+ # about to assume the other. Said HERE rather than only in the launch
908
+ # refusal, because a refusal arrives after the decision and this
909
+ # arrives during it.
910
+ if name in ("workspace_dir", "workspace_is_project"):
911
+ lines.extend(_workspace_pair(name))
912
+
913
+ if row.authority:
914
+ key = authority_key(name)
915
+ lines.append(f"AUTHORITY. This decides {AUTHORITY_EFFECT[key]}")
916
+ lines.append(
917
+ "No settings file, environment variable or tool call can reach "
918
+ "it. Changing it here asks first.")
919
+ if row.kind == "pair":
920
+ role = "critic" if name == "critic_model" else "embedder"
921
+ lines.append(
922
+ f"/{role} sets this for the next run without a restart, and is "
923
+ f"remembered per user; this sets the harness default.")
924
+ if row.kind == "pair":
925
+ lines.append(
926
+ f"Set it with: /config {name} <PROVIDER> <name>, or "
927
+ f"/config {name} off")
928
+ elif row.settable:
929
+ lines.append(f"Set it with: /config {name} <value>")
930
+ else:
931
+ lines.append(
932
+ "Edit it in config.yaml. CONFIG_ARCHITECTURE.md says why it is "
933
+ "what it is.")
934
+ return lines
935
+
936
+
937
+ def _settings_tier_lines(row) -> list[str]:
938
+ """Whether a settings.json IS outranking this key, or merely could.
939
+
940
+ TECHNICAL_DEBT 12, batch 111. This used to be one sentence -- "a
941
+ project or user settings.json CAN win over whatever is written here"
942
+ -- which is a static possibility stated in a process that knows the
943
+ answer. `core/config_loader.settings_sources()` records which tier
944
+ wrote each setting, so the live case can name the tier and the value
945
+ and leave the reader with nothing to go and check.
946
+
947
+ THE OLD SENTENCE IS KEPT for the case where nothing speaks, because
948
+ there it is the whole truth and it is still worth saying: the reason
949
+ this key can be overridden is not visible from the key.
950
+
951
+ THE VALUE COMES FROM THE SETTINGS TIER, NOT FROM `row.in_session`, and
952
+ that is a trap worth naming. For a compaction key `in_session` is
953
+ `config.COMPACTION_*` -- what `config.yaml` said, bound at import --
954
+ because the settings merge happens inside `effective_compaction` and
955
+ never reaches the `config` module at all. So the two-values rule this
956
+ module is built on has a third value here, and `in_session` is the
957
+ wrong one of the three to quote in a sentence about what is winning.
958
+ """
959
+ from core import config_loader
960
+
961
+ tier = config_loader.settings_sources().get(row.settings_key)
962
+ if tier is None:
963
+ return [f"A {row.outranked_by} key outranks this one, so a project "
964
+ f"or user settings.json can win over whatever is written "
965
+ f"here."]
966
+
967
+ whose = {"project": "This project's", "user": "Your"}.get(
968
+ tier, f"A {tier}")
969
+ return [f"{whose} settings.json sets {row.settings_key} to "
970
+ f"{shown(_settings_value(row.settings_key))}, so that is what "
971
+ f"is in force and config.yaml's {shown(row.in_file)} is not. A "
972
+ f"write here does not change it -- the settings file wins "
973
+ f"again at the next launch."]
974
+
975
+
976
+ def _settings_value(path: str) -> Any:
977
+ """What the merged settings hold at a dotted *path*, one level deep.
978
+
979
+ One level because `_NESTED_SETTINGS` is one level; a deeper path
980
+ cannot exist, and inventing a general walker for it would be code
981
+ written against a shape the validator refuses.
982
+ """
983
+ from core import config_loader
984
+
985
+ settings = config_loader.get_settings()
986
+ section, _, leaf = path.partition(".")
987
+ if not leaf:
988
+ return settings.get(section)
989
+ return (settings.get(section) or {}).get(leaf)
990
+
991
+
992
+ def _workspace_pair(name: str) -> list[str]:
993
+ """What `explain` says about `workspace_dir` / `workspace_is_project`.
994
+
995
+ TECHNICAL_DEBT 28. The two keys answer different questions -- where the
996
+ file tools may write, and where the WORK is -- and for one release the
997
+ second question had no key at all, so writing the first and expecting
998
+ both was the obvious mistake to make. These sentences exist to make it
999
+ the unobvious one.
1000
+
1001
+ THE SESSION ANSWERS "is it", THE FILE ANSWERS "what is written", and
1002
+ keeping those apart is this module's whole subject (batch 85). `/config
1003
+ workspace_is_project true` writes the file and leaves the running
1004
+ process exactly where it was until a restart, so a line that read the
1005
+ file would tell someone their project had already moved when it had
1006
+ not -- in a sentence added to the file that states the rule.
1007
+
1008
+ The session's answer is `derived_values(current())` rather than
1009
+ `config.WORKSPACE_DIR_EXPLICIT`, because this module imports no
1010
+ first-party name but `config_schema` and that function IS the
1011
+ definition of the value; asking it is how these lines cannot drift
1012
+ from what `main()` will do.
1013
+ """
1014
+ row = find("workspace_is_project")
1015
+ in_file = bool(row and row.in_file)
1016
+ session = config_schema.current()
1017
+ now = bool(config_schema.derived_values(session)["WORKSPACE_DIR_EXPLICIT"])
1018
+ variable = os.environ.get("AGENT_WORKSPACE") is not None
1019
+
1020
+ if name == "workspace_dir":
1021
+ lines = [
1022
+ "This is the file tools' root. Whether it is also the PROJECT "
1023
+ "-- what workspace trust asks about, which .venastine/ is read, "
1024
+ "where /init writes, what memories belong to -- is the separate "
1025
+ "question workspace_is_project answers."]
1026
+ if now:
1027
+ named = ("$AGENT_WORKSPACE" if variable
1028
+ else "workspace_is_project")
1029
+ lines.append(
1030
+ f"It IS the project in this session, because {named} says "
1031
+ f"so, so moving this path moves the work with it.")
1032
+ else:
1033
+ lines.append(
1034
+ "It is NOT the project in this session: nothing named it, "
1035
+ "so the project is the directory you launched from. Set "
1036
+ "workspace_is_project true to change that.")
1037
+ if in_file is not bool(session.workspace_is_project):
1038
+ lines.append(
1039
+ f"config.yaml now says workspace_is_project: "
1040
+ f"{shown(in_file)}, which this session has not picked up. "
1041
+ f"The next launch will.")
1042
+ return lines
1043
+
1044
+ lines = [
1045
+ "True means the workspace above is also the project: workspace "
1046
+ "trust, the .venastine/ tier, /init's destination and "
1047
+ "project-scoped memories all move to it. Naming AGENT_WORKSPACE "
1048
+ "does the same thing; this is the way to say it in the file."]
1049
+ if variable:
1050
+ lines.append(
1051
+ "$AGENT_WORKSPACE is set, so the workspace is already the "
1052
+ "project this session whatever this key says. The two are OR'd "
1053
+ "-- there is no precedence between them to get wrong.")
1054
+ return lines
1055
+
1056
+
1057
+ def _entries(value: Any, cap: int = 12) -> list[str]:
1058
+ """A container's contents, capped, one per line.
1059
+
1060
+ CAPPED because `domain_authority_suffixes` has 105 entries and the
1061
+ transcript is a conversation, not a pager. The cap says how many are
1062
+ not shown rather than trailing off, for the same reason the suggestion
1063
+ panel's title counts what it did not draw.
1064
+ """
1065
+ if isinstance(value, dict):
1066
+ items = [f" {key}: {shown(item)}" for key, item in value.items()]
1067
+ elif isinstance(value, (list, tuple, frozenset)):
1068
+ items = [f" {shown(item)}" for item in sorted(value, key=str)]
1069
+ else:
1070
+ return []
1071
+ if len(items) <= cap:
1072
+ return items
1073
+ return items[:cap] + [f" … and {len(items) - cap} more, in config.yaml"]
1074
+
1075
+
1076
+ def authority_key(name: str) -> Optional[str]:
1077
+ """The authority key `name` belongs to, or None.
1078
+
1079
+ A leaf answers with its TABLE: `tool_permissions.shell` is gated because
1080
+ `tool_permissions` is, and the sentence the confirmation shows is the
1081
+ table's.
1082
+ """
1083
+ root = name.split(".", 1)[0]
1084
+ return root if root in config_schema.HARNESS_AUTHORITY_KEYS else None
1085
+
1086
+
1087
+ # ---------------------------------------------------------------------------
1088
+ # ---- Proposing a change ---------------------------------------------------
1089
+ # ---------------------------------------------------------------------------
1090
+
1091
+ #: The words that mean "no value" wherever `/config` takes one.
1092
+ #:
1093
+ #: PUBLIC, and `auto` is in it, because `tui/app._config_set` carried its own
1094
+ #: copy with `auto` and this one without -- so `/config critic_model auto`
1095
+ #: cleared the key while `/config default_effort auto` wrote the literal
1096
+ #: string and was refused by the schema. One word, two behaviours, decided by
1097
+ #: which branch a key happened to take. The value grammar lives here by this
1098
+ #: module's own rule; the terminal reads it.
1099
+ NULL_WORDS = ("null", "none", "off", "clear", "auto")
1100
+
1101
+
1102
+ def _unquoted(text: str) -> str:
1103
+ """`"x"` and `'x'` mean x, for the fields that take their text verbatim.
1104
+
1105
+ The only way to type an EMPTY string, which is what one shipped value
1106
+ is: `scholar_mailto` is `''` in the file, and without this there is no
1107
+ way to put it back. Typing `""` would set the two-character string
1108
+ `""` -- silently, so the key meant to carry an email address would
1109
+ carry a pair of quotes and OpenAlex would be sent them.
1110
+
1111
+ It also covers quoting out of habit, which the verbatim rule would
1112
+ otherwise take at its word.
1113
+ """
1114
+ if len(text) >= 2 and text[0] == text[-1] and text[0] in "\"'":
1115
+ return text[1:-1]
1116
+ return text
1117
+
1118
+
1119
+ def parse_value(row: KeyRow, text: str) -> Any:
1120
+ """Typed text, as the value the schema will be handed.
1121
+
1122
+ THE STRING FIELDS TAKE THEIR TEXT VERBATIM, and that exception is the
1123
+ whole reason this is not one `yaml.load` call. `sandbox_docker_image` is
1124
+ `docker.io/library/python:3.13-slim`, `scholar_api_url` is a URL and
1125
+ `db_path` is a path:
1126
+ handing those to a YAML parser asks it to guess, and the day a value
1127
+ contains `: ` it would guess "mapping" and the error would talk about a
1128
+ dict the user never typed.
1129
+
1130
+ Everything else IS parsed as YAML, so `true`, `0.4`, `18000` and `null`
1131
+ mean in the prompt exactly what they mean in the file -- and a value of
1132
+ the wrong shape is refused by the schema a moment later, naming the key,
1133
+ rather than by a second type system invented here.
1134
+ """
1135
+ text = text.strip()
1136
+ if not text:
1137
+ raise ValueError(f"{row.name} needs a value. It takes {row.values}.")
1138
+ if row.takes_text:
1139
+ if row.nullable and text.lower() in NULL_WORDS:
1140
+ return None
1141
+ return _unquoted(text)
1142
+ if row.nullable and text.lower() in NULL_WORDS:
1143
+ return None
1144
+ try:
1145
+ return YAML(typ="safe").load(io.StringIO(text))
1146
+ except Exception:
1147
+ # Unparseable as YAML is still a legal thing to have typed; let the
1148
+ # schema be the one that says what was wrong with it.
1149
+ return text
1150
+
1151
+
1152
+ def _validate_candidate(candidate: str, name: str, value: Any) -> None:
1153
+ """Run `candidate` past the loader as a FILE. Raises ValueError.
1154
+
1155
+ THROUGH THE SEAM, not through a reader assembled here.
1156
+ `config_schema.load(path=...)` was built in batch 83 for exactly this
1157
+ caller: it validates a candidate on its own terms, with no environment
1158
+ overlay and without touching the live cache, because the file is what
1159
+ the next launch reads and the environment it will read it under is not
1160
+ knowable now. A candidate missing `db_path` is refused here even in a
1161
+ shell where `APP_DB_PATH` happens to be set, which is the property that
1162
+ makes "this file will start" mean something.
1163
+
1164
+ The temp file sits beside `config.yaml` rather than in the system temp
1165
+ directory, so it lands on the same filesystem as the write that may
1166
+ follow and cannot be redirected somewhere unwritable by an environment
1167
+ variable.
1168
+
1169
+ The message is re-led rather than passed through: the loader names the
1170
+ file it was handed, and "config.a7f3.proposed.yaml is not valid" tells
1171
+ a person nothing. Everything after that first line -- the key, the
1172
+ problem, one line per fault -- is the loader's and is kept verbatim.
1173
+ """
1174
+ directory = os.path.dirname(config_schema.CONFIG_PATH)
1175
+ try:
1176
+ handle, path = tempfile.mkstemp(prefix="config.",
1177
+ suffix=".proposed.yaml", dir=directory)
1178
+ except OSError:
1179
+ # A GLOBAL npm PREFIX OWNED BY ROOT is an ordinary install, and the
1180
+ # directory above is not writable there. Without this the first
1181
+ # `/config` write of such a session raised PermissionError out of the
1182
+ # command handler and took the app down -- before anything could tell
1183
+ # the user the far more useful fact that the file cannot be written.
1184
+ # The same fallback `config_update._validates` carries.
1185
+ handle, path = tempfile.mkstemp(prefix="config.",
1186
+ suffix=".proposed.yaml")
1187
+ try:
1188
+ with open(handle, "w", encoding="utf-8", newline="") as stream:
1189
+ stream.write(candidate)
1190
+ try:
1191
+ config_schema.load(path=path)
1192
+ except ValueError as exc:
1193
+ detail = str(exc)
1194
+ _, _, rest = detail.partition("):\n")
1195
+ raise ValueError(
1196
+ f"{name} = {shown(value)} was refused:\n"
1197
+ + (rest or detail)) from None
1198
+ finally:
1199
+ try:
1200
+ os.unlink(path)
1201
+ except OSError:
1202
+ # A leftover temp file is untidy, not a failure to report over
1203
+ # the outcome of the validation the caller asked for.
1204
+ pass
1205
+
1206
+
1207
+ def _changed_lines(before: str, after: str) -> list:
1208
+ """`(line number, old, new)` for what actually moved between two texts.
1209
+
1210
+ ALIGNED, not zipped. `zip(old, new)` assumes the documents stay the same
1211
+ length: setting `critic_model` from `null` to a provider pair grows the
1212
+ file by two lines, and every line after the edit then pairs against its
1213
+ neighbour -- measured at 707 of 847 lines reported as changed for a
1214
+ one-line edit. It also stopped at the shorter document, so a change that
1215
+ only removes lines under-reported.
1216
+
1217
+ Line numbers are the NEW document's, because what the caller shows is
1218
+ the file as it will be.
1219
+ """
1220
+ import difflib
1221
+
1222
+ old, new = before.split("\n"), after.split("\n")
1223
+ changed = []
1224
+ matcher = difflib.SequenceMatcher(None, old, new, autojunk=False)
1225
+ for tag, i1, i2, j1, j2 in matcher.get_opcodes():
1226
+ if tag == "equal":
1227
+ continue
1228
+ for offset in range(max(i2 - i1, j2 - j1)):
1229
+ a = old[i1 + offset] if i1 + offset < i2 else ""
1230
+ b = new[j1 + offset] if j1 + offset < j2 else ""
1231
+ changed.append((j1 + offset + 1, a, b))
1232
+ return changed
1233
+
1234
+
1235
+ @dataclasses.dataclass(frozen=True)
1236
+ class Proposal:
1237
+ """A validated change that has not been written yet."""
1238
+
1239
+ name: str
1240
+ before: Any
1241
+ after: Any
1242
+ text: str # the whole document, as it would be written
1243
+ newline: str
1244
+ lines: list # the changed lines, `(number, old, new)`
1245
+
1246
+
1247
+ def propose(name: str, value: Any) -> Proposal:
1248
+ """Validate `name = value` against the whole document. Raises ValueError.
1249
+
1250
+ THE WHOLE DOCUMENT, not the one field, and that is what makes this worth
1251
+ routing through the file at all: `config_schema` carries cross-field
1252
+ invariants that a per-field check cannot see -- a compaction strategy has
1253
+ to appear in the roster beside it, a similarity band's floor has to be
1254
+ under its ceiling, every domain suffix has to name a class that exists.
1255
+ Setting one key can break one of those, and the failure belongs here,
1256
+ before the write, rather than at the next launch.
1257
+ """
1258
+ row = find(name)
1259
+ if row is None:
1260
+ raise ValueError(f"{name} is not a key in config.yaml.")
1261
+ if not row.settable:
1262
+ raise ValueError(
1263
+ f"{name} holds {shown(row.in_session)} and is edited in "
1264
+ f"config.yaml directly, not from here.")
1265
+
1266
+ text, newline = read_text()
1267
+ tree = _round_trip().load(io.StringIO(text))
1268
+ place(tree, name, value)
1269
+ candidate = _dump(tree)
1270
+ _validate_candidate(candidate, name, value)
1271
+
1272
+ changed = _changed_lines(text, candidate)
1273
+ # `in_file`, not `in_session`: "was" is about the value this write is
1274
+ # REPLACING, which is the document's. The two are the same until the
1275
+ # first write of a session, which is why taking the wrong one read as
1276
+ # correct for as long as nobody changed two values in one sitting.
1277
+ return Proposal(name=name, before=row.in_file, after=value,
1278
+ text=candidate, newline=newline, lines=changed)
1279
+
1280
+
1281
+ # ---------------------------------------------------------------------------
1282
+ # ---- Asking for a restart -------------------------------------------------
1283
+ # ---------------------------------------------------------------------------
1284
+
1285
+ @dataclasses.dataclass(frozen=True)
1286
+ class RestartRequest:
1287
+ """"Relaunch this harness so a written change takes effect."
1288
+
1289
+ Lives here rather than in `tui/` or `main.py` because both ends need
1290
+ it: the TUI exits with one, `main.py` acts on one, and a record they
1291
+ both import from a leaf module is cheaper than an edge between them.
1292
+
1293
+ It carries FACTS, not arguments. Which flags express "this thread, this
1294
+ model" is `main.py`'s question, and it is the module that owns the
1295
+ parser those flags belong to.
1296
+ """
1297
+
1298
+ key: str
1299
+ thread_id: Optional[str] = None
1300
+ provider: Optional[str] = None
1301
+ model: Optional[str] = None