@yahyahammad/venastine 0.1.0 → 0.3.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +19 -14
- package/CONFIG_ARCHITECTURE.md +2002 -0
- package/NOTICE +1 -1
- package/README.md +249 -93
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/plan.md +23 -5
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +261 -195
- package/agents/subagent_tool.py +280 -23
- package/agents/tui_commands.py +31 -21
- package/bin/venastine.mjs +528 -382
- package/bin/venastine.py +71 -0
- package/cli_commands.py +835 -0
- package/config.py +95 -1198
- package/config.yaml +1090 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +966 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +256 -0
- package/core/ansi.py +452 -0
- package/core/approval.py +27 -5
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +1249 -82
- package/core/commands.py +454 -0
- package/core/compaction.py +1735 -959
- package/core/config_loader.py +516 -97
- package/core/connect.py +686 -0
- package/core/events.py +68 -6
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +87 -4
- package/core/line_pattern.py +128 -0
- package/core/loop.py +2566 -1353
- package/core/memory.py +482 -370
- package/core/pipeline_models.py +23 -9
- package/core/provider_errors.py +234 -0
- package/core/reasoning/confidence_scoring.py +70 -54
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +232 -53
- package/core/reasoning/output_writer.py +90 -31
- package/core/reasoning/payload_validation.py +133 -7
- package/core/reasoning/pipeline_storage.py +427 -361
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +38 -14
- package/core/reasoning/source_corpus.py +110 -4
- package/core/replay.py +315 -167
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +308 -180
- package/database.py +82 -1
- package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +118 -77
- package/json_store.py +236 -16
- package/logging_setup.py +121 -11
- package/main.py +1672 -198
- package/mcp_client/client.py +257 -23
- package/mcp_client/config.py +484 -379
- package/mcp_client/registration.py +163 -2
- package/memories/manager.py +15 -0
- package/memories/tui_commands.py +21 -14
- package/package.json +303 -73
- package/project_init/config_files.py +4 -0
- package/project_init/generator.py +201 -37
- package/project_init/manifest.py +418 -406
- package/project_init/tui_commands.py +7 -4
- package/prompts/revalidate.md +1 -1
- package/prompts/revise.md +17 -15
- package/prompts/system_prompts.py +64 -10
- package/providers.json.example +94 -92
- package/pyproject.toml +149 -100
- package/requirements.txt +252 -29
- package/safety/policy_enforcement.py +1082 -682
- package/security/askpass.py +419 -0
- package/security/capability.py +37 -7
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +54 -7
- package/security/posture.py +124 -12
- package/security/protected_paths.py +198 -6
- package/security/sandbox.py +3262 -139
- package/security/secrets.py +855 -0
- package/skills/tui_commands.py +3 -4
- package/storage.py +1338 -1005
- package/tools/base.py +465 -305
- package/tools/builtin/_math_common.py +306 -16
- package/tools/builtin/_net_common.py +267 -61
- package/tools/builtin/arxiv.py +681 -223
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +239 -21
- package/tools/builtin/file_ops.py +341 -33
- package/tools/builtin/geometry.py +184 -148
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +10 -0
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +46 -12
- package/tools/builtin/probability_stats.py +224 -228
- package/tools/builtin/project_docs.py +80 -21
- package/tools/builtin/remember.py +21 -4
- package/tools/builtin/shell.py +586 -67
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +5 -3
- package/tools/builtin/web_search.py +329 -151
- package/tools/context.py +23 -0
- package/tools/isolation.py +387 -314
- package/tools/registry.py +374 -29
- package/tui/app.py +5281 -397
- package/tui/app.tcss +290 -9
- package/tui/commands.py +26 -61
- package/tui/diffs.py +286 -265
- package/tui/history.py +128 -0
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +1329 -0
- package/tui/meters.py +364 -0
- package/tui/screens.py +346 -92
- package/tui/themes.py +599 -366
- package/tui/widgets.py +2673 -116
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
package/config_edit.py
ADDED
|
@@ -0,0 +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
|