@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.
- package/.env.example +19 -19
- package/CONFIG_ARCHITECTURE.md +2030 -2002
- package/LICENSE +201 -201
- package/README.md +1034 -1034
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -106
- package/agents/builtin/review.md +74 -74
- package/agents/manager.py +261 -261
- package/agents/subagent_tool.py +472 -472
- package/agents/tui_commands.py +238 -146
- package/bin/venastine.mjs +528 -528
- package/bin/venastine.py +71 -71
- package/cli_commands.py +838 -835
- package/config.yaml +13 -0
- package/config_edit.py +1301 -1301
- package/config_schema.py +971 -966
- package/config_update.py +749 -749
- package/core/agent_activity.py +256 -256
- package/core/ansi.py +452 -452
- package/core/approval.py +137 -137
- package/core/call_view.py +364 -364
- package/core/cancel.py +121 -121
- package/core/chatgpt_auth.py +747 -747
- package/core/claims_view.py +107 -107
- package/core/client.py +2715 -2715
- package/core/commands.py +460 -454
- package/core/compaction.py +1735 -1735
- package/core/config_loader.py +1982 -1982
- package/core/connect.py +686 -686
- package/core/events.py +123 -123
- package/core/file_mentions.py +280 -280
- package/core/interaction.py +411 -411
- package/core/loop.py +2566 -2566
- package/core/memory.py +482 -482
- package/core/pipeline_models.py +190 -190
- package/core/provider_errors.py +234 -234
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -484
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/orchestrator.py +1561 -1561
- package/core/reasoning/output_writer.py +345 -345
- package/core/reasoning/payload_validation.py +524 -524
- package/core/reasoning/pipeline_storage.py +427 -427
- package/core/reasoning/scholar.py +458 -458
- package/core/reasoning/source_corpus.py +433 -433
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -315
- package/core/shell_sessions.py +1553 -1553
- package/credentials.py +307 -307
- package/database.py +333 -333
- package/docs/PRIVACY.md +78 -78
- package/docs/SECURITY.md +108 -108
- package/docs/THIRD_PARTY_NOTICES.md +148 -148
- package/env_secrets.py +118 -118
- package/json_store.py +343 -343
- package/logging_setup.py +295 -295
- package/main.py +3433 -3433
- package/mcp_client/client.py +733 -733
- package/mcp_client/config.py +484 -484
- package/mcp_client/registration.py +343 -343
- package/memories/manager.py +147 -147
- package/memories/tui_commands.py +319 -239
- package/package.json +303 -303
- package/project_init/config_files.py +282 -282
- package/project_init/generator.py +728 -728
- package/project_init/manifest.py +418 -418
- package/project_init/tui_commands.py +147 -147
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +17 -17
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -316
- package/providers.json.example +94 -94
- package/pyproject.toml +149 -149
- package/requirements.txt +295 -295
- package/safety/policy_enforcement.py +1082 -1082
- package/security/askpass.py +419 -419
- package/security/capability.py +207 -207
- package/security/confine.py +484 -484
- package/security/hosted.py +182 -182
- package/security/permissions.py +237 -237
- package/security/protected_paths.py +501 -501
- package/security/sandbox.py +4108 -4108
- package/skills/builtin/math/formal-specification.md +67 -67
- package/skills/builtin/math/numerical-methods.md +66 -66
- package/skills/builtin/research/experiment-design.md +62 -62
- package/skills/builtin/research/reproducibility.md +55 -55
- package/skills/builtin/research/source-evaluation.md +70 -70
- package/skills/builtin/research/statistical-inference.md +63 -63
- package/skills/builtin/research/technical-writing.md +59 -59
- package/skills/builtin/software/code-review.md +61 -61
- package/skills/builtin/software/debugging.md +61 -61
- package/skills/builtin/software/test-design.md +67 -67
- package/skills/tui_commands.py +110 -110
- package/storage.py +1338 -1338
- package/tools/base.py +465 -465
- package/tools/builtin/_math_common.py +667 -667
- package/tools/builtin/_net_common.py +267 -267
- package/tools/builtin/arxiv.py +681 -681
- package/tools/builtin/fetch_url.py +371 -371
- package/tools/builtin/file_ops.py +720 -720
- package/tools/builtin/geometry.py +184 -184
- package/tools/builtin/load_skill.py +76 -76
- package/tools/builtin/pin.py +227 -227
- package/tools/builtin/probability_stats.py +224 -224
- package/tools/builtin/project_docs.py +464 -464
- package/tools/builtin/remember.py +175 -175
- package/tools/builtin/shell.py +980 -980
- package/tools/builtin/todo.py +149 -149
- package/tools/builtin/web_search.py +328 -328
- package/tools/context.py +159 -159
- package/tools/isolation.py +387 -387
- package/tools/registry.py +1242 -1242
- package/tui/app.py +8318 -8307
- package/tui/app.tcss +747 -739
- package/tui/commands.py +26 -26
- package/tui/diffs.py +286 -286
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -102
- package/tui/markdown.py +1329 -1329
- package/tui/meters.py +364 -364
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -1197
- package/tui/themes.py +599 -599
- package/tui/widgets.py +3813 -3796
package/CONFIG_ARCHITECTURE.md
CHANGED
|
@@ -1,2002 +1,2030 @@
|
|
|
1
|
-
# CONFIG_ARCHITECTURE.md
|
|
2
|
-
|
|
3
|
-
**Why every value in `config.yaml` is what it is.**
|
|
4
|
-
|
|
5
|
-
`config.yaml` holds the harness's tunable values and says, in a line or two
|
|
6
|
-
per key, what each one *does*. This file is the other half: the argument. Most
|
|
7
|
-
of these numbers were chosen against a specific measurement or a specific
|
|
8
|
-
incident, several were reversed once, and a few are load-bearing in ways that
|
|
9
|
-
are invisible from the value alone. **Read the entry for a key before changing
|
|
10
|
-
it.** More than one of these has been "corrected" back to a value it was
|
|
11
|
-
deliberately moved away from.
|
|
12
|
-
|
|
13
|
-
The prose here was `config.py`'s, from the years when the values and their
|
|
14
|
-
history lived in one 1,210-line module of which 788 lines were comment. It was
|
|
15
|
-
carried over verbatim. Section headings are `config.py`'s own; the entry for
|
|
16
|
-
each key is named by its **`config.yaml` key**, so a key you are editing leads
|
|
17
|
-
straight here.
|
|
18
|
-
|
|
19
|
-
**Two things about that port, both worth knowing before you trust a
|
|
20
|
-
sentence here.** First, it is no longer verbatim in five places, each
|
|
21
|
-
marked and dated: the `tool_compute_timeout_s` arithmetic described a
|
|
22
|
-
value the code has not had for some time, three entries told the reader to
|
|
23
|
-
set something in `config.py` where an edit is now silently overwritten at
|
|
24
|
-
import, and one described a `settings.json` key that does not exist. The
|
|
25
|
-
rest is unchanged, so a diff against `config.py` before the migration is
|
|
26
|
-
still the way to check it. Second, **this file is hand-maintained from
|
|
27
|
-
here.** It was produced once by a migration script that was not kept;
|
|
28
|
-
nothing regenerates it, so a value's rationale moves when someone moves
|
|
29
|
-
it.
|
|
30
|
-
|
|
31
|
-
## How configuration is laid out
|
|
32
|
-
|
|
33
|
-
| File | Holds | Tier |
|
|
34
|
-
|---|---|---|
|
|
35
|
-
| `config.yaml` | every tunable value | harness, one location |
|
|
36
|
-
| `config_schema.py` | the schema, the environment overrides, the loader | -- |
|
|
37
|
-
| `config.py` | the same values as module attributes, for the code | -- |
|
|
38
|
-
| `~/.config/venastine/settings.json` | the user's overrides | user |
|
|
39
|
-
| `<project>/.venastine/settings.json` | a project's overrides, if trusted | project |
|
|
40
|
-
|
|
41
|
-
`settings.json` is merged across tiers by `core/config_loader.py`, and for the
|
|
42
|
-
keys it knows a **project's file beats the user's** (D29) because it is what
|
|
43
|
-
you authored versus what arrived with a directory you cloned. That precedence
|
|
44
|
-
is the reason for the two rules below.
|
|
45
|
-
|
|
46
|
-
### One location, and no override variable
|
|
47
|
-
|
|
48
|
-
`config.yaml` resolves from `config_schema.__file__`, beside `config.py`. There
|
|
49
|
-
is no user-tier copy, no project-tier copy, and **no environment variable that
|
|
50
|
-
redirects it**. That absence is a security property rather than an oversight.
|
|
51
|
-
|
|
52
|
-
`settings.json` refuses `shell_approval_mode`, `ensemble_models`,
|
|
53
|
-
`critic_model`, `embedder_model` and `research.granted_tools` **by name** --
|
|
54
|
-
R12, E2, G7 and SQ7, each argued in `ROADMAP_v2.md` -- and the argument is
|
|
55
|
-
always the same shape: a project's `settings.json` beats the user's and arrives
|
|
56
|
-
with a clone, so a key there would let a cloned repository set this harness's
|
|
57
|
-
approval posture or point its research passes at a provider you never chose. A
|
|
58
|
-
file that ships inside the harness, in exactly one place, carries none of that
|
|
59
|
-
risk. An `AGENT_CONFIG_FILE` variable would hand it straight back, and it would
|
|
60
|
-
look like the obvious sibling of `AGENT_ENV_FILE` and `APP_DB_PATH`. It is not:
|
|
61
|
-
those redirect *state*, and this is a shipped asset.
|
|
62
|
-
|
|
63
|
-
### The one location survives an npm update (batch 86)
|
|
64
|
-
|
|
65
|
-
`config.yaml` ships inside the package, and **npm replaces a package directory wholesale** -- measured with `npm pack` and two installs into a scratch prefix: an edited `max_tokens: 31337` came back as the shipped `16000`, and the new version's `max_iterations` default arrived with it. So the rule above had a cost nobody had paid attention to: every value an npm user had chosen was discarded at each update.
|
|
66
|
-
|
|
67
|
-
The fix is a merge, **not a second location**. `config_update.py` keeps the pristine copy of the installed version and a mirror of the user's own file in `~/.config/venastine/config-state/`, and after an update it re-applies the difference onto whatever npm has just written. The live document is still the one inside the harness, still resolved from `__file__`, still with no variable that redirects it -- the state directory holds HISTORY, which is state, and state has always been redirectable here. A reader who finds a `config.yaml` under the home directory and concludes the user tier is back has found the mirror, which nothing reads at startup.
|
|
68
|
-
|
|
69
|
-
Two consequences worth stating. Keys the user never touched adopt the new version's defaults, and keys the new version adds arrive at theirs -- the merge starts FROM the shipped file, so that half needs no code. And the nine AUTHORITY keys are restored like any other, each one named in the report the launch prints: an update must neither silently loosen nor silently tighten the posture, and the file surviving is the status quo.
|
|
70
|
-
|
|
71
|
-
### Read once, at startup
|
|
72
|
-
|
|
73
|
-
`config.py` imports `config_schema`, which reads the file, folds the
|
|
74
|
-
environment into the raw document, and validates the result — **once**, in
|
|
75
|
-
that order. The environment goes in *before* validation so that there is one
|
|
76
|
-
model with the overrides already in it: applied afterwards they would reach
|
|
77
|
-
only the namespace `config.py` publishes, and `config_schema.current()` would
|
|
78
|
-
quietly disagree with `config.<NAME>` about any key that has a variable.
|
|
79
|
-
Nothing re-reads the file. `security/posture.py`
|
|
80
|
-
depends on that: `config` binding at import is what makes
|
|
81
|
-
`os.environ[...] = ...` unable to move the security posture, where anything
|
|
82
|
-
reading `os.environ` at call time would follow the mutation (UN1, and batch
|
|
83
|
-
37's asymmetry). `tools/builtin/shell.py` validates the approval mode at its
|
|
84
|
-
own import, so the values must be final before it runs.
|
|
85
|
-
|
|
86
|
-
Editing `config.yaml` while the harness is running therefore changes nothing
|
|
87
|
-
until the next launch.
|
|
88
|
-
|
|
89
|
-
### The keys marked AUTHORITY
|
|
90
|
-
|
|
91
|
-
Nine keys decide what the harness may do to its host, or name a provider it
|
|
92
|
-
sends your content to. Nothing *unattended* can change them -- not a tool
|
|
93
|
-
call, not a settings file, not an environment variable.
|
|
94
|
-
`config_schema.HARNESS_AUTHORITY_KEYS` is the machine-readable list, and a
|
|
95
|
-
test holds it against `security/posture.Posture`'s fields and the five
|
|
96
|
-
by-name `settings.json` rejections. (Four ROADMAP markers, five keys:
|
|
97
|
-
`critic_model` and `embedder_model` share SQ7.)
|
|
98
|
-
|
|
99
|
-
**Batch 84 gave `/config` a route to them, behind a confirmation.** Until
|
|
100
|
-
then the rule was absolute: no in-session surface at all, a slash command
|
|
101
|
-
included. What changed is the reading of *why*. The `settings.json`
|
|
102
|
-
rejections argue from a file that arrives with a directory you cloned, and
|
|
103
|
-
the environment argument from a variable a subprocess can set; neither
|
|
104
|
-
describes a person typing at the prompt, who is the harness operator and is
|
|
105
|
-
the one `config.yaml` has always been edited by. The model cannot reach the
|
|
106
|
-
route -- `tui/commands.dispatch` is called from the prompt's submit handler
|
|
107
|
-
and nowhere else.
|
|
108
|
-
|
|
109
|
-
**What the file tools do here, stated accurately** (corrected in batch 87).
|
|
110
|
-
This said "the file tools refuse the harness install tree", and they do not:
|
|
111
|
-
`security/protected_paths.PROTECTED_SEGMENTS` is `{".venastine"}`, so
|
|
112
|
-
`file_ops._protected_path_error` denies a path carrying that segment and
|
|
113
|
-
returns None for `<install>/config.yaml`. The control that actually holds is
|
|
114
|
-
weaker and still real — `write` and `edit` ship **denied** in
|
|
115
|
-
`tool_permissions` and cannot be enabled at runtime, and `protected_paths`
|
|
116
|
-
makes a workspace that overlaps the harness tree a *startup error*, so the
|
|
117
|
-
install tree is never inside the workspace and a write there is
|
|
118
|
-
approval-gated rather than auto-approved. `protected_paths.py` says why the
|
|
119
|
-
difference is worth a paragraph: a half-understood control is worse than
|
|
120
|
-
none.
|
|
121
|
-
|
|
122
|
-
The compensating control is that the confirmation says what the key
|
|
123
|
-
PERMITS, not "are you sure": `config_edit.AUTHORITY_EFFECT` carries one
|
|
124
|
-
sentence per key and a test fails if a key has none. And the change still
|
|
125
|
-
does not take effect in the running process -- it is written to the file
|
|
126
|
-
and applied by relaunching, so the frozen posture is never edited under a
|
|
127
|
-
session that has already read it.
|
|
128
|
-
|
|
129
|
-
`ensemble_mode` is deliberately *not* one of them. It is a mode, persistable in
|
|
130
|
-
`settings.json`, and the worst it can do is spend more of a provider you
|
|
131
|
-
already chose -- the line `core/config_loader.py` draws between authority and
|
|
132
|
-
cost.
|
|
133
|
-
|
|
134
|
-
### Two values with no key in the file
|
|
135
|
-
|
|
136
|
-
Both are derived in `config_schema.derived_values()` because neither is a static
|
|
137
|
-
default, and giving either a key would change behaviour:
|
|
138
|
-
|
|
139
|
-
- **`OUTPUT_DIR`** is `AGENT_OUTPUT_DIR`, else `<AGENT_WORKSPACE or ".">/output`
|
|
140
|
-
-- one expression with no branch in it. Note the `"."` default here against
|
|
141
|
-
`workspace_dir`'s `"./workspace"`: an unset variable still means `./output`
|
|
142
|
-
rather than `./workspace/output`. A key would have to be ignored whenever
|
|
143
|
-
`AGENT_WORKSPACE` is named, which is the branch this form exists to avoid.
|
|
144
|
-
- **`WORKSPACE_DIR_EXPLICIT`** answers "was this workspace named as the project?",
|
|
145
|
-
and since batch 111 it has **two inputs, OR'd**: the **presence** of
|
|
146
|
-
`AGENT_WORKSPACE`, never its value, and the `workspace_is_project` key. The
|
|
147
|
-
presence rule is why the variable cannot be a value test -- the default
|
|
148
|
-
`./workspace` is a subdirectory of the launch directory, so comparing values
|
|
149
|
-
would move the project one level down for everyone who set nothing, and YAML
|
|
150
|
-
cannot express "was this variable named?". The key exists because that left a
|
|
151
|
-
person editing `config.yaml` with no way to say it at all (TECHNICAL_DEBT 28),
|
|
152
|
-
which cost them a refused launch telling them to set a variable in a session
|
|
153
|
-
where they had just set the key. Still live from batch 107: an unset variable
|
|
154
|
-
and an undeclared key make the LAUNCH DIRECTORY the project, and
|
|
155
|
-
`protected_paths.check_project` refuses that at startup when it is the install
|
|
156
|
-
tree (TECHNICAL_DEBT 26).
|
|
157
|
-
|
|
158
|
-
### The environment variables
|
|
159
|
-
|
|
160
|
-
`AGENT_MODEL`, `APP_DB_PATH`, `AGENT_WORKSPACE`, `AGENT_SHELL` and
|
|
161
|
-
`AGENT_SANDBOX_IMAGE` each override one key; `AGENT_OUTPUT_DIR` and
|
|
162
|
-
`AGENT_WORKSPACE` feed the two derived values above.
|
|
163
|
-
`config_schema.ENV_OVERRIDES` is the table, and `HARNESS_ENV_VARS` the full
|
|
164
|
-
list, so neither has to be maintained by hand anywhere else. An override is
|
|
165
|
-
folded into the document before validation, so it goes through the same type
|
|
166
|
-
check the file's own value does.
|
|
167
|
-
|
|
168
|
-
Note that there is **no variable for `config.yaml`'s own path** — see *One
|
|
169
|
-
location, and no override variable* above. That is the one absence in this
|
|
170
|
-
list which is a decision rather than an omission.
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
## Contents
|
|
174
|
-
|
|
175
|
-
- [Model and loop](#model-and-loop)
|
|
176
|
-
- [Loop control](#loop-control)
|
|
177
|
-
- [Subagents (ROADMAP_v2 §18)](#subagents-roadmap_v2-18)
|
|
178
|
-
- [
|
|
179
|
-
- [
|
|
180
|
-
- [
|
|
181
|
-
- [
|
|
182
|
-
- [
|
|
183
|
-
- [
|
|
184
|
-
- [
|
|
185
|
-
- [
|
|
186
|
-
- [
|
|
187
|
-
- [
|
|
188
|
-
- [
|
|
189
|
-
- [
|
|
190
|
-
- [
|
|
191
|
-
- [
|
|
192
|
-
- [
|
|
193
|
-
- [
|
|
194
|
-
- [
|
|
195
|
-
- [
|
|
196
|
-
- [
|
|
197
|
-
- [
|
|
198
|
-
- [
|
|
199
|
-
- [
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
the
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
### `
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
--
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
### `
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
the
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
by --
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
the
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
so
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
`
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
is
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
### `
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
|
-
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1404
|
-
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
|
|
1419
|
-
|
|
1420
|
-
|
|
1421
|
-
|
|
1422
|
-
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
|
-
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
the
|
|
1440
|
-
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
that
|
|
1447
|
-
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1456
|
-
|
|
1457
|
-
|
|
1458
|
-
|
|
1459
|
-
|
|
1460
|
-
|
|
1461
|
-
|
|
1462
|
-
|
|
1463
|
-
|
|
1464
|
-
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
### `
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
1508
|
-
|
|
1509
|
-
|
|
1510
|
-
|
|
1511
|
-
|
|
1512
|
-
|
|
1513
|
-
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
### `
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
### `
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
1537
|
-
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
|
|
1541
|
-
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1553
|
-
|
|
1554
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1557
|
-
an
|
|
1558
|
-
|
|
1559
|
-
|
|
1560
|
-
|
|
1561
|
-
### `
|
|
1562
|
-
|
|
1563
|
-
|
|
1564
|
-
|
|
1565
|
-
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1575
|
-
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
|
|
1579
|
-
|
|
1580
|
-
|
|
1581
|
-
|
|
1582
|
-
|
|
1583
|
-
|
|
1584
|
-
|
|
1585
|
-
|
|
1586
|
-
|
|
1587
|
-
|
|
1588
|
-
|
|
1589
|
-
|
|
1590
|
-
|
|
1591
|
-
|
|
1592
|
-
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
1596
|
-
|
|
1597
|
-
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
1606
|
-
|
|
1607
|
-
|
|
1608
|
-
|
|
1609
|
-
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
|
|
1614
|
-
|
|
1615
|
-
|
|
1616
|
-
|
|
1617
|
-
|
|
1618
|
-
|
|
1619
|
-
|
|
1620
|
-
|
|
1621
|
-
|
|
1622
|
-
|
|
1623
|
-
|
|
1624
|
-
|
|
1625
|
-
|
|
1626
|
-
|
|
1627
|
-
|
|
1628
|
-
|
|
1629
|
-
|
|
1630
|
-
|
|
1631
|
-
|
|
1632
|
-
|
|
1633
|
-
|
|
1634
|
-
|
|
1635
|
-
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
|
-
|
|
1647
|
-
|
|
1648
|
-
|
|
1649
|
-
|
|
1650
|
-
|
|
1651
|
-
|
|
1652
|
-
|
|
1653
|
-
|
|
1654
|
-
|
|
1655
|
-
|
|
1656
|
-
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
1666
|
-
|
|
1667
|
-
|
|
1668
|
-
|
|
1669
|
-
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
1673
|
-
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
|
-
|
|
1677
|
-
|
|
1678
|
-
|
|
1679
|
-
|
|
1680
|
-
|
|
1681
|
-
|
|
1682
|
-
|
|
1683
|
-
|
|
1684
|
-
|
|
1685
|
-
|
|
1686
|
-
|
|
1687
|
-
|
|
1688
|
-
|
|
1689
|
-
|
|
1690
|
-
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
|
|
1697
|
-
endpoint
|
|
1698
|
-
|
|
1699
|
-
|
|
1700
|
-
|
|
1701
|
-
|
|
1702
|
-
|
|
1703
|
-
|
|
1704
|
-
|
|
1705
|
-
|
|
1706
|
-
|
|
1707
|
-
|
|
1708
|
-
|
|
1709
|
-
|
|
1710
|
-
|
|
1711
|
-
|
|
1712
|
-
|
|
1713
|
-
|
|
1714
|
-
|
|
1715
|
-
|
|
1716
|
-
|
|
1717
|
-
|
|
1718
|
-
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1722
|
-
|
|
1723
|
-
|
|
1724
|
-
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
|
-
|
|
1728
|
-
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
|
|
1759
|
-
|
|
1760
|
-
|
|
1761
|
-
|
|
1762
|
-
|
|
1763
|
-
|
|
1764
|
-
|
|
1765
|
-
|
|
1766
|
-
|
|
1767
|
-
|
|
1768
|
-
|
|
1769
|
-
|
|
1770
|
-
|
|
1771
|
-
|
|
1772
|
-
|
|
1773
|
-
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
|
|
1777
|
-
|
|
1778
|
-
|
|
1779
|
-
|
|
1780
|
-
|
|
1781
|
-
|
|
1782
|
-
|
|
1783
|
-
|
|
1784
|
-
|
|
1785
|
-
|
|
1786
|
-
|
|
1787
|
-
|
|
1788
|
-
|
|
1789
|
-
|
|
1790
|
-
|
|
1791
|
-
|
|
1792
|
-
|
|
1793
|
-
|
|
1794
|
-
|
|
1795
|
-
|
|
1796
|
-
|
|
1797
|
-
|
|
1798
|
-
|
|
1799
|
-
|
|
1800
|
-
|
|
1801
|
-
|
|
1802
|
-
|
|
1803
|
-
|
|
1804
|
-
|
|
1805
|
-
|
|
1806
|
-
|
|
1807
|
-
|
|
1808
|
-
|
|
1809
|
-
|
|
1810
|
-
|
|
1811
|
-
|
|
1812
|
-
|
|
1813
|
-
|
|
1814
|
-
|
|
1815
|
-
|
|
1816
|
-
|
|
1817
|
-
|
|
1818
|
-
|
|
1819
|
-
|
|
1820
|
-
|
|
1821
|
-
|
|
1822
|
-
|
|
1823
|
-
|
|
1824
|
-
|
|
1825
|
-
|
|
1826
|
-
|
|
1827
|
-
|
|
1828
|
-
|
|
1829
|
-
|
|
1830
|
-
|
|
1831
|
-
|
|
1832
|
-
|
|
1833
|
-
|
|
1834
|
-
|
|
1835
|
-
|
|
1836
|
-
|
|
1837
|
-
|
|
1838
|
-
|
|
1839
|
-
|
|
1840
|
-
|
|
1841
|
-
|
|
1842
|
-
|
|
1843
|
-
|
|
1844
|
-
|
|
1845
|
-
|
|
1846
|
-
|
|
1847
|
-
|
|
1848
|
-
|
|
1849
|
-
|
|
1850
|
-
|
|
1851
|
-
|
|
1852
|
-
|
|
1853
|
-
|
|
1854
|
-
|
|
1855
|
-
|
|
1856
|
-
|
|
1857
|
-
|
|
1858
|
-
|
|
1859
|
-
|
|
1860
|
-
|
|
1861
|
-
|
|
1862
|
-
|
|
1863
|
-
|
|
1864
|
-
|
|
1865
|
-
|
|
1866
|
-
|
|
1867
|
-
|
|
1868
|
-
|
|
1869
|
-
|
|
1870
|
-
|
|
1871
|
-
|
|
1872
|
-
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
|
-
|
|
1876
|
-
|
|
1877
|
-
|
|
1878
|
-
|
|
1879
|
-
|
|
1880
|
-
|
|
1881
|
-
|
|
1882
|
-
|
|
1883
|
-
|
|
1884
|
-
|
|
1885
|
-
|
|
1886
|
-
|
|
1887
|
-
|
|
1888
|
-
|
|
1889
|
-
|
|
1890
|
-
|
|
1891
|
-
|
|
1892
|
-
|
|
1893
|
-
|
|
1894
|
-
|
|
1895
|
-
|
|
1896
|
-
|
|
1897
|
-
|
|
1898
|
-
|
|
1899
|
-
`
|
|
1900
|
-
|
|
1901
|
-
|
|
1902
|
-
|
|
1903
|
-
|
|
1904
|
-
|
|
1905
|
-
|
|
1906
|
-
|
|
1907
|
-
|
|
1908
|
-
|
|
1909
|
-
|
|
1910
|
-
|
|
1911
|
-
|
|
1912
|
-
|
|
1913
|
-
|
|
1914
|
-
the
|
|
1915
|
-
|
|
1916
|
-
|
|
1917
|
-
|
|
1918
|
-
|
|
1919
|
-
|
|
1920
|
-
|
|
1921
|
-
|
|
1922
|
-
|
|
1923
|
-
|
|
1924
|
-
|
|
1925
|
-
|
|
1926
|
-
|
|
1927
|
-
|
|
1928
|
-
|
|
1929
|
-
|
|
1930
|
-
|
|
1931
|
-
that
|
|
1932
|
-
|
|
1933
|
-
|
|
1934
|
-
|
|
1935
|
-
|
|
1936
|
-
|
|
1937
|
-
|
|
1938
|
-
|
|
1939
|
-
|
|
1940
|
-
|
|
1941
|
-
|
|
1942
|
-
|
|
1943
|
-
|
|
1944
|
-
|
|
1945
|
-
|
|
1946
|
-
|
|
1947
|
-
|
|
1948
|
-
|
|
1949
|
-
|
|
1950
|
-
|
|
1951
|
-
|
|
1952
|
-
|
|
1953
|
-
|
|
1954
|
-
|
|
1955
|
-
|
|
1956
|
-
|
|
1957
|
-
|
|
1958
|
-
|
|
1959
|
-
|
|
1960
|
-
|
|
1961
|
-
|
|
1962
|
-
|
|
1963
|
-
|
|
1964
|
-
|
|
1965
|
-
|
|
1966
|
-
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
|
-
|
|
1970
|
-
|
|
1971
|
-
|
|
1972
|
-
|
|
1973
|
-
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
1977
|
-
|
|
1978
|
-
|
|
1979
|
-
|
|
1980
|
-
|
|
1981
|
-
|
|
1982
|
-
|
|
1983
|
-
|
|
1984
|
-
|
|
1985
|
-
|
|
1986
|
-
|
|
1987
|
-
|
|
1988
|
-
|
|
1989
|
-
|
|
1990
|
-
|
|
1991
|
-
|
|
1992
|
-
|
|
1993
|
-
|
|
1994
|
-
|
|
1995
|
-
|
|
1996
|
-
#### `tool_approvals.
|
|
1997
|
-
|
|
1998
|
-
§
|
|
1999
|
-
|
|
2000
|
-
|
|
2001
|
-
|
|
2002
|
-
|
|
1
|
+
# CONFIG_ARCHITECTURE.md
|
|
2
|
+
|
|
3
|
+
**Why every value in `config.yaml` is what it is.**
|
|
4
|
+
|
|
5
|
+
`config.yaml` holds the harness's tunable values and says, in a line or two
|
|
6
|
+
per key, what each one *does*. This file is the other half: the argument. Most
|
|
7
|
+
of these numbers were chosen against a specific measurement or a specific
|
|
8
|
+
incident, several were reversed once, and a few are load-bearing in ways that
|
|
9
|
+
are invisible from the value alone. **Read the entry for a key before changing
|
|
10
|
+
it.** More than one of these has been "corrected" back to a value it was
|
|
11
|
+
deliberately moved away from.
|
|
12
|
+
|
|
13
|
+
The prose here was `config.py`'s, from the years when the values and their
|
|
14
|
+
history lived in one 1,210-line module of which 788 lines were comment. It was
|
|
15
|
+
carried over verbatim. Section headings are `config.py`'s own; the entry for
|
|
16
|
+
each key is named by its **`config.yaml` key**, so a key you are editing leads
|
|
17
|
+
straight here.
|
|
18
|
+
|
|
19
|
+
**Two things about that port, both worth knowing before you trust a
|
|
20
|
+
sentence here.** First, it is no longer verbatim in five places, each
|
|
21
|
+
marked and dated: the `tool_compute_timeout_s` arithmetic described a
|
|
22
|
+
value the code has not had for some time, three entries told the reader to
|
|
23
|
+
set something in `config.py` where an edit is now silently overwritten at
|
|
24
|
+
import, and one described a `settings.json` key that does not exist. The
|
|
25
|
+
rest is unchanged, so a diff against `config.py` before the migration is
|
|
26
|
+
still the way to check it. Second, **this file is hand-maintained from
|
|
27
|
+
here.** It was produced once by a migration script that was not kept;
|
|
28
|
+
nothing regenerates it, so a value's rationale moves when someone moves
|
|
29
|
+
it.
|
|
30
|
+
|
|
31
|
+
## How configuration is laid out
|
|
32
|
+
|
|
33
|
+
| File | Holds | Tier |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| `config.yaml` | every tunable value | harness, one location |
|
|
36
|
+
| `config_schema.py` | the schema, the environment overrides, the loader | -- |
|
|
37
|
+
| `config.py` | the same values as module attributes, for the code | -- |
|
|
38
|
+
| `~/.config/venastine/settings.json` | the user's overrides | user |
|
|
39
|
+
| `<project>/.venastine/settings.json` | a project's overrides, if trusted | project |
|
|
40
|
+
|
|
41
|
+
`settings.json` is merged across tiers by `core/config_loader.py`, and for the
|
|
42
|
+
keys it knows a **project's file beats the user's** (D29) because it is what
|
|
43
|
+
you authored versus what arrived with a directory you cloned. That precedence
|
|
44
|
+
is the reason for the two rules below.
|
|
45
|
+
|
|
46
|
+
### One location, and no override variable
|
|
47
|
+
|
|
48
|
+
`config.yaml` resolves from `config_schema.__file__`, beside `config.py`. There
|
|
49
|
+
is no user-tier copy, no project-tier copy, and **no environment variable that
|
|
50
|
+
redirects it**. That absence is a security property rather than an oversight.
|
|
51
|
+
|
|
52
|
+
`settings.json` refuses `shell_approval_mode`, `ensemble_models`,
|
|
53
|
+
`critic_model`, `embedder_model` and `research.granted_tools` **by name** --
|
|
54
|
+
R12, E2, G7 and SQ7, each argued in `ROADMAP_v2.md` -- and the argument is
|
|
55
|
+
always the same shape: a project's `settings.json` beats the user's and arrives
|
|
56
|
+
with a clone, so a key there would let a cloned repository set this harness's
|
|
57
|
+
approval posture or point its research passes at a provider you never chose. A
|
|
58
|
+
file that ships inside the harness, in exactly one place, carries none of that
|
|
59
|
+
risk. An `AGENT_CONFIG_FILE` variable would hand it straight back, and it would
|
|
60
|
+
look like the obvious sibling of `AGENT_ENV_FILE` and `APP_DB_PATH`. It is not:
|
|
61
|
+
those redirect *state*, and this is a shipped asset.
|
|
62
|
+
|
|
63
|
+
### The one location survives an npm update (batch 86)
|
|
64
|
+
|
|
65
|
+
`config.yaml` ships inside the package, and **npm replaces a package directory wholesale** -- measured with `npm pack` and two installs into a scratch prefix: an edited `max_tokens: 31337` came back as the shipped `16000`, and the new version's `max_iterations` default arrived with it. So the rule above had a cost nobody had paid attention to: every value an npm user had chosen was discarded at each update.
|
|
66
|
+
|
|
67
|
+
The fix is a merge, **not a second location**. `config_update.py` keeps the pristine copy of the installed version and a mirror of the user's own file in `~/.config/venastine/config-state/`, and after an update it re-applies the difference onto whatever npm has just written. The live document is still the one inside the harness, still resolved from `__file__`, still with no variable that redirects it -- the state directory holds HISTORY, which is state, and state has always been redirectable here. A reader who finds a `config.yaml` under the home directory and concludes the user tier is back has found the mirror, which nothing reads at startup.
|
|
68
|
+
|
|
69
|
+
Two consequences worth stating. Keys the user never touched adopt the new version's defaults, and keys the new version adds arrive at theirs -- the merge starts FROM the shipped file, so that half needs no code. And the nine AUTHORITY keys are restored like any other, each one named in the report the launch prints: an update must neither silently loosen nor silently tighten the posture, and the file surviving is the status quo.
|
|
70
|
+
|
|
71
|
+
### Read once, at startup
|
|
72
|
+
|
|
73
|
+
`config.py` imports `config_schema`, which reads the file, folds the
|
|
74
|
+
environment into the raw document, and validates the result — **once**, in
|
|
75
|
+
that order. The environment goes in *before* validation so that there is one
|
|
76
|
+
model with the overrides already in it: applied afterwards they would reach
|
|
77
|
+
only the namespace `config.py` publishes, and `config_schema.current()` would
|
|
78
|
+
quietly disagree with `config.<NAME>` about any key that has a variable.
|
|
79
|
+
Nothing re-reads the file. `security/posture.py`
|
|
80
|
+
depends on that: `config` binding at import is what makes
|
|
81
|
+
`os.environ[...] = ...` unable to move the security posture, where anything
|
|
82
|
+
reading `os.environ` at call time would follow the mutation (UN1, and batch
|
|
83
|
+
37's asymmetry). `tools/builtin/shell.py` validates the approval mode at its
|
|
84
|
+
own import, so the values must be final before it runs.
|
|
85
|
+
|
|
86
|
+
Editing `config.yaml` while the harness is running therefore changes nothing
|
|
87
|
+
until the next launch.
|
|
88
|
+
|
|
89
|
+
### The keys marked AUTHORITY
|
|
90
|
+
|
|
91
|
+
Nine keys decide what the harness may do to its host, or name a provider it
|
|
92
|
+
sends your content to. Nothing *unattended* can change them -- not a tool
|
|
93
|
+
call, not a settings file, not an environment variable.
|
|
94
|
+
`config_schema.HARNESS_AUTHORITY_KEYS` is the machine-readable list, and a
|
|
95
|
+
test holds it against `security/posture.Posture`'s fields and the five
|
|
96
|
+
by-name `settings.json` rejections. (Four ROADMAP markers, five keys:
|
|
97
|
+
`critic_model` and `embedder_model` share SQ7.)
|
|
98
|
+
|
|
99
|
+
**Batch 84 gave `/config` a route to them, behind a confirmation.** Until
|
|
100
|
+
then the rule was absolute: no in-session surface at all, a slash command
|
|
101
|
+
included. What changed is the reading of *why*. The `settings.json`
|
|
102
|
+
rejections argue from a file that arrives with a directory you cloned, and
|
|
103
|
+
the environment argument from a variable a subprocess can set; neither
|
|
104
|
+
describes a person typing at the prompt, who is the harness operator and is
|
|
105
|
+
the one `config.yaml` has always been edited by. The model cannot reach the
|
|
106
|
+
route -- `tui/commands.dispatch` is called from the prompt's submit handler
|
|
107
|
+
and nowhere else.
|
|
108
|
+
|
|
109
|
+
**What the file tools do here, stated accurately** (corrected in batch 87).
|
|
110
|
+
This said "the file tools refuse the harness install tree", and they do not:
|
|
111
|
+
`security/protected_paths.PROTECTED_SEGMENTS` is `{".venastine"}`, so
|
|
112
|
+
`file_ops._protected_path_error` denies a path carrying that segment and
|
|
113
|
+
returns None for `<install>/config.yaml`. The control that actually holds is
|
|
114
|
+
weaker and still real — `write` and `edit` ship **denied** in
|
|
115
|
+
`tool_permissions` and cannot be enabled at runtime, and `protected_paths`
|
|
116
|
+
makes a workspace that overlaps the harness tree a *startup error*, so the
|
|
117
|
+
install tree is never inside the workspace and a write there is
|
|
118
|
+
approval-gated rather than auto-approved. `protected_paths.py` says why the
|
|
119
|
+
difference is worth a paragraph: a half-understood control is worse than
|
|
120
|
+
none.
|
|
121
|
+
|
|
122
|
+
The compensating control is that the confirmation says what the key
|
|
123
|
+
PERMITS, not "are you sure": `config_edit.AUTHORITY_EFFECT` carries one
|
|
124
|
+
sentence per key and a test fails if a key has none. And the change still
|
|
125
|
+
does not take effect in the running process -- it is written to the file
|
|
126
|
+
and applied by relaunching, so the frozen posture is never edited under a
|
|
127
|
+
session that has already read it.
|
|
128
|
+
|
|
129
|
+
`ensemble_mode` is deliberately *not* one of them. It is a mode, persistable in
|
|
130
|
+
`settings.json`, and the worst it can do is spend more of a provider you
|
|
131
|
+
already chose -- the line `core/config_loader.py` draws between authority and
|
|
132
|
+
cost.
|
|
133
|
+
|
|
134
|
+
### Two values with no key in the file
|
|
135
|
+
|
|
136
|
+
Both are derived in `config_schema.derived_values()` because neither is a static
|
|
137
|
+
default, and giving either a key would change behaviour:
|
|
138
|
+
|
|
139
|
+
- **`OUTPUT_DIR`** is `AGENT_OUTPUT_DIR`, else `<AGENT_WORKSPACE or ".">/output`
|
|
140
|
+
-- one expression with no branch in it. Note the `"."` default here against
|
|
141
|
+
`workspace_dir`'s `"./workspace"`: an unset variable still means `./output`
|
|
142
|
+
rather than `./workspace/output`. A key would have to be ignored whenever
|
|
143
|
+
`AGENT_WORKSPACE` is named, which is the branch this form exists to avoid.
|
|
144
|
+
- **`WORKSPACE_DIR_EXPLICIT`** answers "was this workspace named as the project?",
|
|
145
|
+
and since batch 111 it has **two inputs, OR'd**: the **presence** of
|
|
146
|
+
`AGENT_WORKSPACE`, never its value, and the `workspace_is_project` key. The
|
|
147
|
+
presence rule is why the variable cannot be a value test -- the default
|
|
148
|
+
`./workspace` is a subdirectory of the launch directory, so comparing values
|
|
149
|
+
would move the project one level down for everyone who set nothing, and YAML
|
|
150
|
+
cannot express "was this variable named?". The key exists because that left a
|
|
151
|
+
person editing `config.yaml` with no way to say it at all (TECHNICAL_DEBT 28),
|
|
152
|
+
which cost them a refused launch telling them to set a variable in a session
|
|
153
|
+
where they had just set the key. Still live from batch 107: an unset variable
|
|
154
|
+
and an undeclared key make the LAUNCH DIRECTORY the project, and
|
|
155
|
+
`protected_paths.check_project` refuses that at startup when it is the install
|
|
156
|
+
tree (TECHNICAL_DEBT 26).
|
|
157
|
+
|
|
158
|
+
### The environment variables
|
|
159
|
+
|
|
160
|
+
`AGENT_MODEL`, `APP_DB_PATH`, `AGENT_WORKSPACE`, `AGENT_SHELL` and
|
|
161
|
+
`AGENT_SANDBOX_IMAGE` each override one key; `AGENT_OUTPUT_DIR` and
|
|
162
|
+
`AGENT_WORKSPACE` feed the two derived values above.
|
|
163
|
+
`config_schema.ENV_OVERRIDES` is the table, and `HARNESS_ENV_VARS` the full
|
|
164
|
+
list, so neither has to be maintained by hand anywhere else. An override is
|
|
165
|
+
folded into the document before validation, so it goes through the same type
|
|
166
|
+
check the file's own value does.
|
|
167
|
+
|
|
168
|
+
Note that there is **no variable for `config.yaml`'s own path** — see *One
|
|
169
|
+
location, and no override variable* above. That is the one absence in this
|
|
170
|
+
list which is a decision rather than an omission.
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
## Contents
|
|
174
|
+
|
|
175
|
+
- [Model and loop](#model-and-loop)
|
|
176
|
+
- [Loop control](#loop-control)
|
|
177
|
+
- [Subagents (ROADMAP_v2 §18)](#subagents-roadmap_v2-18)
|
|
178
|
+
- [The active agent (ROADMAP_v3 §59)](#the-active-agent-roadmap_v3-59)
|
|
179
|
+
- [Deep research pipeline](#deep-research-pipeline)
|
|
180
|
+
- [Spend cap (batch 27, #4)](#spend-cap-batch-27-4)
|
|
181
|
+
- [Ensemble mode (ROADMAP §10, as redesigned by its revisit)](#ensemble-mode-roadmap-10-as-redesigned-by-its-revisit)
|
|
182
|
+
- [Sampling-parameter support (ROADMAP_v2 §16 prerequisite)](#sampling-parameter-support-roadmap_v2-16-prerequisite)
|
|
183
|
+
- [Critic-model routing (ROADMAP §11)](#critic-model-routing-roadmap-11)
|
|
184
|
+
- [Embedder routing (ROADMAP_v2 §45, SQ2/SQ7)](#embedder-routing-roadmap_v2-45-sq2sq7)
|
|
185
|
+
- [Source authority: domain classes (ROADMAP_v2 §45, SQ4)](#source-authority-domain-classes-roadmap_v2-45-sq4)
|
|
186
|
+
- [The sources/ artifact (ROADMAP_v2 §45, SQ8)](#the-sources-artifact-roadmap_v2-45-sq8)
|
|
187
|
+
- [Scholarly authority: OpenAlex (ROADMAP_v2 §45, SQ5/SQ9)](#scholarly-authority-openalex-roadmap_v2-45-sq5sq9)
|
|
188
|
+
- [Reasoning effort (ROADMAP_v2 §16; default changed batch 25, #139)](#reasoning-effort-roadmap_v2-16-default-changed-batch-25-139)
|
|
189
|
+
- [Database](#database)
|
|
190
|
+
- [Output artifacts](#output-artifacts)
|
|
191
|
+
- [File-ops workspace (ROADMAP §6)](#file-ops-workspace-roadmap-6)
|
|
192
|
+
- [/init (ROADMAP_v2 §24)](#init-roadmap_v2-24)
|
|
193
|
+
- [MCP teardown (ROADMAP_v2 §37 F6, #64)](#mcp-teardown-roadmap_v2-37-f6-64)
|
|
194
|
+
- [Shell / sandbox (ROADMAP §7)](#shell-sandbox-roadmap-7)
|
|
195
|
+
- [Output redaction (#167/#49, batch 20)](#output-redaction-16749-batch-20)
|
|
196
|
+
- [Compaction (ROADMAP_v2 §21)](#compaction-roadmap_v2-21)
|
|
197
|
+
- [Catalog text (ROADMAP_v2 §32, A5)](#catalog-text-roadmap_v2-32-a5)
|
|
198
|
+
- [Summaries, references and the checklist (ROADMAP_v2 §21c / §23)](#summaries-references-and-the-checklist-roadmap_v2-21c-23)
|
|
199
|
+
- [Context windows (ROADMAP_v2 §21 M1, as amended by batches 30 and 44)](#context-windows-roadmap_v2-21-m1-as-amended-by-batches-30-and-44)
|
|
200
|
+
- [Tool permissions and approvals (ROADMAP_v2 §15, D24)](#tool-permissions-and-approvals-roadmap_v2-15-d24)
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Model and loop
|
|
205
|
+
|
|
206
|
+
### `model_name`
|
|
207
|
+
|
|
208
|
+
--- Model / loop settings -- these were missing; call_model, RunAgentLoop,
|
|
209
|
+
and database.py all depend on them ---
|
|
210
|
+
|
|
211
|
+
### `max_tokens`
|
|
212
|
+
|
|
213
|
+
Per-call output ceiling. Raised from 4096 in ROADMAP_v2 §16: on current
|
|
214
|
+
Anthropic models max_tokens caps THINKING PLUS RESPONSE TEXT together, so
|
|
215
|
+
4096 truncated answers mid-sentence as soon as reasoning effort was
|
|
216
|
+
enabled. There is no default cumulative budget for it to interact with any
|
|
217
|
+
more (batch 27, #4): spend is uncapped unless settings.json
|
|
218
|
+
max_token_budget says otherwise.
|
|
219
|
+
|
|
220
|
+
## Loop control
|
|
221
|
+
|
|
222
|
+
### `max_iterations`
|
|
223
|
+
|
|
224
|
+
Raised from 20 in batch 16 (#45): this is THE default step ceiling -- the
|
|
225
|
+
`or config.MAX_ITERATIONS` fallback at every agent-shaped call site, the
|
|
226
|
+
value an invalid `max_steps:` frontmatter field is repaired to, and the
|
|
227
|
+
ceiling of every chat turn and research pass that does not name its own.
|
|
228
|
+
|
|
229
|
+
### `model_call_max_retries`
|
|
230
|
+
|
|
231
|
+
Batch 91. Nothing retried a model call before this, and the SDKs cover less
|
|
232
|
+
than they appear to: openai and anthropic retry a request that fails BEFORE
|
|
233
|
+
its stream opens (408/409/429/5xx, connection errors, twice each), but an
|
|
234
|
+
error sent inside a stream that opened with 200 is raised straight up by
|
|
235
|
+
both, and google-genai retries nothing at all unless told to (1.0.0,
|
|
236
|
+
2.29.0 since batch 172, and 2.32.0 since batch 234, measured on a 503:
|
|
237
|
+
with no `retry_options` it makes one attempt).
|
|
238
|
+
OpenRouter reports an
|
|
239
|
+
overloaded upstream exactly that way -- "The service is temporarily
|
|
240
|
+
unavailable", "Upstream idle timeout exceeded" -- which failed four nested
|
|
241
|
+
subagents in the run that prompted this.
|
|
242
|
+
|
|
243
|
+
Two, so a call gets three attempts. The SDK retries are KEPT (owner
|
|
244
|
+
decision) and happen inside each attempt, so the worst case is nine HTTP
|
|
245
|
+
requests for one call; turning the SDKs' off would lose their retry-after
|
|
246
|
+
handling for the statuses they already cover well. `core/provider_errors.py`
|
|
247
|
+
decides what qualifies -- temporary provider errors only, never a bad
|
|
248
|
+
request, an auth failure or a harness bug -- and `core/loop.py` decides
|
|
249
|
+
WHEN: a run whose output reaches no screen is retried whatever it had
|
|
250
|
+
streamed, a run someone is watching only before its first delta, because a
|
|
251
|
+
transcript row cannot be taken back.
|
|
252
|
+
|
|
253
|
+
### `model_call_retry_base_delay_s`
|
|
254
|
+
|
|
255
|
+
Batch 91. Three seconds, then six, with a quarter either way of jitter.
|
|
256
|
+
Deliberately slower than the SDKs' half-second start (owner decision): these
|
|
257
|
+
retries sit ABOVE the SDK's own, so by the time one fires the provider has
|
|
258
|
+
already refused several requests in quick succession, and a rate limit met
|
|
259
|
+
with more of the same only extends itself. The jitter is for siblings: the
|
|
260
|
+
failures that prompted this came in pairs from one parallel spawn batch, and
|
|
261
|
+
without it they would retry in the same instant. A server's retry-after can
|
|
262
|
+
lengthen a wait, never shorten it, up to 60 seconds.
|
|
263
|
+
|
|
264
|
+
## Subagents (ROADMAP_v2 §18)
|
|
265
|
+
|
|
266
|
+
### `subagent_max_depth`
|
|
267
|
+
|
|
268
|
+
Maximum spawn_subagent nesting. The counter lives on
|
|
269
|
+
ToolContext.subagent_depth; this is the value it is checked against (C3).
|
|
270
|
+
|
|
271
|
+
### `subagent_max_parallel`
|
|
272
|
+
|
|
273
|
+
§47 slice 8 (NA10). How many calls of one response may run at once, for
|
|
274
|
+
tools whose ToolSpec declares `parallel`. A ceiling, not a target: a
|
|
275
|
+
response naming fewer runs fewer, and a response naming more runs them in
|
|
276
|
+
waves of this size. 1 makes the parallel path behave exactly like the
|
|
277
|
+
sequential one, which is the escape hatch if concurrency is ever suspect.
|
|
278
|
+
|
|
279
|
+
Three because that is the case the design keeps citing -- one turn
|
|
280
|
+
spawning `explore` three times -- and because three children at depth 1,
|
|
281
|
+
each able to nest to SUBAGENT_MAX_DEPTH, is a bounded worst case for the
|
|
282
|
+
serialised approval queue and for the SQLite writers.
|
|
283
|
+
|
|
284
|
+
## The active agent (ROADMAP_v3 §59)
|
|
285
|
+
|
|
286
|
+
### `agent_cycle`
|
|
287
|
+
|
|
288
|
+
UI3, UI5 and UI6. The agents shift+tab steps through in the TUI's prompt,
|
|
289
|
+
in order. The cycle is short on purpose. Twelve or more built-in, user and
|
|
290
|
+
project agents would make a list to scroll through, not a cycle, and the
|
|
291
|
+
request was for moving between two or three ways of working.
|
|
292
|
+
|
|
293
|
+
**`default` is always the first stop and is never listed** (UI6). The
|
|
294
|
+
plain harness is then never more than a few presses away, and no roster can
|
|
295
|
+
strand a user in an agent. A `default` entry is ignored rather than refused:
|
|
296
|
+
the stop is already there.
|
|
297
|
+
|
|
298
|
+
**Names, checked when the key is pressed.** The user and project tiers are
|
|
299
|
+
discovered after this file is read, so the schema cannot know whether a
|
|
300
|
+
project's agent exists. A name no tier provides is skipped and named in the
|
|
301
|
+
transcript once per session. Refusing the launch over it would make a
|
|
302
|
+
project agent's absence a reason not to start.
|
|
303
|
+
|
|
304
|
+
**Here and not in an agent's frontmatter** (UI5, the owner's choice). A
|
|
305
|
+
frontmatter flag would let a project's agent add itself to the user's cycle,
|
|
306
|
+
and the order would have to come from tier and file name.
|
|
307
|
+
|
|
308
|
+
An empty list gives shift+tab back to Textual's reverse focus, which is
|
|
309
|
+
what it did before §59. `/agent <name>` reaches every agent, listed or not.
|
|
310
|
+
|
|
311
|
+
## Deep research pipeline
|
|
312
|
+
|
|
313
|
+
### `max_pipeline_retries`
|
|
314
|
+
|
|
315
|
+
max revise/re-validate loop iterations per claim before fallback
|
|
316
|
+
|
|
317
|
+
### `max_json_retries`
|
|
318
|
+
|
|
319
|
+
max corrective follow-up attempts when a pass returns malformed JSON
|
|
320
|
+
|
|
321
|
+
(total attempts per pass = MAX_JSON_RETRIES + 1). See ROADMAP §3.
|
|
322
|
+
|
|
323
|
+
## Spend cap (batch 27, #4)
|
|
324
|
+
|
|
325
|
+
There is NO default spend ceiling any more. The loop's cumulative
|
|
326
|
+
input+output counter is a BILLING meter -- the prompt is re-sent and
|
|
327
|
+
re-billed on every step of a tool-using turn, so it grows quadratically
|
|
328
|
+
in steps, which is correct as billing and meaningless as a size limit.
|
|
329
|
+
Reading it as "how large may a thread get" is the defect TECHNICAL_DEBT
|
|
330
|
+
item 9 recorded; size reasoning reads ModelResponse.turn_new_tokens and
|
|
331
|
+
memory.last_input_tokens now, and compaction keys off measured context
|
|
332
|
+
size (it never keyed off this number).
|
|
333
|
+
|
|
334
|
+
A user who wants a hard ceiling sets settings.json `max_token_budget`
|
|
335
|
+
(int tokens per _run() invocation -- one user turn, one research pass,
|
|
336
|
+
one /init run). core/config_loader.spend_cap() resolves it, and the
|
|
337
|
+
headroom advisory in effective_compaction() speaks only when a cap is
|
|
338
|
+
configured. Hard limits at the provider remain the stronger instrument:
|
|
339
|
+
they see the same bill and cannot be forgotten by a code path. The three
|
|
340
|
+
constants this file used to carry (MAX_TOKEN_BUDGET 250k,
|
|
341
|
+
RESEARCH_PASS_TOKEN_BUDGET 1M for passes, INIT_TOKEN_BUDGET 1M) died
|
|
342
|
+
here -- the two 1M envelopes existed only because the 250k chat value
|
|
343
|
+
was misread as bounding pass context (the Pass-1-with-14-tool-calls
|
|
344
|
+
incident in DEVLOG), and with no default cap there is nothing to work
|
|
345
|
+
around.
|
|
346
|
+
|
|
347
|
+
Deferred for now (core sequential pipeline only, per current scope):
|
|
348
|
+
```text
|
|
349
|
+
(none remaining -- ensemble_mode/ensemble_n built in ROADMAP §10,
|
|
350
|
+
critic_model built in ROADMAP §11)
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
## Ensemble mode (ROADMAP §10, as redesigned by its revisit)
|
|
354
|
+
|
|
355
|
+
### `ensemble_mode`
|
|
356
|
+
|
|
357
|
+
Run Pass 1 once per entry below, then extract the union of claims across
|
|
358
|
+
candidates, and send a factual claim at most half of them asserted to Pass
|
|
359
|
+
6a/6b to be checked (ROADMAP_v3 §90). Off by default.
|
|
360
|
+
|
|
361
|
+
DIVERSITY COMES FROM DIFFERENT MODELS, NOT DIFFERENT SAMPLING (E1). §10
|
|
362
|
+
originally raised `temperature` on N runs of one model. That could not work
|
|
363
|
+
on current Anthropic models, which reject sampling parameters outright (see
|
|
364
|
+
MODELS_REJECTING_SAMPLING_PARAMS), so the section was built, documented as
|
|
365
|
+
working, and could not execute against this harness's own default model.
|
|
366
|
+
ENSEMBLE_TEMPERATURE is deleted rather than repaired: it was an ABSOLUTE
|
|
367
|
+
value being used as though it were a raise, so what "1.0" meant differed
|
|
368
|
+
per provider, and so did how much diversity a run actually got.
|
|
369
|
+
|
|
370
|
+
The deeper reason is §11's, verbatim: "a model checking its own output for
|
|
371
|
+
errors shares that model's blind spots." N samples of one model agree most
|
|
372
|
+
confidently on that model's systematic errors, which is exactly where a
|
|
373
|
+
research harness needs agreement to mean something. Different models do
|
|
374
|
+
not share blind spots, so their agreement is real evidence.
|
|
375
|
+
|
|
376
|
+
N is len(ENSEMBLE_MODELS) -- derived, never configured separately (E3). The
|
|
377
|
+
denominator of a confidence score must not be able to disagree with the
|
|
378
|
+
roster that produced it.
|
|
379
|
+
|
|
380
|
+
`config.yaml` ONLY, deliberately -- there is no settings.json key for
|
|
381
|
+
this, following `critic_model` (E2). Trusting a cloned repo already lets it pick
|
|
382
|
+
the provider and multiply pipeline cost; a project-tier list of N providers
|
|
383
|
+
is that same grant multiplied by N.
|
|
384
|
+
|
|
385
|
+
Fewer than two DISTINCT (provider_name, model) pairs is refused, not
|
|
386
|
+
tolerated: one model cannot disagree with itself, so every claim would
|
|
387
|
+
score maximal consistency and Pass 5 would read that as confidence. That
|
|
388
|
+
is the original defect, and repeating the same entry N times is the way to
|
|
389
|
+
recreate it through this config.
|
|
390
|
+
|
|
391
|
+
### `ensemble_models`
|
|
392
|
+
|
|
393
|
+
Example, as it is written in `config.yaml` -- a sequence of mappings,
|
|
394
|
+
not the Python assignment this example used to show:
|
|
395
|
+
|
|
396
|
+
```yaml
|
|
397
|
+
ensemble_models:
|
|
398
|
+
- {provider_name: ANTHROPIC, model: claude-opus-5}
|
|
399
|
+
- {provider_name: OPENAI, model: gpt-5.1}
|
|
400
|
+
- {provider_name: GOOGLE, model: gemini-2.5-pro}
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
## Sampling-parameter support (ROADMAP_v2 §16 prerequisite)
|
|
404
|
+
|
|
405
|
+
### `models_rejecting_sampling_params`
|
|
406
|
+
|
|
407
|
+
Models that reject temperature/top_p/top_k. Current Anthropic models
|
|
408
|
+
removed these parameters outright (any value returns HTTP 400); Sonnet 5
|
|
409
|
+
rejects non-default values. Steering is expected to happen through
|
|
410
|
+
prompting and MODEL_EFFORT_LEVELS instead.
|
|
411
|
+
|
|
412
|
+
A static table rather than a capability query: the Models API capability
|
|
413
|
+
tree does not report sampling support, so unlike effort levels (which ARE
|
|
414
|
+
queryable, see MODEL_EFFORT_LEVELS) there is nothing to ask. Same posture
|
|
415
|
+
as §21's MODEL_CONTEXT_WINDOWS -- honest about being incomplete, and
|
|
416
|
+
incompleteness is safe here because the failure is a loud 400, not a
|
|
417
|
+
silent wrong answer.
|
|
418
|
+
|
|
419
|
+
EXCEPT FOR A MODEL THAT IGNORES THEM, which is why two Google names are
|
|
420
|
+
listed (ROADMAP_v3 §87, A82). Gemini 3.6 Flash and 3.5 Flash-Lite ignore
|
|
421
|
+
the parameters: no error, no effect. Google says every later Gemini will do
|
|
422
|
+
the same and then refuse them with a 400, so a new Gemini belongs here when
|
|
423
|
+
it ships. OpenAI's reasoning models are NOT listed: core/client.py drops a
|
|
424
|
+
temperature on OPENAI whenever a reasoning effort other than "none" is
|
|
425
|
+
sent, which is OpenAI's documented rule and needs no names.
|
|
426
|
+
|
|
427
|
+
ON ANTHROPIC THE LIST IS NOT CONSULTED, since batch 234 (A82, amended).
|
|
428
|
+
anthropic 2.x sends API version 2026-10-21, which refuses all three
|
|
429
|
+
parameters on every model, even at the default, so core/client.py drops a
|
|
430
|
+
temperature there on every model. The claude names stay, and the five
|
|
431
|
+
5.x-generation ones were added (Fable 5.1, Mythos 5.1, Opus 5.5, Sonnet
|
|
432
|
+
5.5, Haiku 5.5), for Claude reached by its bare name through an
|
|
433
|
+
OpenAI-compatible gateway, which still sends whatever it is given.
|
|
434
|
+
|
|
435
|
+
## Critic-model routing (ROADMAP §11)
|
|
436
|
+
|
|
437
|
+
### `critic_model`
|
|
438
|
+
|
|
439
|
+
Route the critic/grounding passes (3a, 3b, 6c) to a different model than
|
|
440
|
+
the generator, so a model isn't checking its own output for errors.
|
|
441
|
+
None means every pass uses the same provider/model — no special routing.
|
|
442
|
+
Example to enable: {"provider_name": "OPENAI", "model": "gpt-5.1"}
|
|
443
|
+
|
|
444
|
+
## Embedder routing (ROADMAP_v2 §45, SQ2/SQ7)
|
|
445
|
+
|
|
446
|
+
### `embedder_model`
|
|
447
|
+
|
|
448
|
+
The model that turns a claim and a source passage into vectors, so
|
|
449
|
+
`similarity_score` is a cosine rather than a self-report. None -- the
|
|
450
|
+
default -- means the pipeline warns once at launch and falls back to the
|
|
451
|
+
grounding model's own number, under source_grounding.md's anchored
|
|
452
|
+
rubric.
|
|
453
|
+
|
|
454
|
+
`config.yaml` ONLY, with no settings.json key, following `critic_model`
|
|
455
|
+
and `ensemble_models` (E2): choosing a provider is a grant, and this one sends
|
|
456
|
+
claim text and fetched page text to whoever is named. `/embedder` writes
|
|
457
|
+
to the user-tier store in core/pipeline_models.py, which OUTRANKS this.
|
|
458
|
+
Example: {"provider_name": "OPENAI", "model": "text-embedding-3-small"}
|
|
459
|
+
|
|
460
|
+
### `similarity_calibration`
|
|
461
|
+
|
|
462
|
+
Asymmetric embedders score materially worse without their prefixes and
|
|
463
|
+
produce NO ERROR AT ALL when they are missing, which is why this is a
|
|
464
|
+
table rather than something inferred. Keyed by a substring of the model
|
|
465
|
+
slug, longest match wins; a model matching nothing gets no prefix, which
|
|
466
|
+
is correct for every symmetric embedder (OpenAI's, Cohere's, Voyage's).
|
|
467
|
+
|
|
468
|
+
`task_type` is Google's equivalent and is ignored by every other
|
|
469
|
+
provider. Incomplete on purpose: an unlisted asymmetric model scores
|
|
470
|
+
lower than it should, which is visible in the artifact as a low cosine
|
|
471
|
+
on a source that plainly matches -- and adding a row is the fix.
|
|
472
|
+
Raw cosine is NOT a 0-1 score, and treating it as one is the quiet way
|
|
473
|
+
to publish a wrong number. Unrelated text sits near 0.1 on some models
|
|
474
|
+
and above 0.7 on others, so the same passage would score "irrelevant" on
|
|
475
|
+
one embedder and "supports the claim" on another. This maps the useful
|
|
476
|
+
band onto 0-1: below `floor` is noise, above `ceiling` is as close as
|
|
477
|
+
that model gets.
|
|
478
|
+
|
|
479
|
+
Keyed by a substring of the model slug, longest match wins; anything
|
|
480
|
+
unlisted takes DEFAULT_SIMILARITY_CALIBRATION. The RAW cosine is always
|
|
481
|
+
recorded beside the calibrated score, so a bad row here is visible in
|
|
482
|
+
the artifact and fixable after the fact rather than baked in.
|
|
483
|
+
|
|
484
|
+
### `default_similarity_calibration`
|
|
485
|
+
|
|
486
|
+
### `embedder_prefixes`
|
|
487
|
+
|
|
488
|
+
## Source authority: domain classes (ROADMAP_v2 §45, SQ4)
|
|
489
|
+
|
|
490
|
+
### `domain_authority_classes`
|
|
491
|
+
|
|
492
|
+
What a source is worth before anything is known about the specific page.
|
|
493
|
+
Two tables, deliberately: a CLASS carries the number, and a SUFFIX names
|
|
494
|
+
which class a host belongs to. A user who thinks preprints deserve more
|
|
495
|
+
edits one number; a user adding their field's own trusted domain edits a
|
|
496
|
+
membership. One combined {suffix: score} table would make the first of
|
|
497
|
+
those a find-and-replace across a hundred rows.
|
|
498
|
+
|
|
499
|
+
THE SIGNAL IS A RESTRICTED REGISTRY, NOT A FAMILIAR SUFFIX. `.gov`,
|
|
500
|
+
`.mil`, `.int` and `.edu` gate registration -- you cannot buy one -- and
|
|
501
|
+
so do `gov.uk`, `ac.uk`, `gc.ca` and their equivalents worldwide, which
|
|
502
|
+
is why source_scoring derives the `<kind>.<cc>` forms rather than
|
|
503
|
+
enumerating them here. `.org` gates nothing at all and never has, so it
|
|
504
|
+
sits barely above `.com`; treating it as trustworthy is the single most
|
|
505
|
+
common version of this mistake.
|
|
506
|
+
|
|
507
|
+
INCOMPLETE ON PURPOSE, and safe when incomplete: an unlisted host takes
|
|
508
|
+
DEFAULT_DOMAIN_AUTHORITY, which is the generic-commercial number. The
|
|
509
|
+
failure mode is a good source scored ordinary, never a bad source scored
|
|
510
|
+
authoritative, and the model's bounded adjustment (below) is the route
|
|
511
|
+
for the first.
|
|
512
|
+
|
|
513
|
+
**Notes on individual entries.**
|
|
514
|
+
|
|
515
|
+
.gov .mil .int .edu, gov.uk, ac.uk...
|
|
516
|
+
WHO, UN, World Bank, OECD, EU
|
|
517
|
+
IETF, W3C, ISO, NIST, IEC
|
|
518
|
+
not peer reviewed; §45 SQ5 refines this
|
|
519
|
+
encyclopaedias -- a pointer to a source
|
|
520
|
+
an unrestricted registry, small bump
|
|
521
|
+
|
|
522
|
+
### `default_domain_authority`
|
|
523
|
+
|
|
524
|
+
== generic_commercial, for an unknown host
|
|
525
|
+
|
|
526
|
+
### `domain_authority_suffixes`
|
|
527
|
+
|
|
528
|
+
host suffix -> class. Longest suffix wins, so `blogs.nature.com` can be
|
|
529
|
+
listed separately from `nature.com` if it ever needs to be.
|
|
530
|
+
|
|
531
|
+
**Notes on individual entries.**
|
|
532
|
+
|
|
533
|
+
Restricted registries. The bare TLDs; the `<kind>.<cc>` second-level
|
|
534
|
+
forms are derived in source_scoring.py rather than listed.
|
|
535
|
+
Intergovernmental bodies, whose hosts are ordinary .org/.int names.
|
|
536
|
+
Standards bodies.
|
|
537
|
+
Peer-reviewed publishers and indexes.
|
|
538
|
+
Preprint servers and repositories -- not peer reviewed.
|
|
539
|
+
News organisations with a correction policy and a masthead. An
|
|
540
|
+
ALLOWLIST, because "news site" is not a property of a domain suffix
|
|
541
|
+
and the alternative is scoring every .com that publishes articles.
|
|
542
|
+
Tertiary references -- they summarise sources rather than being one.
|
|
543
|
+
Blog and newsletter platforms: the host says nothing about the author.
|
|
544
|
+
Forums and Q&A. Often correct, never attributable.
|
|
545
|
+
Social media. Speculation and unattributed claims travel here fastest,
|
|
546
|
+
which is the whole reason a claim needs grounding elsewhere.
|
|
547
|
+
Aggregators that republish without attribution, and image boards with
|
|
548
|
+
no text to ground anything in. The measured case: a Pinterest pin
|
|
549
|
+
scored similarity 1.0 on a Nobel Prize claim.
|
|
550
|
+
|
|
551
|
+
### `authority_adjustment_cap`
|
|
552
|
+
|
|
553
|
+
How far the model may move a computed authority, in either direction
|
|
554
|
+
(§45, SQ4). Small on purpose: it is a correction for what a domain
|
|
555
|
+
cannot see -- a primary source on an ordinary host, an opinion column on
|
|
556
|
+
a masthead -- not a second opinion about the number. An adjustment
|
|
557
|
+
arriving without a reason is discarded rather than clamped.
|
|
558
|
+
|
|
559
|
+
## The sources/ artifact (ROADMAP_v2 §45, SQ8)
|
|
560
|
+
|
|
561
|
+
### `persist_source_text`
|
|
562
|
+
|
|
563
|
+
Whether output/<run_id>/sources/ keeps the TEXT each cited page served,
|
|
564
|
+
or only its hash, size and provenance.
|
|
565
|
+
|
|
566
|
+
On by default, because it is what makes a similarity score reproducible
|
|
567
|
+
after the run -- and the directory output_writer has created since §12
|
|
568
|
+
was described by fetch_url.py's own comment for just as long. Everything
|
|
569
|
+
written there has been through redact_output_text on entry to the
|
|
570
|
+
corpus.
|
|
571
|
+
|
|
572
|
+
ROADMAP_v3 §52 (RB1) is what makes that sentence true again for a paged
|
|
573
|
+
document, and it was measured false first. §51 cut a page out of the
|
|
574
|
+
body before the redactor saw it, so a credential straddling character
|
|
575
|
+
5,000 matched nothing in either page and PG7's append rejoined it here
|
|
576
|
+
-- reproduced end to end into artifact_entries(), which is exactly what
|
|
577
|
+
this directory is written from. fetch_url redacts the whole body before
|
|
578
|
+
it cuts now, so the halves never exist.
|
|
579
|
+
|
|
580
|
+
It is new data at rest, so it has a switch and PRIVACY.md says what it
|
|
581
|
+
holds. Turning it off costs the audit trail, not the scores: the corpus
|
|
582
|
+
still exists in memory for the run that computes them.
|
|
583
|
+
|
|
584
|
+
## Scholarly authority: OpenAlex (ROADMAP_v2 §45, SQ5/SQ9)
|
|
585
|
+
|
|
586
|
+
### `scholar_lookup`
|
|
587
|
+
|
|
588
|
+
OFF BY DEFAULT. This is the first network call in this harness made by
|
|
589
|
+
something that is not a registered tool, so it bypasses the approval
|
|
590
|
+
registry and granted_calls.json -- and an out-of-the-box run must make
|
|
591
|
+
no call the user did not ask for. With it off, a paper takes its
|
|
592
|
+
preprint-server or publisher domain class and nothing else.
|
|
593
|
+
|
|
594
|
+
### `scholar_api_url`
|
|
595
|
+
|
|
596
|
+
### `scholar_timeout_s`
|
|
597
|
+
|
|
598
|
+
### `scholar_max_retries`
|
|
599
|
+
|
|
600
|
+
### `scholar_cache_ttl_s`
|
|
601
|
+
|
|
602
|
+
### `scholar_mailto`
|
|
603
|
+
|
|
604
|
+
OpenAlex asks for a contact address to put a caller in its "polite pool"
|
|
605
|
+
(higher rate limits). EMPTY BY DEFAULT AND NEVER DERIVED: an address is
|
|
606
|
+
personal data, and sending one the user did not type -- from a git
|
|
607
|
+
config, an environment variable, anywhere -- is not a rate-limit
|
|
608
|
+
optimisation, it is an unasked-for disclosure.
|
|
609
|
+
|
|
610
|
+
### `scholar_venue_weight`
|
|
611
|
+
|
|
612
|
+
How a paper's score is composed. Renormalised over whichever terms are
|
|
613
|
+
actually available, so a paper too young to have a citation percentile
|
|
614
|
+
is not scored as though it had a bad one.
|
|
615
|
+
|
|
616
|
+
### `scholar_citation_weight`
|
|
617
|
+
|
|
618
|
+
### `scholar_author_weight`
|
|
619
|
+
|
|
620
|
+
### `scholar_venue_credit`
|
|
621
|
+
|
|
622
|
+
Venue credit. A preprint scores lower than a comparable published paper
|
|
623
|
+
-- generally, not strictly, which is why it is a weight and not a gate.
|
|
624
|
+
|
|
625
|
+
**Notes on individual entries.**
|
|
626
|
+
|
|
627
|
+
arXiv, bioRxiv, institutional repositories
|
|
628
|
+
|
|
629
|
+
### `scholar_h_saturation`
|
|
630
|
+
|
|
631
|
+
max h-index across a paper's authors, log-saturated. 60 is a full career
|
|
632
|
+
at the top of most fields; the curve is deliberately flat above it,
|
|
633
|
+
because the difference between 60 and 90 says more about field size and
|
|
634
|
+
career length than about this paper.
|
|
635
|
+
|
|
636
|
+
### `scholar_min_cohort_size`
|
|
637
|
+
|
|
638
|
+
Below this many works, a field-and-year cohort is too small for a
|
|
639
|
+
percentile to mean anything and the window widens instead.
|
|
640
|
+
|
|
641
|
+
### `scholar_min_citation_age_days`
|
|
642
|
+
|
|
643
|
+
Below this age, citation counts are noise: 72% of computer-science
|
|
644
|
+
preprints from 2024 have zero citations, so a three-week-old paper's
|
|
645
|
+
zero says nothing at all. The term is DROPPED and the remaining weights
|
|
646
|
+
renormalise, rather than being scored as low impact.
|
|
647
|
+
|
|
648
|
+
### `scholar_retracted_authority`
|
|
649
|
+
|
|
650
|
+
A retracted paper is not evidence, whatever its venue or citation count
|
|
651
|
+
-- and a heavily cited retraction is the most dangerous shape there is.
|
|
652
|
+
|
|
653
|
+
## Reasoning effort (ROADMAP_v2 §16; default changed batch 25, #139)
|
|
654
|
+
|
|
655
|
+
### `default_effort`
|
|
656
|
+
|
|
657
|
+
The default effort level requested when the user has not chosen one.
|
|
658
|
+
|
|
659
|
+
This shipped as None -- "send nothing", the one universally safe value,
|
|
660
|
+
because reasoning_effort is rejected by OpenAI-compatible NON-reasoning
|
|
661
|
+
models. Batch 25 changed it to "high" by owner decision: the pipeline
|
|
662
|
+
now consumes the setting (#139), so None meant the mode this project
|
|
663
|
+
exists for ran at the provider's own default forever, invisibly. The
|
|
664
|
+
risk the old note named is managed in MODEL_EFFORT_LEVELS rather than
|
|
665
|
+
by silence: known non-reasoning models are listed there with an EMPTY
|
|
666
|
+
level set, which effort_for() treats as authoritative and drops the
|
|
667
|
+
level cleanly instead of sending a parameter that would 400.
|
|
668
|
+
|
|
669
|
+
### `model_effort_levels`
|
|
670
|
+
|
|
671
|
+
Fallback effort levels for providers whose APIs expose no capability
|
|
672
|
+
endpoint (every OpenAI-compatible provider, and Google). ANTHROPIC is NOT
|
|
673
|
+
listed here on purpose: its Models API reports per-model effort support,
|
|
674
|
+
so client.py queries it and new Anthropic models need no entry.
|
|
675
|
+
|
|
676
|
+
An entry whose value is an EMPTY list means "this model takes no effort
|
|
677
|
+
parameter at all" and is authoritative: effort_for() DROPS the requested
|
|
678
|
+
level with a naming warning instead of sending it. That is the safety
|
|
679
|
+
mechanism behind DEFAULT_EFFORT="high" -- without these entries, the
|
|
680
|
+
fallback for an unknown model ASSUMES ["low","medium","high"] and the
|
|
681
|
+
default high would reach gpt-4o-class endpoints as a 400 on every call.
|
|
682
|
+
Incomplete on purpose (same posture as MODELS_REJECTING_SAMPLING_PARAMS):
|
|
683
|
+
an unlisted non-reasoning endpoint still fails loud, and the fix is one
|
|
684
|
+
line here or `--effort auto`.
|
|
685
|
+
|
|
686
|
+
### `default_effort_levels`
|
|
687
|
+
|
|
688
|
+
### `google_thinking_budgets`
|
|
689
|
+
|
|
690
|
+
Google expresses reasoning depth as an integer token budget rather than an
|
|
691
|
+
enum, so a level has to be mapped to a number at the boundary. -1 is the
|
|
692
|
+
SDK's "decide dynamically" sentinel.
|
|
693
|
+
|
|
694
|
+
Live since batch 172 (ROADMAP_v3 §82). Until then this map was never sent:
|
|
695
|
+
the google-genai pin, 1.0.0, had no `thinking_budget`, so Google reported
|
|
696
|
+
no levels. The pin has it since 2.29.0 (2.32.0 since batch 234). Measured on Gemini 3: every budget here,
|
|
697
|
+
and 0, was accepted by gemini-3.1-flash-lite. Gemini 3's native control
|
|
698
|
+
is `thinking_level`; this map sends budgets, which it still takes. A Gemini
|
|
699
|
+
model with no `model_effort_levels` entry gets `default_effort_levels` and a
|
|
700
|
+
WARNING, like any other unlisted model.
|
|
701
|
+
|
|
702
|
+
## Database
|
|
703
|
+
|
|
704
|
+
### `db_path`
|
|
705
|
+
|
|
706
|
+
Must not be empty (#213). An empty path was accepted until then and
|
|
707
|
+
opened SQLite's anonymous temporary database, so every thread and memory
|
|
708
|
+
vanished at exit without a word.
|
|
709
|
+
|
|
710
|
+
## Output artifacts
|
|
711
|
+
|
|
712
|
+
### `output_dir`
|
|
713
|
+
|
|
714
|
+
BESIDE THE WORK, which since batch 44 means beside the WORKSPACE when one
|
|
715
|
+
was named. "State is global, artifacts are local" is the distribution
|
|
716
|
+
split, and the local half is only true if "local" tracks where the work
|
|
717
|
+
is: with AGENT_WORKSPACE pointing at a project, a run launched from the
|
|
718
|
+
harness checkout wrote its reports into the harness. Reading the env var
|
|
719
|
+
rather than WORKSPACE_DIR below, and defaulting it to ".", so this stays
|
|
720
|
+
one expression with no branch in it -- an unset AGENT_WORKSPACE gives
|
|
721
|
+
./output exactly as before, not ./workspace/output.
|
|
722
|
+
|
|
723
|
+
## File-ops workspace (ROADMAP §6)
|
|
724
|
+
|
|
725
|
+
### `workspace_dir`
|
|
726
|
+
|
|
727
|
+
An empty one is refused by name at startup, by
|
|
728
|
+
`protected_paths.check_workspace`, which answers both routes to it -- this
|
|
729
|
+
key and an empty `AGENT_WORKSPACE`. The schema deliberately does not
|
|
730
|
+
refuse it too (#213): it would answer the variable's case first, as an
|
|
731
|
+
error about this file.
|
|
732
|
+
|
|
733
|
+
### `workspace_is_project`
|
|
734
|
+
|
|
735
|
+
Whether the workspace above is also the PROJECT (batch 111,
|
|
736
|
+
TECHNICAL_DEBT 28). Shipped `false`.
|
|
737
|
+
|
|
738
|
+
THE SECOND OF TWO ROUTES TO ONE ANSWER, and it exists because the first
|
|
739
|
+
one is an environment variable. `AGENT_WORKSPACE` has decided this since
|
|
740
|
+
batch 44, by its presence; someone configuring the harness through
|
|
741
|
+
`config.yaml` alone had no way to say it. What they got instead was the
|
|
742
|
+
workspace they asked for and a project of `os.getcwd()` -- and, launched
|
|
743
|
+
from the install tree, a refusal telling them to set a variable in the
|
|
744
|
+
same breath as the file where they had just named the directory they
|
|
745
|
+
meant. The refusal's own last paragraph used to say so.
|
|
746
|
+
|
|
747
|
+
THE TWO OPTIONS THE DEBT ENTRY OFFERED WERE BOTH WORSE, and the second
|
|
748
|
+
for a reason the entry did not have. "Any value in the file counts" is
|
|
749
|
+
always true, because the shipped file writes `workspace_dir: ./workspace`
|
|
750
|
+
out in full -- so it moves the project for every install nobody has
|
|
751
|
+
edited. "Differs from the shipped default" needs a shipped default to
|
|
752
|
+
compare against, and `HarnessConfig` has none: every field is required
|
|
753
|
+
and comes from the file, by design, so the comparison would need either
|
|
754
|
+
the first schema default in the codebase or a second hand-written copy
|
|
755
|
+
of `"./workspace"` -- the exact staleness `shipped_defaults()` exists to
|
|
756
|
+
prevent. It also quietly makes `./workspace` un-nameable.
|
|
757
|
+
|
|
758
|
+
NOT AN AUTHORITY KEY, deliberately. An authority key is one no
|
|
759
|
+
unattended surface reaches, and `ENV_OVERRIDES` and
|
|
760
|
+
`HARNESS_AUTHORITY_KEYS` are disjoint for that reason
|
|
761
|
+
(`test_no_authority_key_has_an_environment_override`). `AGENT_WORKSPACE`
|
|
762
|
+
already produces this exact effect through an ordinary override, so
|
|
763
|
+
gating the file key would put the confirmation on the louder of the two
|
|
764
|
+
routes and leave the quieter one open. It is also strictly less
|
|
765
|
+
dangerous than `workspace_dir` itself, which is ungated and carries the
|
|
766
|
+
sharper hazard named above it.
|
|
767
|
+
|
|
768
|
+
### `workspace_dir_explicit`
|
|
769
|
+
|
|
770
|
+
Whether the workspace was NAMED as the project, as opposed to defaulted
|
|
771
|
+
(batch 44; a second input added in batch 111).
|
|
772
|
+
|
|
773
|
+
`cfg.workspace_is_project or "AGENT_WORKSPACE" in os.environ`. The
|
|
774
|
+
variable half is its PRESENCE, never its value: the default
|
|
775
|
+
"./workspace" is a subdirectory of wherever you launched, so a value
|
|
776
|
+
test would make `./workspace` the project for everyone who never set
|
|
777
|
+
anything -- which is the whole population this must not disturb. main()
|
|
778
|
+
reads this to decide the project path; the decision is there, because
|
|
779
|
+
the config layer holds plain values and this is one.
|
|
780
|
+
|
|
781
|
+
OR, with no precedence between the halves. Both say the same thing about
|
|
782
|
+
the same directory, so there is no conflict to resolve, and inventing a
|
|
783
|
+
winner would mean a user who did both getting less than a user who did
|
|
784
|
+
either. main() never learns there are two routes -- that is the point of
|
|
785
|
+
computing the OR here.
|
|
786
|
+
|
|
787
|
+
Batch 107 made the UNNAMED branch a refusal rather than a silent
|
|
788
|
+
fallback: with nothing naming a workspace the project is os.getcwd(), and
|
|
789
|
+
protected_paths.check_project() refuses that when it is the harness's own
|
|
790
|
+
install tree. Naming the harness had always been refused by
|
|
791
|
+
check_workspace; the implicit route reached the same state by saying
|
|
792
|
+
nothing. Batch 111 closed what that left open (TECHNICAL_DEBT 28) and the
|
|
793
|
+
refusal now offers three ways out rather than two and a dead end.
|
|
794
|
+
|
|
795
|
+
Note that this value has NO `config.yaml` key of its own -- it is computed
|
|
796
|
+
in `config_schema.derived_values(cfg)`, because half of it is a question
|
|
797
|
+
about the environment that YAML cannot ask. `workspace_is_project` is an
|
|
798
|
+
input to it, not a key for it. There is nothing here to edit.
|
|
799
|
+
|
|
800
|
+
### `max_file_size_bytes`
|
|
801
|
+
|
|
802
|
+
25 MB — hard reject before opening
|
|
803
|
+
|
|
804
|
+
### `max_read_lines`
|
|
805
|
+
|
|
806
|
+
max lines per read call
|
|
807
|
+
|
|
808
|
+
### `max_read_chars`
|
|
809
|
+
|
|
810
|
+
max chars per read call
|
|
811
|
+
|
|
812
|
+
It is also the bound on an MCP tool's whole result (ROADMAP_v3 §84, A79,
|
|
813
|
+
batch 225). The server's text is cut at it with a note giving the size it
|
|
814
|
+
had, a structured payload is kept whole if it fits in what the text left
|
|
815
|
+
and dropped with a note if not, and a word the cut splits goes too, so the
|
|
816
|
+
redactor never sees half a credential. One key and not a second one,
|
|
817
|
+
because the compaction headroom check (`compaction_min_headroom_tokens`,
|
|
818
|
+
below) measures one read against this number, and an MCP result is a read
|
|
819
|
+
for that purpose.
|
|
820
|
+
|
|
821
|
+
### `max_image_bytes`
|
|
822
|
+
|
|
823
|
+
ROADMAP_v3 §81 (IM7). The largest image file `view_image` will attach:
|
|
824
|
+
3,932,160 bytes, which is 3.75 MiB.
|
|
825
|
+
|
|
826
|
+
The number is derived, not chosen. An image travels as base64, which is 4/3
|
|
827
|
+
the size of the file, so 3.75 MiB of file is 5 MiB on the wire. 5 MiB is
|
|
828
|
+
Anthropic's per-image limit, the smallest of the wires §81 delivers to;
|
|
829
|
+
OpenAI's is larger, and Google's limit (a wire since batch 173) is on the whole
|
|
830
|
+
request rather than per image. A cap at 5 MiB of FILE would put a 6.7 MiB payload
|
|
831
|
+
on the wire, and Anthropic would reject it with a 400 that names neither the
|
|
832
|
+
file nor this key.
|
|
833
|
+
|
|
834
|
+
It is also a cost bound, separate from `max_file_size_bytes` (25 MB). That
|
|
835
|
+
key limits what a tool may operate on; this one limits what is resent with
|
|
836
|
+
every request for as long as the image stays in the conversation's view.
|
|
837
|
+
Raising it toward the 25 MB general limit would not be consistent, it would
|
|
838
|
+
break: the provider would reject the request.
|
|
839
|
+
|
|
840
|
+
## /init (ROADMAP_v2 §24)
|
|
841
|
+
|
|
842
|
+
### `initializer_agent`
|
|
843
|
+
|
|
844
|
+
### `init_read_chars`
|
|
845
|
+
|
|
846
|
+
Three bounds, each doing a different job (I7). /init is a tool-heavy loop
|
|
847
|
+
over documentation that can run to hundreds of kilobytes -- this repo's own
|
|
848
|
+
root markdown is 721KB, with DEVLOG.md alone at 226KB.
|
|
849
|
+
|
|
850
|
+
INIT_READ_CHARS is well below MAX_READ_CHARS because of TECHNICAL_DEBT
|
|
851
|
+
item 9 (now closed, batch 27): the billing meter re-counts the WHOLE
|
|
852
|
+
prompt on every step, so each 50KB read is re-billed for every step that
|
|
853
|
+
follows it. 20KB keeps a dozen reads affordable and still returns a
|
|
854
|
+
useful span of a document per call. It stays even though the meter no
|
|
855
|
+
longer caps anything by default -- it bounds per-read VOLUME, which is a
|
|
856
|
+
different axis from spend and from the number of reads.
|
|
857
|
+
|
|
858
|
+
### `init_max_steps`
|
|
859
|
+
|
|
860
|
+
The number of reads, which neither budget nor read size bounds: a model
|
|
861
|
+
can spend an unbounded number of small reads inside any ceiling.
|
|
862
|
+
|
|
863
|
+
### `init_max_hub_chars`
|
|
864
|
+
|
|
865
|
+
Batch 221 (#226, TECHNICAL_DEBT 72). The existing hub was the one read on
|
|
866
|
+
/init's path with no bound at all: measured, a 5.4 MB `AGENTS.md` became a
|
|
867
|
+
5.4 MB model task and a 5.4 MB diff in the transcript. A cap with a notice
|
|
868
|
+
("the first N characters are shown") was rejected, because the initializer's
|
|
869
|
+
reply REPLACES the whole file -- a model shown the head would write the hub
|
|
870
|
+
back without its tail. So past this size /init stops before any model call
|
|
871
|
+
and says to trim the file or edit it by hand. 1,000,000 characters is about
|
|
872
|
+
three times this repository's own 347 KB hub and past what most model
|
|
873
|
+
windows hold anyway, so an ordinary hand-grown hub never meets it. The owner
|
|
874
|
+
chose the shape and the number.
|
|
875
|
+
|
|
876
|
+
### `init_diff_shown_lines`
|
|
877
|
+
|
|
878
|
+
The other half of #226: below the cap a hub can still produce a diff of
|
|
879
|
+
tens of thousands of lines, and printing it whole is the transcript freeze
|
|
880
|
+
S15 removed. Only the PRINT is cut, with a line saying how many lines were
|
|
881
|
+
not shown; the whole diff still decides whether anything changed, and the
|
|
882
|
+
write is still the whole proposal. 2,000 lines is enough to judge a rewrite
|
|
883
|
+
by -- this repository's own hub is about 3,300 lines.
|
|
884
|
+
|
|
885
|
+
## MCP teardown (ROADMAP_v2 §37 F6, #64)
|
|
886
|
+
|
|
887
|
+
### `teardown_budget_s`
|
|
888
|
+
|
|
889
|
+
ONE shared wall-clock budget for the whole goodbye -- polite close,
|
|
890
|
+
force-cancel, loop-thread join -- replacing three sequential 15-second
|
|
891
|
+
waits whose worst case hung a quitting harness for ~45s, Ctrl+C
|
|
892
|
+
included. Servers still alive when the budget expires are named in a
|
|
893
|
+
WARNING; their child processes may outlive this session. The value
|
|
894
|
+
lives with the other harness bounds and is re-exported by
|
|
895
|
+
mcp_client/client.py beside its sibling timeouts.
|
|
896
|
+
|
|
897
|
+
## MCP results
|
|
898
|
+
|
|
899
|
+
### `mcp_max_event_bytes`
|
|
900
|
+
|
|
901
|
+
16 MiB (16,777,216), the owner's number (batch 208). mcp 2.3.0 reads
|
|
902
|
+
each Streamable HTTP server-sent event whole and fails the call when one
|
|
903
|
+
exceeds `max_sse_event_size`; 2.2.0, on the httpx2 it installed, had no
|
|
904
|
+
limit at all. A result a server STREAMS is one event, so for those this is
|
|
905
|
+
the memory one result can take before the harness sees it -- a bound on
|
|
906
|
+
the transport, NOT on what reaches the model. That one is `max_read_chars`,
|
|
907
|
+
applied to the whole result since batch 225 (A79).
|
|
908
|
+
|
|
909
|
+
WHICH RESULTS IT COVERS, measured rather than read (batch 208). A server
|
|
910
|
+
may answer a request as SSE or as plain JSON. mcp 2.3.0's own server,
|
|
911
|
+
negotiating 2026-07-28, answered every request as `application/json`, and
|
|
912
|
+
the client reads that body whole with no limit: 4 MB and 40 MB results
|
|
913
|
+
both arrived, at this ceiling and at 1 MiB. So this key bounds streamed
|
|
914
|
+
answers only. Through `mcp_client` against a server streaming every answer
|
|
915
|
+
(an in-process mock on 2025-06-18): a 2 MB result passed at 16 MiB and
|
|
916
|
+
failed at 1 MiB with "MCP call failed: SSE stream failed: Server-sent event
|
|
917
|
+
exceeded the 1048576 byte limit."; 16,000,000 characters passed at 16 MiB
|
|
918
|
+
and 20,000,000 failed naming 16777216.
|
|
919
|
+
|
|
920
|
+
Why not the SDK's 1 MiB: a screenshot is 0.2-3 MB, base64 adds a third,
|
|
921
|
+
and a tool that returns one would fail outright, text included -- this
|
|
922
|
+
harness replaces an MCP image with a note and keeps the text, but only if
|
|
923
|
+
the event arrives. 16 MiB fits an image at Claude's 5 MB per-image limit
|
|
924
|
+
(~6.7 MB encoded) with headroom while a broken or hostile server still
|
|
925
|
+
costs a bounded amount per event. Uploads are unaffected: this bounds what
|
|
926
|
+
a server sends back.
|
|
927
|
+
|
|
928
|
+
Read per connection by `mcp_client/client.py`, which passes it on BOTH
|
|
929
|
+
Streamable HTTP branches, because a bare URL takes the SDK's default. The
|
|
930
|
+
legacy "sse" transport keeps the SDK's fixed 1 MiB: `sse_client` takes no
|
|
931
|
+
size. An ordinary key rather than harness authority, like
|
|
932
|
+
`max_read_chars`: it is a resource bound, not a permission.
|
|
933
|
+
|
|
934
|
+
## Shell / sandbox (ROADMAP §7)
|
|
935
|
+
|
|
936
|
+
### `shell_binary`
|
|
937
|
+
|
|
938
|
+
auto-detect if empty
|
|
939
|
+
|
|
940
|
+
### `allow_insecure_sandbox_fallback`
|
|
941
|
+
|
|
942
|
+
explicitly enable subprocess fallback
|
|
943
|
+
|
|
944
|
+
### `auto_approve_sandbox_fallback`
|
|
945
|
+
|
|
946
|
+
auto-approve fallback runs (no per-run prompt)
|
|
947
|
+
|
|
948
|
+
### `allow_wsl_backend`
|
|
949
|
+
|
|
950
|
+
ROADMAP_v3 §49, slice 3 (SS35). Whether the agent may ask for a command
|
|
951
|
+
to run in a WSL distribution instead of the container. Ships `false`, and
|
|
952
|
+
is part of the frozen posture -- so no tool call, `settings.json` at
|
|
953
|
+
either tier, environment variable or slash command can move it.
|
|
954
|
+
|
|
955
|
+
It is off by default because WSL is not a weaker container, it is no
|
|
956
|
+
container at all. Measured on the machine this was built on:
|
|
957
|
+
|
|
958
|
+
```text
|
|
959
|
+
the harness's own config.yaml writable from the distribution
|
|
960
|
+
~/.config (and .config/venastine) writable
|
|
961
|
+
memory / CPU / process limits none -- they belong to the WSL VM
|
|
962
|
+
network always on, not withholdable
|
|
963
|
+
Windows interop survives `env -i`; it is binfmt_misc,
|
|
964
|
+
not PATH, so a command there can run
|
|
965
|
+
cmd.exe with the user's authority
|
|
966
|
+
```
|
|
967
|
+
|
|
968
|
+
So the harness treats it as UNCONTAINED for every tier (SS1): under
|
|
969
|
+
`tiered` and `contained` only a read-only command whose every argument is
|
|
970
|
+
inside the workspace runs unasked, and a command naming a protected path
|
|
971
|
+
segment is REFUSED rather than asked about (SS40) -- because the
|
|
972
|
+
read-only bind over `.venastine/` that makes "ask" tolerable on the
|
|
973
|
+
container route does not exist here, and a write would succeed and be
|
|
974
|
+
noticed only at the next launch.
|
|
975
|
+
|
|
976
|
+
Two questions, two owners, which is why this is a config key and the
|
|
977
|
+
backend choice is a tool parameter: whether this machine may run agent
|
|
978
|
+
commands outside a container is the user's decision, and which command
|
|
979
|
+
needs a Linux userland is the agent's. A process-wide switch would answer
|
|
980
|
+
both at once and give up the container for every command in order to
|
|
981
|
+
serve one.
|
|
982
|
+
|
|
983
|
+
### `wsl_distro`
|
|
984
|
+
|
|
985
|
+
Which distribution the backend runs in. Empty means the first name
|
|
986
|
+
`wsl.exe -l -q` lists, which is WSL's own default.
|
|
987
|
+
|
|
988
|
+
Never settable by the agent (SS36): a distribution is a fact about the
|
|
989
|
+
machine rather than about a command, and the list on a typical developer
|
|
990
|
+
box includes `docker-desktop`, which is Docker's own internal
|
|
991
|
+
distribution and not a place to run anything. A configured name is
|
|
992
|
+
matched case-insensitively against the installed list and refused with
|
|
993
|
+
that list if it is absent -- rather than passed through, because
|
|
994
|
+
`wsl.exe -d NoSuchDistro` exits `4294967295` and writes its complaint to
|
|
995
|
+
*stdout* in UTF-16, so an unvalidated name fails in a way that reads as
|
|
996
|
+
the command failing rather than the configuration being wrong.
|
|
997
|
+
|
|
998
|
+
The listing itself is decoded as UTF-16LE for the same measured reason:
|
|
999
|
+
read as UTF-8 it is a NUL-riddled string that matches no name at all, so
|
|
1000
|
+
a probe that guessed the encoding would report "no distribution
|
|
1001
|
+
installed" on a machine with three.
|
|
1002
|
+
|
|
1003
|
+
### `allow_ssh_backend`
|
|
1004
|
+
|
|
1005
|
+
ROADMAP_v3 §49, slice 4 (SS46). Whether the agent may ask for a command to
|
|
1006
|
+
run on the one remote host configured below, instead of the container.
|
|
1007
|
+
Ships `false`, and is part of the frozen posture -- so no tool call,
|
|
1008
|
+
`settings.json` at either tier, environment variable or slash command can
|
|
1009
|
+
move it.
|
|
1010
|
+
|
|
1011
|
+
It is off by default because a remote host is not a weaker sandbox; it is
|
|
1012
|
+
a machine this harness cannot look at:
|
|
1013
|
+
|
|
1014
|
+
```text
|
|
1015
|
+
isolation none
|
|
1016
|
+
memory / CPU / process limits none -- they belong to the remote
|
|
1017
|
+
network the remote's, always on
|
|
1018
|
+
what this harness can inspect nothing: no path, no file, no mount
|
|
1019
|
+
credentials yours, not ones this harness issued
|
|
1020
|
+
```
|
|
1021
|
+
|
|
1022
|
+
**NOTHING runs there without asking you (SS48)** -- the one rule that
|
|
1023
|
+
makes this backend different from the other three. Every other backend
|
|
1024
|
+
runs a read-only in-workspace command unasked; this one asks about `ls`.
|
|
1025
|
+
The reason is not caution: the check that decides whether a command's
|
|
1026
|
+
arguments stay inside the workspace resolves them against the LOCAL
|
|
1027
|
+
filesystem, so on a remote it is answering a true question about the wrong
|
|
1028
|
+
machine. Slice 3 (SS45) is the evidence for what such a check is worth --
|
|
1029
|
+
it did not fail loudly, it approved confidently. A second reason stands on
|
|
1030
|
+
its own: `ssh` has no `execve` path, so the shell-free argv that the
|
|
1031
|
+
auto-approved tier is defined by does not exist on this route at all.
|
|
1032
|
+
|
|
1033
|
+
`never` still means never, because SS1 already said so and this slice
|
|
1034
|
+
widened no mode.
|
|
1035
|
+
|
|
1036
|
+
### `ssh_host`, `ssh_user`, `ssh_port`
|
|
1037
|
+
|
|
1038
|
+
The one host the backend reaches. The agent says `backend: "ssh"` and gets
|
|
1039
|
+
THIS host; it never names one. SS35's split, unchanged: which machine this
|
|
1040
|
+
harness may reach is the user's question, which command needs it is the
|
|
1041
|
+
agent's. A named map of hosts is a later addition that this shape does not
|
|
1042
|
+
block.
|
|
1043
|
+
|
|
1044
|
+
`ssh_port` is a whole number from 1 to 65535 (#213). It was a lax `int`
|
|
1045
|
+
until then, so `true` was read as port 1 and `99999` reached the SSH call
|
|
1046
|
+
before anything said no.
|
|
1047
|
+
|
|
1048
|
+
### `ssh_identity_file`
|
|
1049
|
+
|
|
1050
|
+
The private key to authenticate with. Empty offers whatever a running
|
|
1051
|
+
`ssh-agent` holds.
|
|
1052
|
+
|
|
1053
|
+
**This harness never asks for, holds or stores a passphrase or a password
|
|
1054
|
+
(SS47).** If the key is encrypted, load it into an agent with `ssh-add`
|
|
1055
|
+
first; the connection is made with `BatchMode=yes` and
|
|
1056
|
+
`PreferredAuthentications=publickey`, so `ssh` can never prompt. That flag
|
|
1057
|
+
is load-bearing rather than tidy -- measured, without it an encrypted key
|
|
1058
|
+
with no agent waits twenty seconds and is still waiting, trying to prompt
|
|
1059
|
+
on a terminal this process does not own. With it the same call fails in
|
|
1060
|
+
0.12 s and the refusal says `ssh-add`.
|
|
1061
|
+
|
|
1062
|
+
`IdentitiesOnly=yes` is passed only WHEN a key is configured: with no key
|
|
1063
|
+
it would rule out the agent, which is the one way to use an encrypted key
|
|
1064
|
+
without this harness ever seeing the passphrase.
|
|
1065
|
+
|
|
1066
|
+
### `ssh_remote_workspace`
|
|
1067
|
+
|
|
1068
|
+
Where a command runs on the remote. **Required** when the backend is on,
|
|
1069
|
+
and deliberately not defaulted to the login home (SS52): a command that
|
|
1070
|
+
runs somewhere nobody named is the failure this backend is most able to
|
|
1071
|
+
cause, and nothing here can see where it landed afterwards. `ssh` has no
|
|
1072
|
+
`--cd`, so the command is prefixed with `cd -- <dir> ||` and a failure is
|
|
1073
|
+
recognised by BOTH a chosen exit code and a marker on stderr -- either
|
|
1074
|
+
alone is guessable, since 125 is inside `timeout`'s own vocabulary and a
|
|
1075
|
+
marker is a string any command may print.
|
|
1076
|
+
|
|
1077
|
+
Note the trap this key names: `write` saves files LOCALLY while the shell
|
|
1078
|
+
runs remotely, so a file the agent just wrote is not in this directory.
|
|
1079
|
+
|
|
1080
|
+
### `ssh_host_key`
|
|
1081
|
+
|
|
1082
|
+
The remote's host key, PINNED. Run `ssh-keyscan -p <port> <host>` and
|
|
1083
|
+
paste its output; the `#` banner line it prints above the key is ignored,
|
|
1084
|
+
so pasting the whole thing works. The harness writes it to a file it owns
|
|
1085
|
+
and passes `UserKnownHostsFile` with `StrictHostKeyChecking=yes`, never
|
|
1086
|
+
touching `~/.ssh/known_hosts` -- its trust set is exactly what you pinned.
|
|
1087
|
+
|
|
1088
|
+
A key that does not match, or no key at all, REFUSES (SS49). There is no
|
|
1089
|
+
trust-on-first-use prompt, for two reasons: a first-use question cannot be
|
|
1090
|
+
answered in a headless run, and the case actually worth refusing is a key
|
|
1091
|
+
that CHANGES, which a prompt teaches people to click through.
|
|
1092
|
+
|
|
1093
|
+
The fingerprint is not configured -- it is a hash, and `known_hosts` needs
|
|
1094
|
+
the key. It is DERIVED and shown, so you can verify it out of band once.
|
|
1095
|
+
|
|
1096
|
+
### `ssh_binary`
|
|
1097
|
+
|
|
1098
|
+
Which `ssh` program to run. Empty prefers the operating system's own
|
|
1099
|
+
(`%SYSTEMROOT%\System32\OpenSSH\ssh.exe` on Windows) and falls back to
|
|
1100
|
+
`PATH`.
|
|
1101
|
+
|
|
1102
|
+
Not `PATH` first, and that is measured rather than defensive: on the
|
|
1103
|
+
machine this was built, `PATH` resolves to a git-for-Windows MSYS2 build
|
|
1104
|
+
while Windows ships its own, and the two are NOT interchangeable. They
|
|
1105
|
+
agree on every happy path and disagree on FAILURES -- a refused connection
|
|
1106
|
+
is `ssh: connect to host ... Connection refused` from one and `banner
|
|
1107
|
+
exchange: Connection to UNKNOWN port -1: Connection refused` from the
|
|
1108
|
+
other -- and a failure message is the half a refusal is built out of. It
|
|
1109
|
+
is SS38's GnuWin32 `cat` on a third route.
|
|
1110
|
+
|
|
1111
|
+
### `shell_approval_mode`
|
|
1112
|
+
|
|
1113
|
+
ROADMAP_v2 §28 (G3). WHICH shell commands need a human to say yes.
|
|
1114
|
+
|
|
1115
|
+
```text
|
|
1116
|
+
"always" every command is asked about, whatever it does.
|
|
1117
|
+
"tiered" the classifier decides -- see security/capability.py for
|
|
1118
|
+
the one rule, and security/sandbox.py:classify_command for
|
|
1119
|
+
how a command is measured against it. Since §48 (CE1) only
|
|
1120
|
+
a read-only INERT command runs unasked: anything that may
|
|
1121
|
+
run code asks, contained or not.
|
|
1122
|
+
"contained" §48 (CE2): the rule "tiered" had before §48. A command the
|
|
1123
|
+
container confines runs unasked unless it gets network,
|
|
1124
|
+
code included; reads outside the workspace and network
|
|
1125
|
+
commands still ask.
|
|
1126
|
+
"never" nothing is ever asked about.
|
|
1127
|
+
```
|
|
1128
|
+
|
|
1129
|
+
`auto_approve_sandbox_fallback` is honoured under "tiered" and
|
|
1130
|
+
"contained" (§48, CE5) -- the one written exception to "code asks" under
|
|
1131
|
+
"tiered" -- and never under "always", whose check returns before the
|
|
1132
|
+
opt-in is read (CE6).
|
|
1133
|
+
|
|
1134
|
+
There is no list of interpreters behind "tiered", deliberately. `python
|
|
1135
|
+
-c` is the obvious case, but `pytest` runs a conftest.py, `make` runs a
|
|
1136
|
+
Makefile, and `"python"`, `python3.13` and `echo x | python` are the same
|
|
1137
|
+
call to a shell -- a list would be a parser whose misses auto-approve
|
|
1138
|
+
(G2). Every command that is not INERT may run code, and that is the
|
|
1139
|
+
answer the classifier gives.
|
|
1140
|
+
|
|
1141
|
+
This is the gate. Before §28 the gate was ToolApprovals.shell, and
|
|
1142
|
+
`_shell_approval_check` looked like a five-layer policy underneath it --
|
|
1143
|
+
but four of those layers could only ever return False on the shipped
|
|
1144
|
+
flags, so the whole thing was a pass-through for one boolean and the
|
|
1145
|
+
harness had exactly two settings: ask about everything, or ask about
|
|
1146
|
+
nothing. "tiered" is the rung that docstring already claimed existed.
|
|
1147
|
+
|
|
1148
|
+
"never" is that second setting, preserved deliberately and now NAMED.
|
|
1149
|
+
It is the pre-§28 `ToolApprovals.shell = False` behaviour exactly: an
|
|
1150
|
+
inert command runs on the HOST with unrestricted arguments, so `cat
|
|
1151
|
+
~/.aws/credentials` returns your keys to the model. You reach that by
|
|
1152
|
+
writing "never", not by switching off a field that reads like "stop
|
|
1153
|
+
nagging me" -- which is the actual fix for audit #157.
|
|
1154
|
+
The legal set lives with the code that ENFORCES it --
|
|
1155
|
+
security/capability.APPROVAL_MODES, which validate_mode() reads. A second
|
|
1156
|
+
copy here was read by nothing but a test asserting its literal, so the two
|
|
1157
|
+
could have disagreed and only the unenforced one would have been wrong.
|
|
1158
|
+
|
|
1159
|
+
### `sandbox_docker_image`
|
|
1160
|
+
|
|
1161
|
+
The image both runtimes run: Docker, or Podman when Docker cannot run a
|
|
1162
|
+
container (ROADMAP_v3 §49, SS22). The key kept its name when Podman
|
|
1163
|
+
arrived, because config_update.py carries a user's own value across an
|
|
1164
|
+
npm update BY KEY, and a renamed key would silently drop it.
|
|
1165
|
+
|
|
1166
|
+
FULLY QUALIFIED since batch 93 (SS23), and the reason is Podman's: an
|
|
1167
|
+
unqualified name is resolved through `registries.conf`, and with no
|
|
1168
|
+
search registries and no short-name alias -- measured on a stock Ubuntu
|
|
1169
|
+
Podman, whose `shortnames.conf` happens to alias `python` -- a name it
|
|
1170
|
+
cannot resolve fails without a terminal to ask on. `docker.io/library/`
|
|
1171
|
+
is where Docker resolves the short name anyway. A value you set yourself
|
|
1172
|
+
is carried as written.
|
|
1173
|
+
|
|
1174
|
+
A TAG, NOT AN IDENTITY (ROADMAP_v2 §46, EP7): the resolved image ID is
|
|
1175
|
+
logged once per process, and two machines -- or two runtimes on one --
|
|
1176
|
+
pulling the same tag on different days get different images.
|
|
1177
|
+
|
|
1178
|
+
### `sandbox_timeout_seconds`
|
|
1179
|
+
|
|
1180
|
+
### `sandbox_memory_mb`
|
|
1181
|
+
|
|
1182
|
+
### `sandbox_cpu_seconds`
|
|
1183
|
+
|
|
1184
|
+
### `sandbox_max_pids`
|
|
1185
|
+
|
|
1186
|
+
### `shell_session_timeout_cap_s`
|
|
1187
|
+
|
|
1188
|
+
ROADMAP_v3 §49 (SS12, SS13). The longest a background or monitor session
|
|
1189
|
+
may run, whatever the agent asks for. 3600 because the owner's own example
|
|
1190
|
+
was an hour, and it is also the ceiling on how long a misbehaving agent can
|
|
1191
|
+
hold the input block (SS2) with one session.
|
|
1192
|
+
|
|
1193
|
+
A value above the cap is CLAMPED, not refused, and the started result says
|
|
1194
|
+
so. Refusing would make the agent guess numbers until one fits, and the cap
|
|
1195
|
+
is not a secret. The clamp happens in one place, the session manager, and
|
|
1196
|
+
is enforced twice: the harness kills at the timeout, and coreutils `timeout`
|
|
1197
|
+
inside the container ends it `SESSION_TIMEOUT_MARGIN_S` later if the harness
|
|
1198
|
+
is no longer there to.
|
|
1199
|
+
|
|
1200
|
+
### `shell_session_max_live`
|
|
1201
|
+
|
|
1202
|
+
ROADMAP_v3 §49 (SS12). Live background and monitor sessions, counted
|
|
1203
|
+
process-wide across the main agent and every subagent -- a subagent does not
|
|
1204
|
+
get a quota of its own, or three parallel children could each fill one. The
|
|
1205
|
+
classic one-shot `shell` is not counted: it holds no slot past its own call.
|
|
1206
|
+
|
|
1207
|
+
4, because each is a container under `sandbox_memory_mb` (2048), so the
|
|
1208
|
+
ceiling this implies is 8 GB of container memory. At the cap a start is
|
|
1209
|
+
refused with the list of live sessions, never queued: a queued session would
|
|
1210
|
+
start at a time nobody chose.
|
|
1211
|
+
|
|
1212
|
+
### `shell_session_max_consecutive_wakes`
|
|
1213
|
+
|
|
1214
|
+
ROADMAP_v3 §49 (SS2). How many wake turns may run in a row with no message
|
|
1215
|
+
from the user. Every wake is a model call nobody typed, and while sessions
|
|
1216
|
+
are live the prompt is blocked, so an agent that starts a new session on
|
|
1217
|
+
every wake would otherwise hold the session and spend tokens indefinitely.
|
|
1218
|
+
Past the limit, waking stops, the plain prompt unblocks, and the results are
|
|
1219
|
+
delivered with the user's next message; a user message resets the count.
|
|
1220
|
+
|
|
1221
|
+
10 is a ceiling on an unattended loop, not an estimate of a normal one. A
|
|
1222
|
+
subagent has no user to reset it, so it gets one final wake and returns
|
|
1223
|
+
(SS20).
|
|
1224
|
+
|
|
1225
|
+
### `shell_session_output_head_chars`
|
|
1226
|
+
|
|
1227
|
+
### `shell_session_output_tail_chars`
|
|
1228
|
+
|
|
1229
|
+
ROADMAP_v3 §49 (SS12). How much of a session's output is kept: the first
|
|
1230
|
+
10 000 characters and the most recent 190 000, IN MEMORY ONLY. Never on disk,
|
|
1231
|
+
because program output can hold secrets and redaction is pattern-based, so a
|
|
1232
|
+
file would be a durable copy of whatever the patterns miss. The dropped
|
|
1233
|
+
middle is reported as a gap when the agent pages through the output.
|
|
1234
|
+
|
|
1235
|
+
The head is what shows how a run STARTED -- the command's own banner, the
|
|
1236
|
+
first error of a cascade -- which a tail-only buffer loses on exactly the long
|
|
1237
|
+
runs sessions exist for. The split is uneven because the end of a run is what
|
|
1238
|
+
is usually asked about.
|
|
1239
|
+
|
|
1240
|
+
## Output redaction (#167/#49, batch 20)
|
|
1241
|
+
|
|
1242
|
+
### `redact_tool_outputs`
|
|
1243
|
+
|
|
1244
|
+
The PERMANENT master switch for pattern-based redaction of what leaves a
|
|
1245
|
+
tool: vendor token substitution and credential-shape redaction, applied
|
|
1246
|
+
by check_output_policy() to every tool result and by param_digest() to
|
|
1247
|
+
what the shells display of an argument. On by default; a user whose
|
|
1248
|
+
workflow needs the model to see real values (debugging their own
|
|
1249
|
+
credentials, say) turns it off here, or per-run with
|
|
1250
|
+
VENASTINE_REDACT_OFF in the environment -- see redaction_enabled().
|
|
1251
|
+
|
|
1252
|
+
DELIBERATELY NOT a settings.json key (decision recorded in DEVLOG,
|
|
1253
|
+
batch 20): project tier beats user tier there, so a cloned repo could
|
|
1254
|
+
ship `.venastine/settings.json` switching the scrubbing off behind a
|
|
1255
|
+
trust prompt nobody reads -- the exact shape G7 rejected
|
|
1256
|
+
shell_approval_mode for and R12 rejected research.granted_tools for.
|
|
1257
|
+
Permanent means editing this line.
|
|
1258
|
+
|
|
1259
|
+
NEVER covers three things, whatever this is set to: check_input_policy's
|
|
1260
|
+
refusals (a denial is legible, not destructive); check_output_policy's
|
|
1261
|
+
depth-cap substitution (fail-closed structure bound -- making it optional
|
|
1262
|
+
would recreate the deterministic bypass its comment forbids); and
|
|
1263
|
+
logging_setup.py's formatter redaction (the second sink keeps its own
|
|
1264
|
+
guard).
|
|
1265
|
+
|
|
1266
|
+
### `tool_compute_timeout_s`
|
|
1267
|
+
|
|
1268
|
+
ROADMAP_v2 §31 (H9). The wall clock on a BUDGET_COMPUTE tool call --
|
|
1269
|
+
the six math tools, which are pure functions of their params and have
|
|
1270
|
+
nothing bounding them from the inside. dispatch runs them in a
|
|
1271
|
+
killable subprocess under this budget (tools/isolation.py).
|
|
1272
|
+
|
|
1273
|
+
20s is chosen against measurement, not taste. The slowest LEGITIMATE
|
|
1274
|
+
call found is `symbolic_math series order=1000`, so the headroom is the
|
|
1275
|
+
ratio between that call and this number; the runaways it exists for do
|
|
1276
|
+
not return at all. Ten passes each burning a full budget is 200s rather
|
|
1277
|
+
than forever, which is the trade being made.
|
|
1278
|
+
|
|
1279
|
+
*(Re-measured in batch 143, and the value is again unchanged. That call
|
|
1280
|
+
is 9.92-10.19s warm on Windows / Python 3.13.13 / sympy 1.13.3 and
|
|
1281
|
+
11.14s through the real transport -- roughly 2x headroom, not the 6x this
|
|
1282
|
+
paragraph claimed from a 3.44s reading. The ratio is the thing that
|
|
1283
|
+
moved: a timing taken on another machine or another sympy is not a
|
|
1284
|
+
number to restate bare, which is why it is now named as a ratio and
|
|
1285
|
+
measured where it is quoted. The call itself is refused on SIZE from
|
|
1286
|
+
batch 143 anyway -- 1,185,090 characters against
|
|
1287
|
+
`config.MAX_READ_CHARS` -- so it is no longer the worst case this budget
|
|
1288
|
+
has to cover, and its output was never measured when it was chosen.)*
|
|
1289
|
+
|
|
1290
|
+
*(Corrected in batch 83. This paragraph was carried over saying 15s,
|
|
1291
|
+
roughly 4x and 150s -- all three consistent with a 15 the value has not
|
|
1292
|
+
been for some time. `README.md` said 15 in three more places against its
|
|
1293
|
+
own table's 20. The value is unchanged; the arithmetic now describes it.)*
|
|
1294
|
+
|
|
1295
|
+
ONE number, not one per tool: there is no evidence any two math tools
|
|
1296
|
+
want different answers, and a per-tool budget makes each a judgement
|
|
1297
|
+
call at the registration site. It sits beside SANDBOX_TIMEOUT_SECONDS
|
|
1298
|
+
because that is the constant a reader would compare it against.
|
|
1299
|
+
|
|
1300
|
+
### `network_allowed_commands`
|
|
1301
|
+
|
|
1302
|
+
WARNING: commands matching these words get network access inside the
|
|
1303
|
+
sandbox. A compromised package or script can exfiltrate data or
|
|
1304
|
+
download payloads. Only add commands you trust.
|
|
1305
|
+
|
|
1306
|
+
### `inert_commands`
|
|
1307
|
+
|
|
1308
|
+
WARNING: a word added here is a promise that the program neither writes
|
|
1309
|
+
nor runs code -- under `tiered` it is the ONLY tier that runs unasked
|
|
1310
|
+
(§48, CE1), so an entry that can execute its arguments or a file (`find
|
|
1311
|
+
-exec`, `sort --compress-program`, `tar --to-command`) is an unprompted
|
|
1312
|
+
code path. An inert command runs in the container when Docker or Podman is up and
|
|
1313
|
+
on the host when it is not (§46, EP5); one whose argument reaches outside
|
|
1314
|
+
the workspace is HOST_READ, runs on the host, and always asks. The risk of
|
|
1315
|
+
the host path is information disclosure, not modification.
|
|
1316
|
+
|
|
1317
|
+
### `max_granted_tool_calls`
|
|
1318
|
+
|
|
1319
|
+
ROADMAP_v2 §25 (R6). Ceiling on how many PRE-GRANTED tool calls one
|
|
1320
|
+
research run may make without being asked again. Counts granted calls
|
|
1321
|
+
only -- web_search, arxiv_search and every math tool are approval-free
|
|
1322
|
+
and never touch it, so this is not a cap on tool use.
|
|
1323
|
+
|
|
1324
|
+
Pre-flight authorization trades a per-call decision for one up-front
|
|
1325
|
+
decision, and the thing it gives up is the natural bound on how many
|
|
1326
|
+
times the granted tool runs. Set generously: the ceiling exists to stop
|
|
1327
|
+
an injected loop spending the whole authorization unattended, not to
|
|
1328
|
+
ration ordinary work across ten passes.
|
|
1329
|
+
|
|
1330
|
+
### `attended_approval_timeout_s`
|
|
1331
|
+
|
|
1332
|
+
ROADMAP_v2 §25 (R9). How long an attended research run waits for a human
|
|
1333
|
+
to answer one approval prompt before DENYING that call and carrying on.
|
|
1334
|
+
|
|
1335
|
+
Denial is the safe direction, and continuing is the useful one: walking
|
|
1336
|
+
away from an attended run degrades it rather than wedging it, so nine
|
|
1337
|
+
completed passes are not lost to one unanswered question. Generous by
|
|
1338
|
+
default because the whole point of the mode is that someone is there.
|
|
1339
|
+
|
|
1340
|
+
### `subagent_review`
|
|
1341
|
+
|
|
1342
|
+
ROADMAP_v2 §20 (D9). Whether a finished research run gets a reviewer pass
|
|
1343
|
+
over its own output. Off by default: it is one more model call plus a
|
|
1344
|
+
re-synthesis whenever a correction is accepted, and it needs someone
|
|
1345
|
+
present to consent to anything it changes.
|
|
1346
|
+
|
|
1347
|
+
### `max_review_findings`
|
|
1348
|
+
|
|
1349
|
+
§20 (V4). Ceiling on how many findings one review may put to the user.
|
|
1350
|
+
Consent fatigue is the failure mode a mutating review stage has and a
|
|
1351
|
+
read-only one does not: the fiftieth prompt gets answered differently
|
|
1352
|
+
from the first, and an injected "correction" only needs one reflexive
|
|
1353
|
+
yes. Findings past the cap are dropped and the drop is TRACED -- a
|
|
1354
|
+
silent truncation would read as "the reviewer found twelve things".
|
|
1355
|
+
|
|
1356
|
+
### `max_review_refinements`
|
|
1357
|
+
|
|
1358
|
+
§20 (V5). How many times one finding may be sent back for refinement.
|
|
1359
|
+
A human asks for each round, so this is not a runaway guard -- it bounds
|
|
1360
|
+
the case where the reviewer keeps producing a proposal that misses the
|
|
1361
|
+
same point, which is when the honest answer is to reject it.
|
|
1362
|
+
|
|
1363
|
+
## Compaction (ROADMAP_v2 §21)
|
|
1364
|
+
|
|
1365
|
+
### `compaction_trigger_fraction`
|
|
1366
|
+
|
|
1367
|
+
D27: these are DEFAULTS, not settings. Every value is a starting point
|
|
1368
|
+
chosen to be reasonable and explicitly not claimed to be right, and the
|
|
1369
|
+
compaction block as a whole is overridable through the existing settings
|
|
1370
|
+
mechanism -- `config.yaml` default -> user
|
|
1371
|
+
~/.config/venastine/settings.json -> trusted project
|
|
1372
|
+
.venastine/settings.json -> a per-invocation `/compact --strength N`.
|
|
1373
|
+
The architecture is what's locked; the numbers are expected to move once
|
|
1374
|
+
there are real long threads to look at.
|
|
1375
|
+
|
|
1376
|
+
**THIS KEY IS NOT ONE OF THE OVERRIDABLE ONES.** The paragraph above is
|
|
1377
|
+
D27's about the compaction SECTION, and the seven keys a `settings.json`
|
|
1378
|
+
`compaction` block actually accepts are `strength`, `keep_recent_tokens`,
|
|
1379
|
+
`trigger_tokens`, `warning_margin_tokens`, `keep_recent_turns`,
|
|
1380
|
+
`strategy` and `max_retries` -- `core/config_loader._KNOWN_COMPACTION`.
|
|
1381
|
+
`trigger_fraction` is not among them and unknown nested keys RAISE, so
|
|
1382
|
+
writing `compaction: {trigger_fraction: 0.9}` is a startup error rather
|
|
1383
|
+
than an override. `README.md`'s compaction table lists the seven.
|
|
1384
|
+
|
|
1385
|
+
How much of the model's context window a thread may fill before
|
|
1386
|
+
compaction folds it. `thresholds()` reaches it through
|
|
1387
|
+
`derived_trigger()`, which is `context_limit()` minus `headroom_for()` --
|
|
1388
|
+
so it is 900k on a 1M model and 180k on a 200k one.
|
|
1389
|
+
|
|
1390
|
+
**BATCH 119 MADE IT A CLAMPED HEADROOM RATHER THAN A BARE SHARE, and
|
|
1391
|
+
raised it from 0.85 to 0.90.** What the fraction really names is the
|
|
1392
|
+
REMAINDER: the room the step after the trigger has to fit inside, because
|
|
1393
|
+
nothing recovers from a prompt that overflows the window -- there is no
|
|
1394
|
+
context-overflow handler anywhere in `core/`, so the provider raises, the
|
|
1395
|
+
loop retries the same oversized prompt three times, and the turn dies.
|
|
1396
|
+
|
|
1397
|
+
A bare share gets that wrong at both ends, for the mirror image of the
|
|
1398
|
+
reason batch 44 gave against a flat margin. Batch 44 was right that 40k is
|
|
1399
|
+
a rounding error under 1M and strangling under 64k. A share has the
|
|
1400
|
+
opposite defect, because what the headroom must contain does not scale
|
|
1401
|
+
with the window at all: one `max_read_chars` result is 12,500 proxy tokens
|
|
1402
|
+
whether the model holds 64k or a million, and one measured `arxiv_search`
|
|
1403
|
+
result was 29,249. 0.10 of 1M is 100k; 0.10 of 64k is 6,553, which one
|
|
1404
|
+
ordinary file read overflows.
|
|
1405
|
+
|
|
1406
|
+
So `compaction_min_headroom_tokens` and `compaction_max_headroom_fraction`
|
|
1407
|
+
clamp it, and the floor binds below roughly 160k and nowhere above:
|
|
1408
|
+
|
|
1409
|
+
| window | 0.85 (pre-119) | bare 0.90 | shipped | which clamp |
|
|
1410
|
+
|---|---|---|---|---|
|
|
1411
|
+
| 32,768 | 27,852 | 29,491 | 24,576 | cap |
|
|
1412
|
+
| 65,536 | 55,705 | 58,982 | 49,536 | floor |
|
|
1413
|
+
| 131,072 | 111,411 | 117,964 | 115,072 | floor |
|
|
1414
|
+
| 262,144 | 222,822 | 235,929 | 235,929 | fraction |
|
|
1415
|
+
| 1,000,000 | 850,000 | 900,000 | 900,000 | fraction |
|
|
1416
|
+
|
|
1417
|
+
The headroom is computed as `window - int(fraction * window)` rather than
|
|
1418
|
+
`(1 - fraction) * window`, so the unclamped case reproduces the fraction
|
|
1419
|
+
exactly. The two differ by the truncation, and truncating the headroom
|
|
1420
|
+
down put the trigger one token ABOVE `int(fraction * window)` -- harmless
|
|
1421
|
+
as a number, not harmless as an identity, since every table above would
|
|
1422
|
+
have been off by one with nothing to point at.
|
|
1423
|
+
|
|
1424
|
+
### `compaction_min_headroom_tokens`
|
|
1425
|
+
|
|
1426
|
+
The floor on the headroom above. Sized from `max_read_chars` (50,000
|
|
1427
|
+
chars = 12,500 proxy tokens, the largest a single bounded read returns)
|
|
1428
|
+
plus the assistant turn that asked for it. It binds under a ~160k window
|
|
1429
|
+
and nowhere above one, which is the whole point: a 262k or 1M thread gets
|
|
1430
|
+
`compaction_trigger_fraction` exactly as written, and a 64k local model
|
|
1431
|
+
keeps a usable margin instead of the 6,553 tokens a bare share leaves it.
|
|
1432
|
+
|
|
1433
|
+
Not every tool respects `max_read_chars` -- `arxiv_search` does not, and
|
|
1434
|
+
one of its results measured 29,249 proxy tokens (TECHNICAL_DEBT 41). This
|
|
1435
|
+
floor does not cover that, and above ~160k the fraction leaves more room
|
|
1436
|
+
than it anyway; what it covers is the bounded case at the bottom of the
|
|
1437
|
+
roster, where nothing else would.
|
|
1438
|
+
|
|
1439
|
+
Both halves of that stay true and the ITEM is closed (batch 126).
|
|
1440
|
+
`arxiv_search` still does not consult `max_read_chars` -- it should not, a
|
|
1441
|
+
character cap over an assembled dict cuts it mid-structure -- but it now
|
|
1442
|
+
carries its own bounds, per field and on the wire, so the row that sized
|
|
1443
|
+
this floor can no longer occur. The floor's derivation is unchanged: it was
|
|
1444
|
+
sized from `max_read_chars` plus the turn that asked for it, never from
|
|
1445
|
+
this row. What the row did was prove the fraction had to be CLAMPED, and
|
|
1446
|
+
that argument does not depend on the tool staying unbounded.
|
|
1447
|
+
|
|
1448
|
+
### `compaction_max_headroom_fraction`
|
|
1449
|
+
|
|
1450
|
+
The cap on the headroom, and it is load-bearing rather than defensive:
|
|
1451
|
+
16,000 tokens of a 32,768-token window is half of it, and an unclamped
|
|
1452
|
+
floor under a small window derives a trigger at or below zero -- or one
|
|
1453
|
+
under `keep_recent_tokens`, where `effective_compaction()` raises on every
|
|
1454
|
+
evaluation and `should_compact()` runs at the top of every step. This is
|
|
1455
|
+
the clamp that keeps the bottom of the range working at all.
|
|
1456
|
+
|
|
1457
|
+
BATCH 44 REVERSED M1, AND THE REASON M1 GAVE HAS EXPIRED. M1 rejected a
|
|
1458
|
+
window-derived trigger because "a window-derived trigger sits at a size
|
|
1459
|
+
the thread can never reach in working order" -- and the arithmetic
|
|
1460
|
+
behind that was about MAX_TOKEN_BUDGET, then a default spend ceiling of
|
|
1461
|
+
250k: the prompt is re-sent on every step of a tool-using turn, so a
|
|
1462
|
+
thread at 160k got one response and no tool calls before the cap ended
|
|
1463
|
+
the turn. Batch 27 DELETED that default ceiling. There is no cap for a
|
|
1464
|
+
large trigger to collide with any more, so the premise is gone and the
|
|
1465
|
+
flat 40k outlived it -- compacting a 1M-window thread at 4% of its
|
|
1466
|
+
window, spending a model call and losing fidelity to solve a problem
|
|
1467
|
+
the model did not have.
|
|
1468
|
+
|
|
1469
|
+
THE COST OF THE REVERSAL, STATED. MODEL_CONTEXT_WINDOWS and the provider
|
|
1470
|
+
query decide when every thread folds now, where under M1 a wrong entry
|
|
1471
|
+
only mistimed a research backstop. That is why core/model_windows.py
|
|
1472
|
+
exists (the user's own answer, outranking both) and why the fallback
|
|
1473
|
+
still WARNS. A fraction rather than `window - margin`: a fixed margin
|
|
1474
|
+
that is right for a 1M model leaves a 64k model no working room at all,
|
|
1475
|
+
and one that is right for 64k never fires on 1M.
|
|
1476
|
+
|
|
1477
|
+
### `compaction_trigger_tokens`
|
|
1478
|
+
|
|
1479
|
+
The trigger used when NO MODEL IS IN SCOPE -- and the default
|
|
1480
|
+
settings.json's `compaction.trigger_tokens` overrides.
|
|
1481
|
+
|
|
1482
|
+
One caller has no (provider, model) to derive a window from:
|
|
1483
|
+
compaction.pin_measurements, which computes #89's cap as
|
|
1484
|
+
PIN_MAX_TRIGGER_FRACTION x the trigger from a thread id alone. Left at
|
|
1485
|
+
40_000 deliberately, so the pin cap is exactly what it was before batch
|
|
1486
|
+
44 -- this batch changes when a thread compacts, not how much of one a
|
|
1487
|
+
single pin may freeze, and a cap that grew with the window would let one
|
|
1488
|
+
`pin` call freeze 425k tokens of a 1M-window thread.
|
|
1489
|
+
|
|
1490
|
+
### `compaction_warning_margin_tokens`
|
|
1491
|
+
|
|
1492
|
+
Fires this many tokens BEFORE the trigger, so there is room to do
|
|
1493
|
+
something about it -- pin a message, wrap up a thought, run /compact at a
|
|
1494
|
+
natural break.
|
|
1495
|
+
|
|
1496
|
+
STILL ABSOLUTE after batch 44, and that is a decision rather than an
|
|
1497
|
+
oversight. What this buys is a HUMAN'S REACTION TIME, measured in turns,
|
|
1498
|
+
and a turn does not get bigger because the window did: 8k is roughly a
|
|
1499
|
+
turn or two of notice on a 64k model and on a 1M one alike. As a
|
|
1500
|
+
fraction of the new trigger it would be 128k on a 1M model -- a warning
|
|
1501
|
+
that fires while the thread is at 72% and has nothing to worry about
|
|
1502
|
+
yet. §21 singles this out as the one value whose wrong setting
|
|
1503
|
+
is not self-correcting: too small and it is an alert with no time
|
|
1504
|
+
attached to it. Validated to be strictly less than the trigger.
|
|
1505
|
+
|
|
1506
|
+
### `compaction_keep_recent_tokens`
|
|
1507
|
+
|
|
1508
|
+
The most recent tokens that always stay verbatim, never compacted.
|
|
1509
|
+
|
|
1510
|
+
ABSOLUTE, like the warning margin above and for the same kind of reason:
|
|
1511
|
+
this is an amount of CONVERSATION to keep intact, not a share of a
|
|
1512
|
+
window. It is also the weaker of the two floors in practice -- M5 keeps
|
|
1513
|
+
whichever protects more, and the three-turn floor below almost always
|
|
1514
|
+
protects more than 4k on the long threads that reach the trigger at all.
|
|
1515
|
+
Left where it was so batch 44 changes when a thread folds and not what
|
|
1516
|
+
survives the fold.
|
|
1517
|
+
|
|
1518
|
+
### `compaction_keep_recent_turns`
|
|
1519
|
+
|
|
1520
|
+
M5: a FLOOR in turns, on top of the token floor above, and the two
|
|
1521
|
+
compose -- whichever protects more wins, plus the current turn, which is
|
|
1522
|
+
never foldable at all. A single tool-heavy turn can consume the whole
|
|
1523
|
+
keep-token budget by itself, leaving the immediately preceding exchange
|
|
1524
|
+
summarized; a follow-up like "no, the other one" then has no referent.
|
|
1525
|
+
|
|
1526
|
+
### `pin_max_trigger_fraction`
|
|
1527
|
+
|
|
1528
|
+
#89 (batch 16). The most one `pin` call may protect, as a fraction of
|
|
1529
|
+
the trigger above. A pin is a PERMANENT FLOOR under the derived view:
|
|
1530
|
+
pinned rows re-enter it verbatim forever (M9), nothing folds them, and
|
|
1531
|
+
before this cap one ungated call with last_n=40 could put a thread
|
|
1532
|
+
permanently past the trigger with no unpin to undo it. 0.5 leaves room
|
|
1533
|
+
for a real working session while making "floor the trigger by yourself"
|
|
1534
|
+
structurally impossible. Enforced at the tool with a REFUSAL that states
|
|
1535
|
+
the cap and the current share -- never silently trimmed (M15's rule: a
|
|
1536
|
+
pin asked for more protection than allowed must not quietly deliver less).
|
|
1537
|
+
|
|
1538
|
+
### `compaction_strength`
|
|
1539
|
+
|
|
1540
|
+
1-5, mapping to the target compression ratios below.
|
|
1541
|
+
|
|
1542
|
+
### `compaction_max_retries`
|
|
1543
|
+
|
|
1544
|
+
Bounded corrective retries when the compactor misses its target ratio.
|
|
1545
|
+
|
|
1546
|
+
### `compaction_target_ratios`
|
|
1547
|
+
|
|
1548
|
+
§21: strength is an objectively measurable target, not a qualitative
|
|
1549
|
+
instruction. "Be more aggressive" behaves differently across models with
|
|
1550
|
+
different summarization tendencies and no amount of prompting fixes that;
|
|
1551
|
+
a ratio is checkable after the fact. Qualitative guidance still belongs
|
|
1552
|
+
in the compactor's prompt, shaping WHAT survives within the budget.
|
|
1553
|
+
|
|
1554
|
+
### `compaction_ratio_tolerance`
|
|
1555
|
+
|
|
1556
|
+
How far outside the target a summary may land before it is sent back.
|
|
1557
|
+
Under-shooting is not an error: a summary tighter than asked for has
|
|
1558
|
+
already done the job, and rejecting it would spend a second call to make
|
|
1559
|
+
the context bigger.
|
|
1560
|
+
|
|
1561
|
+
### `compaction_strategy`
|
|
1562
|
+
|
|
1563
|
+
M2 as amended by batch 16 (#90, owner decision). Two strategies:
|
|
1564
|
+
|
|
1565
|
+
```text
|
|
1566
|
+
"chain" summarizes the PREVIOUS SUMMARY plus whatever followed it.
|
|
1567
|
+
Constant cost per compaction forever -- the input never
|
|
1568
|
+
grows past summary-plus-tail -- at the price of loss that
|
|
1569
|
+
compounds over a long-lived thread (a summary of a summary
|
|
1570
|
+
of a ...).
|
|
1571
|
+
"rederive" summarizes the ORIGINAL messages every time, so exactly
|
|
1572
|
+
one summarization step always sits between an original
|
|
1573
|
+
message and what the model sees. Fidelity-optimal; input
|
|
1574
|
+
grows with the covered span.
|
|
1575
|
+
```
|
|
1576
|
+
|
|
1577
|
+
The DEFAULT is "chain", reversing M2's original choice -- an explicit
|
|
1578
|
+
owner decision recorded in DEVLOG (batch 16): rederive's whole-span
|
|
1579
|
+
input made every compaction the most expensive call of the turn, and
|
|
1580
|
+
cost compounds on exactly the threads that trigger most. Whatever is
|
|
1581
|
+
configured here, BOTH strategies fall back to chain automatically when
|
|
1582
|
+
a span outgrows one call (built at last, after three documents promised
|
|
1583
|
+
it for two sections), saying so in a WARNING -- and truncate the oldest
|
|
1584
|
+
material with a stated truncation when even chain cannot fit, because
|
|
1585
|
+
an oversized send is never the right failure direction.
|
|
1586
|
+
|
|
1587
|
+
### `compaction_strategies`
|
|
1588
|
+
|
|
1589
|
+
### `max_injected_memories`
|
|
1590
|
+
|
|
1591
|
+
ROADMAP_v2 §21b (M14). Ceiling on how many durable memories reach one
|
|
1592
|
+
prompt. Newest first, and the truncation is stated in the fragment the
|
|
1593
|
+
model reads rather than only in a log.
|
|
1594
|
+
|
|
1595
|
+
Every in-scope memory would otherwise enter every turn forever, which is
|
|
1596
|
+
the unbounded context growth §21 exists to fight -- a memory feature that
|
|
1597
|
+
quietly reintroduces the problem compaction solves would be a poor trade.
|
|
1598
|
+
Recency is the ordering because it is the only staleness signal available
|
|
1599
|
+
without asking a model, and /forget is how a still-relevant old memory
|
|
1600
|
+
gets kept ahead of the cap.
|
|
1601
|
+
|
|
1602
|
+
## Catalog text (ROADMAP_v2 §32, A5)
|
|
1603
|
+
|
|
1604
|
+
### `max_catalog_text_chars`
|
|
1605
|
+
|
|
1606
|
+
The cap on a skill's or an agent's `name` and `description` -- the
|
|
1607
|
+
two strings that go from a .md file straight into the system prompt
|
|
1608
|
+
of every run in a project, with no tool call and no further consent
|
|
1609
|
+
(#131).
|
|
1610
|
+
|
|
1611
|
+
300 is headroom rather than a squeeze: the longest description this
|
|
1612
|
+
project ships is `compactor` at 171 characters, and all eight are
|
|
1613
|
+
single-line. A project whose description does not fit in twice the
|
|
1614
|
+
length of ours is writing instructions, not a summary, which is
|
|
1615
|
+
exactly the thing the cap is for.
|
|
1616
|
+
|
|
1617
|
+
THE NEWLINE COLLAPSE MATTERS MORE THAN THE NUMBER, and they are one
|
|
1618
|
+
constant because they are one rule -- see config_loader._catalog_text.
|
|
1619
|
+
Same posture as tools/builtin/arxiv.MAX_SUMMARY_CHARS (600) and
|
|
1620
|
+
web_search.MAX_SNIPPET_CHARS (300): model-facing text from a source
|
|
1621
|
+
this project did not write is bounded where it is produced.
|
|
1622
|
+
|
|
1623
|
+
ROADMAP_v3 §51 (PG8) left both caps exactly where they are and made
|
|
1624
|
+
them SAY when they bit. A value cut at a cap and a value that happens
|
|
1625
|
+
to be that long were indistinguishable, so "the paper does not mention
|
|
1626
|
+
X" and "the first 600 characters do not" read the same to the model.
|
|
1627
|
+
The flag is the fix; raising the cap is not, for the reason above.
|
|
1628
|
+
|
|
1629
|
+
## Summaries, references and the checklist (ROADMAP_v2 §21c / §23)
|
|
1630
|
+
|
|
1631
|
+
### `compactor_agent`
|
|
1632
|
+
|
|
1633
|
+
The agent that does the summarizing. §21: this is the shape of an agent
|
|
1634
|
+
call -- a system prompt, a task, a judgment-based output -- so it runs
|
|
1635
|
+
through the same RunAgentLoop as everything else rather than needing its
|
|
1636
|
+
own LLM-calling path, and that is also what gives it real autonomy over
|
|
1637
|
+
WHAT to preserve. Mechanical truncation cannot exercise judgment at all.
|
|
1638
|
+
|
|
1639
|
+
### `summary_target_chars`
|
|
1640
|
+
|
|
1641
|
+
ROADMAP_v2 §21c. How long a whole-thread summary may be, in characters.
|
|
1642
|
+
|
|
1643
|
+
ABSOLUTE, not a COMPACTION_TARGET_RATIOS entry, and the difference is the
|
|
1644
|
+
consumer rather than the summarizer. A fold's summary REPLACES the span it
|
|
1645
|
+
came from, so scaling with that span is right: a bigger fold earns a bigger
|
|
1646
|
+
summary and the thread still shrinks. §21c's summary is injected as a prompt
|
|
1647
|
+
tier present on every turn of the REFERENCING thread, where nothing it
|
|
1648
|
+
replaces bounds it -- a 500KB thread at strength 3 would put 75KB into every
|
|
1649
|
+
call indefinitely.
|
|
1650
|
+
|
|
1651
|
+
A thread whose rendered text already fits this is stored verbatim and costs
|
|
1652
|
+
no model call at all.
|
|
1653
|
+
|
|
1654
|
+
### `max_injected_refs`
|
|
1655
|
+
|
|
1656
|
+
§21c. How many referenced threads may be attached to one thread at once.
|
|
1657
|
+
|
|
1658
|
+
Small on purpose, and the cap REFUSES rather than dropping the oldest: a
|
|
1659
|
+
reference is something a person chose by name, and silently discarding one
|
|
1660
|
+
to make room for another is exactly what §21b's "removal is by id, never by
|
|
1661
|
+
substring" rule exists to prevent. The count and the cap are stated in the
|
|
1662
|
+
fragment the model reads, per M14's no-silent-caps rule.
|
|
1663
|
+
|
|
1664
|
+
### `todo_statuses`
|
|
1665
|
+
|
|
1666
|
+
§23 slice 2. The todo list's vocabulary and its ceiling.
|
|
1667
|
+
|
|
1668
|
+
A plain tuple rather than an Enum, for storage.py's THREAD_KIND_* reason: a
|
|
1669
|
+
list persisted under an older vocabulary reads back as data rather than
|
|
1670
|
+
raising, and the tool can then say which status it did not recognise.
|
|
1671
|
+
|
|
1672
|
+
### `max_todo_items`
|
|
1673
|
+
|
|
1674
|
+
The list is injected into every turn's system prompt, so its length is a
|
|
1675
|
+
per-call cost for as long as the thread lives. REFUSES rather than
|
|
1676
|
+
truncating, MAX_INJECTED_REFS' rule: a checklist silently cut to 50 would
|
|
1677
|
+
have the model believe it had recorded work it has now forgotten, which is
|
|
1678
|
+
worse than being told to write a shorter list.
|
|
1679
|
+
|
|
1680
|
+
### `compaction_pipeline_backstop_tokens`
|
|
1681
|
+
|
|
1682
|
+
M6. A research pass is headless and unattended, and each one already
|
|
1683
|
+
returns a distillation, so routine compaction there would spend on a
|
|
1684
|
+
judgment call nobody is watching. Passes compact only when approaching
|
|
1685
|
+
the model's actual context window -- a safety net against a hard provider
|
|
1686
|
+
error mid-pipeline, not a working-set policy.
|
|
1687
|
+
|
|
1688
|
+
## Context windows (ROADMAP_v2 §21 M1, as amended by batches 30 and 44)
|
|
1689
|
+
|
|
1690
|
+
### `model_context_windows`
|
|
1691
|
+
|
|
1692
|
+
The backstop's source, the summarizer's input budget, and M1's remaining
|
|
1693
|
+
use for a window table.
|
|
1694
|
+
|
|
1695
|
+
NOW A FALLBACK, NOT THE ONLY SOURCE. This said "deliberately NOT a
|
|
1696
|
+
per-provider API query", on the grounds that the roster of fifteen had no
|
|
1697
|
+
uniform endpoint and a query would need fifteen adapters to avoid a
|
|
1698
|
+
fallback constant they would all still need. The premise was measured
|
|
1699
|
+
against the PINNED SDKs and did not survive:
|
|
1700
|
+
|
|
1701
|
+
```text
|
|
1702
|
+
anthropic 0.116.0 ModelInfo.max_input_tokens -- on the SAME object
|
|
1703
|
+
core/client.py already retrieves to read
|
|
1704
|
+
capabilities.effort. The answer was in hand and
|
|
1705
|
+
being dropped; reading it costs no extra call.
|
|
1706
|
+
google-genai 2.29.0 types.Model.input_token_limit, one field (as 1.0.0).
|
|
1707
|
+
openai 2.45.0 Model is declared extra="allow", so a provider's
|
|
1708
|
+
own field survives onto .model_extra. That makes
|
|
1709
|
+
the OpenAI-compatible side ONE alias reader --
|
|
1710
|
+
context_window (Groq), context_length (Together,
|
|
1711
|
+
OpenRouter, Cohere), max_context_length (Mistral)
|
|
1712
|
+
-- rather than thirteen adapters.
|
|
1713
|
+
```
|
|
1714
|
+
|
|
1715
|
+
So it is two attribute reads and one sniff, not fifteen adapters. The
|
|
1716
|
+
query lives in core/client.py:context_window_for, beside the effort query
|
|
1717
|
+
it mirrors; core/compaction.py:context_limit prefers it and falls back
|
|
1718
|
+
here. (The old note also corrected itself on a provider count from the
|
|
1719
|
+
dead APICredentials class -- audit #23. Fifteen is right; the count was
|
|
1720
|
+
never what was wrong with the argument.)
|
|
1721
|
+
|
|
1722
|
+
THE CONCLUSION OUTLIVED THE PREMISE, which is why this table stays: OpenAI,
|
|
1723
|
+
DeepSeek and Perplexity answer /models with id/created/object/owned_by and
|
|
1724
|
+
nothing else, and Grok, Fireworks, Qwen and Z.AI publish no model-metadata
|
|
1725
|
+
endpoint at all. A fallback constant is still needed at the end of it.
|
|
1726
|
+
|
|
1727
|
+
KEYS ARE STORED NORMALIZED -- no date suffix, no `vendor/` or `region.`
|
|
1728
|
+
prefix. core/compaction.py:_normalized reduces an incoming id to this form
|
|
1729
|
+
before looking it up, so a dated key here would be UNREACHABLE. That is
|
|
1730
|
+
also the bug this fixed: matching was exact, so `claude-sonnet-5-20260724`
|
|
1731
|
+
missed a million-token entry and silently took the default.
|
|
1732
|
+
|
|
1733
|
+
AN INCOMPLETE ENTRY IS EXPENSIVE NOW. Under M1 it cost a mistimed
|
|
1734
|
+
research backstop and a mistimed summarizer input budget, because the
|
|
1735
|
+
working-set trigger was a flat number that never consulted this. Batch 44
|
|
1736
|
+
made that trigger a FRACTION of what context_limit() returns, so a wrong
|
|
1737
|
+
number here mistimes compaction on every thread -- too high and the
|
|
1738
|
+
thread never folds and the provider raises a hard context-limit error
|
|
1739
|
+
instead. core/model_windows.py is the user's answer to that, and /window
|
|
1740
|
+
is how they give it; this table is what answers before they do.
|
|
1741
|
+
|
|
1742
|
+
**Notes on individual entries.**
|
|
1743
|
+
|
|
1744
|
+
1M IS THE ORDINARY WINDOW ON THESE, not a beta.
|
|
1745
|
+
|
|
1746
|
+
This block used to carry the opposite claim -- that 1M was gated
|
|
1747
|
+
behind a `context-1m-2025-08-07` header this harness does not send,
|
|
1748
|
+
so an ordinary account got 200_000 and these entries "want to be
|
|
1749
|
+
200_000". That was true of the Sonnet 4 era and was never true of
|
|
1750
|
+
the models listed here; checked against the current model reference
|
|
1751
|
+
in batch 44, the whole 4.6-and-later family is 1M and Haiku 4.5 is
|
|
1752
|
+
200K. The values were right and the comment was stale, which is the
|
|
1753
|
+
dangerous combination now that the trigger reads them: a reader
|
|
1754
|
+
following the old note would have "corrected" five entries by a
|
|
1755
|
+
factor of five and compacted every Claude thread at a fifth of the
|
|
1756
|
+
window.
|
|
1757
|
+
Dateless, per the normalization note above: this was keyed
|
|
1758
|
+
"claude-haiku-4-5-20251001" while its five siblings were dateless,
|
|
1759
|
+
which is the inconsistency that exposed the exact-match bug.
|
|
1760
|
+
Alibaba markets "1M"; the documented input limit is 983,616, and
|
|
1761
|
+
drops to that figure specifically when thinking is enabled. The
|
|
1762
|
+
SMALLER number is the right one to record: this feeds the pipeline
|
|
1763
|
+
compaction backstop (context_limit - COMPACTION_PIPELINE_BACKSTOP_
|
|
1764
|
+
TOKENS), where erring low compacts slightly early and erring high
|
|
1765
|
+
means a hard context-limit error from the provider mid-run.
|
|
1766
|
+
|
|
1767
|
+
### `default_context_window`
|
|
1768
|
+
|
|
1769
|
+
Logged at WARNING ONCE PER MODEL, per §21 -- a wrong-by-default window
|
|
1770
|
+
means compaction and the backstop both fire at the wrong time in
|
|
1771
|
+
whichever direction the guess is wrong, and silent guessing turns a
|
|
1772
|
+
tuning problem into a mystery. Once per model rather than once per use,
|
|
1773
|
+
because context_limit() is on should_compact()'s path and that runs at
|
|
1774
|
+
the top of every step of every turn; the dedup set lives in
|
|
1775
|
+
core/compaction.py. A long session therefore says this once and is then
|
|
1776
|
+
silent, which is the trade -- the line is actionable exactly once, and
|
|
1777
|
+
since batch 44 it names the action (/window, which remembers).
|
|
1778
|
+
|
|
1779
|
+
256_000 rather than 200_000 (batch 44): the floor a hosted agentic model
|
|
1780
|
+
ships with today. Below that is essentially always a self-hosted
|
|
1781
|
+
deployment, whose operator knows the number and can say it once with
|
|
1782
|
+
/window -- which is the case this default cannot serve and does not try
|
|
1783
|
+
to. Erring low here would compact every unknown model early forever to
|
|
1784
|
+
protect the rarer case that has an owner who can answer.
|
|
1785
|
+
|
|
1786
|
+
## Connecting a model (ROADMAP_v3 §79)
|
|
1787
|
+
|
|
1788
|
+
### `hf_oauth_client_id`
|
|
1789
|
+
|
|
1790
|
+
ROADMAP_v3 §79 (HD5). The Hugging Face OAuth app `/connect huggingface` signs
|
|
1791
|
+
in through. The default is the project's own app, registered by the owner on
|
|
1792
|
+
2026-10-20, so the sign-in works in every install and every hosted deployment
|
|
1793
|
+
without anyone registering another. Another app's id signs in through that app
|
|
1794
|
+
instead; empty hides the sign-in and leaves a pasted token working.
|
|
1795
|
+
|
|
1796
|
+
**A client id is public, and that is what makes it a `config.yaml` value.** The
|
|
1797
|
+
app is registered with NO secret (Hugging Face calls this a public app), with
|
|
1798
|
+
the device code flow enabled, so nothing about it needs hiding: it names which
|
|
1799
|
+
app asks, and the person approving the request sees that name on Hugging
|
|
1800
|
+
Face's own page. The scopes live on the app's registration (`openid profile
|
|
1801
|
+
inference-api`), not here, so editing this value can change WHICH app asks but
|
|
1802
|
+
not what it may do.
|
|
1803
|
+
|
|
1804
|
+
**Not an authority key.** It cannot widen a tool permission or an approval, and
|
|
1805
|
+
`settings.json` cannot set it at all, like every other key in this file.
|
|
1806
|
+
|
|
1807
|
+
## Tool permissions and approvals (ROADMAP_v2 §15, D24)
|
|
1808
|
+
|
|
1809
|
+
### `tool_permissions`
|
|
1810
|
+
|
|
1811
|
+
APICredentials was here and is deleted (audit #23). It was dead -- nothing
|
|
1812
|
+
constructed it, imported it or type-hinted against it -- and its guidance
|
|
1813
|
+
contradicted the mechanism that is real: it told the reader to put the key
|
|
1814
|
+
in an environment variable and write the VARIABLE'S NAME here, while
|
|
1815
|
+
credentials.save_credentials stores the key value directly in
|
|
1816
|
+
providers.json. Anyone following it ended up with the literal string
|
|
1817
|
+
"MY_KEY_VAR" as their API key.
|
|
1818
|
+
|
|
1819
|
+
Credentials flow through credentials.py (providers.json) and env_secrets.py
|
|
1820
|
+
(.env) -- the deliberate two-mechanism split D19 describes, which
|
|
1821
|
+
env_secrets.py documents at length on the other side. The provider roster
|
|
1822
|
+
lives in providers.json.example, beside the file it describes.
|
|
1823
|
+
|
|
1824
|
+
#### `tool_permissions.fetch_url` -- ships `true`
|
|
1825
|
+
|
|
1826
|
+
ROADMAP_v2 §15/D24: fetch_url was registered and documented as working
|
|
1827
|
+
but had no field here, so getattr(..., False) denied every call since
|
|
1828
|
+
the tool was added. Allowed by default, matching web_search -- it is
|
|
1829
|
+
already constrained by policy_enforcement's blocked-domain list and
|
|
1830
|
+
its output goes through secret redaction like every other tool's.
|
|
1831
|
+
|
|
1832
|
+
#### `tool_permissions.shell_background` / `shell_monitor` / `shell_sessions` / `shell_output` / `shell_kill` -- ship `false`
|
|
1833
|
+
|
|
1834
|
+
ROADMAP_v3 §49 (SS11). The five background-session tools, shipped disabled
|
|
1835
|
+
for `shell`'s reason and not a weaker one: a session IS a shell command, and
|
|
1836
|
+
one that keeps running after the call that started it has been answered.
|
|
1837
|
+
Enabling them without `shell` is allowed and coherent -- a session is
|
|
1838
|
+
classified, approved and routed by exactly the same rules -- but a session
|
|
1839
|
+
also holds a container for as long as its timeout, blocks the user's prompt
|
|
1840
|
+
while it runs, and can wake the agent, so it is more authority rather than
|
|
1841
|
+
less.
|
|
1842
|
+
|
|
1843
|
+
The two that START one are approval-gated by `shell_approval_mode` alone
|
|
1844
|
+
(SS16) and have no `tool_approvals` key, exactly like `shell`; the three
|
|
1845
|
+
that list, read and stop need no approval, because they act only on sessions
|
|
1846
|
+
this conversation already had approved. All five are additionally hidden
|
|
1847
|
+
wherever nothing would ever wake the run -- a research pass, or any run
|
|
1848
|
+
outside a chat turn or a subagent (SS17).
|
|
1849
|
+
|
|
1850
|
+
#### `tool_permissions.spawn_subagent` -- ships `true`
|
|
1851
|
+
|
|
1852
|
+
§18: spawning is allowed by default (model autonomy, D6) and needs no
|
|
1853
|
+
approval -- the spawned run's own tools are each gated by policy,
|
|
1854
|
+
intersection-capped by the parent's context (C6).
|
|
1855
|
+
|
|
1856
|
+
#### `tool_permissions.pin` -- ships `true`
|
|
1857
|
+
|
|
1858
|
+
§21/D26. Thread-scoped, reversible (batch 16 gave that word a
|
|
1859
|
+
mechanism: `unpin`), and it takes effect inside a conversation the
|
|
1860
|
+
user is watching -- a wrong pin costs some context budget and nothing
|
|
1861
|
+
else.
|
|
1862
|
+
|
|
1863
|
+
#### `tool_permissions.unpin` -- ships `true`
|
|
1864
|
+
|
|
1865
|
+
§21/D26, restored by batch 16 (#89). D26's premise called a pin
|
|
1866
|
+
reversible while nothing anywhere unpinned one; unpin is the other
|
|
1867
|
+
half of making the premise true rather than aspirational. Same axis,
|
|
1868
|
+
same gating posture, same reasons.
|
|
1869
|
+
|
|
1870
|
+
#### `tool_permissions.remember` -- ships `true`
|
|
1871
|
+
|
|
1872
|
+
§21b. Allowed everywhere; whether it can actually RUN is decided
|
|
1873
|
+
by the approval gate below plus §13's headless rule.
|
|
1874
|
+
|
|
1875
|
+
#### `tool_permissions.read_project_doc` -- ships `true`
|
|
1876
|
+
|
|
1877
|
+
§24 (I2). Allowed, unlike `read`, because it is confined to the
|
|
1878
|
+
project directory by realpath and to documentation/manifest files by
|
|
1879
|
+
an allowlist -- see tools/builtin/project_docs.py for what that
|
|
1880
|
+
deliberately excludes and why the narrow set is load-bearing.
|
|
1881
|
+
|
|
1882
|
+
#### `tool_permissions.write_project_doc` -- ships `true`
|
|
1883
|
+
|
|
1884
|
+
§24 (I1). Allowed, unlike `write`, because it takes a document NAME
|
|
1885
|
+
from a fixed allowlist rather than a path: the destination is derived,
|
|
1886
|
+
so the tool cannot be aimed anywhere else. The gate is below.
|
|
1887
|
+
|
|
1888
|
+
#### `tool_permissions.ask_user` -- ships `true`
|
|
1889
|
+
|
|
1890
|
+
§23 slice 2. Allowed everywhere, and ungated below (J12): whether it
|
|
1891
|
+
can actually reach a person is decided by whether the run has a
|
|
1892
|
+
response channel, which the tool itself checks.
|
|
1893
|
+
|
|
1894
|
+
#### `tool_permissions.todo_write` -- ships `true`
|
|
1895
|
+
|
|
1896
|
+
§23 slice 2. Thread-scoped, reversible, and it asks nobody -- so it is
|
|
1897
|
+
allowed and ungated for `pin`'s reasons (J9).
|
|
1898
|
+
|
|
1899
|
+
### `tool_approvals`
|
|
1900
|
+
|
|
1901
|
+
#### `tool_approvals.fetch_url` -- ships `false`
|
|
1902
|
+
|
|
1903
|
+
No approval: a tool with approval=True is unusable wherever there is
|
|
1904
|
+
no permission_channel to answer the prompt (the CLI chat loop and
|
|
1905
|
+
every research pass), so gating fetch_url would leave it denied in
|
|
1906
|
+
exactly the places the grounding passes need it -- the same outcome
|
|
1907
|
+
as the D24 bug, with a different error string. See DEVLOG §15.
|
|
1908
|
+
|
|
1909
|
+
#### `tool_approvals.shell` -- removed, not shipped
|
|
1910
|
+
|
|
1911
|
+
There is deliberately no such key. Shell approval is governed solely by
|
|
1912
|
+
`shell_approval_mode` above: the field this section used to describe was
|
|
1913
|
+
the RATCHET (`True` forced `always` whatever the mode said), and every
|
|
1914
|
+
outcome it could produce is an outcome the mode already names -- so a
|
|
1915
|
+
second switch could only ever agree with the gate or surprise someone who
|
|
1916
|
+
set the two differently. An agent's `approval_overrides` keeps its own
|
|
1917
|
+
one-way power over shell through the context layer (D14); what is gone is
|
|
1918
|
+
only the global duplicate. An old file still carrying the key is refused
|
|
1919
|
+
at startup naming it (unknown keys are refused, always), and the npm-update
|
|
1920
|
+
merge drops it as "not a setting in this version" while keeping every
|
|
1921
|
+
other edit.
|
|
1922
|
+
|
|
1923
|
+
#### `tool_approvals.shell_background` / `shell_monitor` -- removed, not shipped
|
|
1924
|
+
|
|
1925
|
+
ROADMAP_v3 §49 (SS16). There are deliberately no such keys, for the reason
|
|
1926
|
+
`tool_approvals.shell` has none: a start tool runs a shell command, so
|
|
1927
|
+
`shell_approval_mode` above decides it, and a second switch here could only
|
|
1928
|
+
agree with the gate or surprise whoever set the two differently. They are
|
|
1929
|
+
registered with shell's own approval check -- by object identity, asserted
|
|
1930
|
+
at import in `tools/registry.py` -- so the exemption cannot outlive the gate
|
|
1931
|
+
that justifies it.
|
|
1932
|
+
|
|
1933
|
+
#### `tool_approvals.shell_sessions` / `shell_output` / `shell_kill` -- ship `false`
|
|
1934
|
+
|
|
1935
|
+
ROADMAP_v3 §49 (SS11): UNGATED, on the axis that separates `pin` from
|
|
1936
|
+
`remember`. Listing sessions, reading one's output and stopping one act
|
|
1937
|
+
only on sessions this conversation started, each of which was already
|
|
1938
|
+
approved as a command; none of them starts anything or reaches outside the
|
|
1939
|
+
thread. Gating them would also make them invisible exactly where they are
|
|
1940
|
+
needed, since an approval-gated tool is not advertised where nothing can
|
|
1941
|
+
ask (§13) -- an agent able to start a session but not to read or stop it is
|
|
1942
|
+
the worse failure.
|
|
1943
|
+
|
|
1944
|
+
#### `tool_approvals.spawn_subagent` -- ships `true`
|
|
1945
|
+
|
|
1946
|
+
Approving a spawn is the §18 subagent sign-off: it authorises the
|
|
1947
|
+
child's whole approval-gated tool set for the rest of the turn, so
|
|
1948
|
+
delegation itself has to be the thing approved. Consequence, named
|
|
1949
|
+
rather than discovered: the headless callability filter drops
|
|
1950
|
+
spawn_subagent anywhere nothing can grant the approval -- CLI chat,
|
|
1951
|
+
and any research run that is neither attended nor granting. The
|
|
1952
|
+
once-per-run notice names it.
|
|
1953
|
+
|
|
1954
|
+
§25 R4 declares it GRANT_NEVER (R13, on the ToolSpec): it can never
|
|
1955
|
+
be PRE-granted, in a research run OR at §18's sign-off, because
|
|
1956
|
+
approving a spawn hands the child a whole gated set and one
|
|
1957
|
+
launch-time tick would compound into unbounded delegated authority
|
|
1958
|
+
across ten unattended passes. #67 is why "or at the sign-off" is in
|
|
1959
|
+
that sentence: R4's argument is ABOUT the sign-off, and the
|
|
1960
|
+
exclusion had never reached it. An ATTENDED run can still approve a
|
|
1961
|
+
spawn live,
|
|
1962
|
+
which is a per-call human decision and exactly what the gate is for.
|
|
1963
|
+
The child then runs headless with nothing granted, since
|
|
1964
|
+
spawn_subagent forwards a grant only alongside a permission_channel.
|
|
1965
|
+
|
|
1966
|
+
#### `tool_approvals.pin` -- ships `false`
|
|
1967
|
+
|
|
1968
|
+
§21/D26: pin does NOT require approval, and the asymmetry with
|
|
1969
|
+
remember (§21b) is the decision. They differ on the axis that already
|
|
1970
|
+
separates `read` from `write` -- pin is thread-scoped and reversible,
|
|
1971
|
+
while remember writes something that outlives the thread and silently
|
|
1972
|
+
shapes conversations the user has not started yet.
|
|
1973
|
+
|
|
1974
|
+
Consequence, named rather than discovered: this is what lets pin work
|
|
1975
|
+
on the CLI and inside a research pass, where an approval-gated tool
|
|
1976
|
+
is not merely denied but not advertised at all (§13).
|
|
1977
|
+
|
|
1978
|
+
#### `tool_approvals.unpin` -- ships `false`
|
|
1979
|
+
|
|
1980
|
+
§21/D26, batch 16 (#89). Ungated for pin's reasons, and now genuinely
|
|
1981
|
+
symmetric: releasing protection costs context budget in a
|
|
1982
|
+
conversation the user is watching, exactly like applying it.
|
|
1983
|
+
|
|
1984
|
+
#### `tool_approvals.remember` -- ships `true`
|
|
1985
|
+
|
|
1986
|
+
§21b/D26, and the asymmetry with pin above IS the decision. A
|
|
1987
|
+
memory outlives its thread and silently shapes conversations the
|
|
1988
|
+
user has not started yet, so it is persistent and invisible at the
|
|
1989
|
+
moment it matters -- the same axis that separates write from read.
|
|
1990
|
+
|
|
1991
|
+
Consequence: unreachable on any headless path, which includes every
|
|
1992
|
+
research pass. That is deliberate (§21's consequence 1) and is
|
|
1993
|
+
reinforced by the tool's GRANT_NEVER policy (M17, carried by R13),
|
|
1994
|
+
because a grant would otherwise route around it.
|
|
1995
|
+
|
|
1996
|
+
#### `tool_approvals.read_project_doc` -- ships `false`
|
|
1997
|
+
|
|
1998
|
+
§24 (I2): no approval. Reading the project's own documentation, at the
|
|
1999
|
+
user's explicit request, on the files the manifest already listed to
|
|
2000
|
+
them, is not an escalation -- and a gate here would mean a dozen
|
|
2001
|
+
prompts for one /init, which is the shape of consent that gets clicked
|
|
2002
|
+
through. The confinement in project_docs.py is the control.
|
|
2003
|
+
|
|
2004
|
+
#### `tool_approvals.write_project_doc` -- ships `true`
|
|
2005
|
+
|
|
2006
|
+
§24 (I1): gated, on the same axis that separates `read` from `write`.
|
|
2007
|
+
This writes a file into the user's project that is then injected into
|
|
2008
|
+
future prompts, and it invalidates the D17 trust hash as it goes.
|
|
2009
|
+
/init supplies the approval itself, as the yes to a rendered diff --
|
|
2010
|
+
so the gate is what makes "no silent overwrite" (§24 AC2) structural
|
|
2011
|
+
rather than a promise the command makes about itself.
|
|
2012
|
+
|
|
2013
|
+
#### `tool_approvals.ask_user` -- ships `false`
|
|
2014
|
+
|
|
2015
|
+
§23 slice 2 (J12): UNGATED. Two reasons, and the second is the one
|
|
2016
|
+
that decides it. Gating would mean approving a prompt in order to be
|
|
2017
|
+
shown a prompt -- but worse, §13 does not merely deny a gated tool
|
|
2018
|
+
where nothing can ask, it stops ADVERTISING it. Gated, this tool would
|
|
2019
|
+
be invisible in every headless run; §24 AC2 requires it be visible,
|
|
2020
|
+
called, and answered with a denial the model can work around. Asking
|
|
2021
|
+
a person is not an action that needs authorising -- it is the least
|
|
2022
|
+
unilateral thing a run can do.
|
|
2023
|
+
|
|
2024
|
+
#### `tool_approvals.todo_write` -- ships `false`
|
|
2025
|
+
|
|
2026
|
+
§23 slice 2 (J9): UNGATED, on the axis that already separates `pin`
|
|
2027
|
+
from `remember`. A todo list is thread-scoped and reversible, and
|
|
2028
|
+
rewriting it costs some prompt budget inside a conversation the user
|
|
2029
|
+
can see. Gating it would also make it invisible in every research pass
|
|
2030
|
+
(§13), which is where a checklist across ten passes helps most.
|