@yahyahammad/venastine 0.2.0 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
package/config.py CHANGED
@@ -1,1198 +1,95 @@
1
- import os
2
- from dataclasses import dataclass
3
-
4
- # --- Model / loop settings -- these were missing; call_model, RunAgentLoop,
5
- # and database.py all depend on them ---
6
- MODEL_NAME = os.environ.get("AGENT_MODEL", "claude-sonnet-5")
7
- # Per-call output ceiling. Raised from 4096 in ROADMAP_v2 §16: on current
8
- # Anthropic models max_tokens caps THINKING PLUS RESPONSE TEXT together, so
9
- # 4096 truncated answers mid-sentence as soon as reasoning effort was
10
- # enabled. There is no default cumulative budget for it to interact with any
11
- # more (batch 27, #4): spend is uncapped unless settings.json
12
- # max_token_budget says otherwise.
13
- MAX_TOKENS = 16_000
14
- # --- Loop control ---
15
- # Raised from 20 in batch 16 (#45): this is THE default step ceiling -- the
16
- # `or config.MAX_ITERATIONS` fallback at every agent-shaped call site, the
17
- # value an invalid `max_steps:` frontmatter field is repaired to, and the
18
- # ceiling of every chat turn and research pass that does not name its own.
19
- MAX_ITERATIONS = 50
20
-
21
- # --- Subagents (ROADMAP_v2 §18) ---
22
- # Maximum spawn_subagent nesting. The counter lives on
23
- # ToolContext.subagent_depth; this is the value it is checked against (C3).
24
- SUBAGENT_MAX_DEPTH = 2
25
-
26
- # --- Deep research pipeline ---
27
- MAX_PIPELINE_RETRIES = 2 # max revise/re-validate loop iterations per claim before fallback
28
- MAX_JSON_RETRIES = 2 # max corrective follow-up attempts when a pass returns malformed JSON
29
- # (total attempts per pass = MAX_JSON_RETRIES + 1). See ROADMAP §3.
30
-
31
- # --- Spend cap (batch 27, #4) ---
32
- # There is NO default spend ceiling any more. The loop's cumulative
33
- # input+output counter is a BILLING meter -- the prompt is re-sent and
34
- # re-billed on every step of a tool-using turn, so it grows quadratically
35
- # in steps, which is correct as billing and meaningless as a size limit.
36
- # Reading it as "how large may a thread get" is the defect TECHNICAL_DEBT
37
- # item 9 recorded; size reasoning reads ModelResponse.turn_new_tokens and
38
- # memory.last_input_tokens now, and compaction keys off measured context
39
- # size (it never keyed off this number).
40
- #
41
- # A user who wants a hard ceiling sets settings.json `max_token_budget`
42
- # (int tokens per _run() invocation -- one user turn, one research pass,
43
- # one /init run). core/config_loader.spend_cap() resolves it, and the
44
- # headroom advisory in effective_compaction() speaks only when a cap is
45
- # configured. Hard limits at the provider remain the stronger instrument:
46
- # they see the same bill and cannot be forgotten by a code path. The three
47
- # constants this file used to carry (MAX_TOKEN_BUDGET 250k,
48
- # RESEARCH_PASS_TOKEN_BUDGET 1M for passes, INIT_TOKEN_BUDGET 1M) died
49
- # here -- the two 1M envelopes existed only because the 250k chat value
50
- # was misread as bounding pass context (the Pass-1-with-14-tool-calls
51
- # incident in DEVLOG), and with no default cap there is nothing to work
52
- # around.
53
-
54
- # Deferred for now (core sequential pipeline only, per current scope):
55
- # (none remaining -- ensemble_mode/ensemble_n built in ROADMAP §10,
56
- # critic_model built in ROADMAP §11)
57
-
58
- # --- Ensemble mode (ROADMAP §10, as redesigned by its revisit) ---
59
- # Run Pass 1 once per entry below, then extract the union of claims across
60
- # candidates and subtract a disagreement penalty in Pass 5. Off by default.
61
- #
62
- # DIVERSITY COMES FROM DIFFERENT MODELS, NOT DIFFERENT SAMPLING (E1). §10
63
- # originally raised `temperature` on N runs of one model. That could not work
64
- # on current Anthropic models, which reject sampling parameters outright (see
65
- # MODELS_REJECTING_SAMPLING_PARAMS), so the section was built, documented as
66
- # working, and could not execute against this harness's own default model.
67
- # ENSEMBLE_TEMPERATURE is deleted rather than repaired: it was an ABSOLUTE
68
- # value being used as though it were a raise, so what "1.0" meant differed
69
- # per provider, and so did how much diversity a run actually got.
70
- #
71
- # The deeper reason is §11's, verbatim: "a model checking its own output for
72
- # errors shares that model's blind spots." N samples of one model agree most
73
- # confidently on that model's systematic errors, which is exactly where a
74
- # research harness needs agreement to mean something. Different models do
75
- # not share blind spots, so their agreement is real evidence.
76
- #
77
- # N is len(ENSEMBLE_MODELS) -- derived, never configured separately (E3). The
78
- # denominator of a confidence score must not be able to disagree with the
79
- # roster that produced it.
80
- #
81
- # config.py ONLY, deliberately -- there is no settings.json key for this,
82
- # following CRITIC_MODEL (E2). Trusting a cloned repo already lets it pick
83
- # the provider and multiply pipeline cost; a project-tier list of N providers
84
- # is that same grant multiplied by N.
85
- #
86
- # Fewer than two DISTINCT (provider_name, model) pairs is refused, not
87
- # tolerated: one model cannot disagree with itself, so every claim would
88
- # score maximal consistency and Pass 5 would read that as confidence. That
89
- # is the original defect, and repeating the same entry N times is the way to
90
- # recreate it through this config.
91
- ENSEMBLE_MODE = False
92
- ENSEMBLE_MODELS: list[dict] | None = None
93
- # Example:
94
- # ENSEMBLE_MODELS = [
95
- # {"provider_name": "ANTHROPIC", "model": "claude-opus-5"},
96
- # {"provider_name": "OPENAI", "model": "gpt-5.1"},
97
- # {"provider_name": "GOOGLE", "model": "gemini-2.5-pro"},
98
- # ]
99
-
100
- # --- Sampling-parameter support (ROADMAP_v2 §16 prerequisite) ---
101
- # Models that reject temperature/top_p/top_k. Current Anthropic models
102
- # removed these parameters outright (any value returns HTTP 400); Sonnet 5
103
- # rejects non-default values. Steering is expected to happen through
104
- # prompting and MODEL_EFFORT_LEVELS instead.
105
- #
106
- # A static table rather than a capability query: the Models API capability
107
- # tree does not report sampling support, so unlike effort levels (which ARE
108
- # queryable, see MODEL_EFFORT_LEVELS) there is nothing to ask. Same posture
109
- # as §21's MODEL_CONTEXT_WINDOWS -- honest about being incomplete, and
110
- # incompleteness is safe here because the failure is a loud 400, not a
111
- # silent wrong answer.
112
- MODELS_REJECTING_SAMPLING_PARAMS = frozenset({
113
- "claude-fable-5",
114
- "claude-mythos-5",
115
- "claude-opus-5",
116
- "claude-opus-4-8",
117
- "claude-opus-4-7",
118
- "claude-sonnet-5",
119
- })
120
-
121
- # --- Critic-model routing (ROADMAP §11) ---
122
- # Route the critic/grounding passes (3a, 3b, 6c) to a different model than
123
- # the generator, so a model isn't checking its own output for errors.
124
- # None means every pass uses the same provider/model — no special routing.
125
- # Example to enable: {"provider_name": "OPENAI", "model": "gpt-5.1"}
126
- CRITIC_MODEL: dict | None = None
127
-
128
- # --- Embedder routing (ROADMAP_v2 §45, SQ2/SQ7) ---
129
- # The model that turns a claim and a source passage into vectors, so
130
- # `similarity_score` is a cosine rather than a self-report. None -- the
131
- # default -- means the pipeline warns once at launch and falls back to the
132
- # grounding model's own number, under source_grounding.md's anchored
133
- # rubric.
134
- #
135
- # `config.py` ONLY, with no settings.json key, following CRITIC_MODEL and
136
- # ENSEMBLE_MODELS (E2): choosing a provider is a grant, and this one sends
137
- # claim text and fetched page text to whoever is named. `/embedder` writes
138
- # to the user-tier store in core/pipeline_models.py, which OUTRANKS this.
139
- # Example: {"provider_name": "OPENAI", "model": "text-embedding-3-small"}
140
- EMBEDDER_MODEL: dict | None = None
141
-
142
- # Asymmetric embedders score materially worse without their prefixes and
143
- # produce NO ERROR AT ALL when they are missing, which is why this is a
144
- # table rather than something inferred. Keyed by a substring of the model
145
- # slug, longest match wins; a model matching nothing gets no prefix, which
146
- # is correct for every symmetric embedder (OpenAI's, Cohere's, Voyage's).
147
- #
148
- # `task_type` is Google's equivalent and is ignored by every other
149
- # provider. Incomplete on purpose: an unlisted asymmetric model scores
150
- # lower than it should, which is visible in the artifact as a low cosine
151
- # on a source that plainly matches -- and adding a row is the fix.
152
- # Raw cosine is NOT a 0-1 score, and treating it as one is the quiet way
153
- # to publish a wrong number. Unrelated text sits near 0.1 on some models
154
- # and above 0.7 on others, so the same passage would score "irrelevant" on
155
- # one embedder and "supports the claim" on another. This maps the useful
156
- # band onto 0-1: below `floor` is noise, above `ceiling` is as close as
157
- # that model gets.
158
- #
159
- # Keyed by a substring of the model slug, longest match wins; anything
160
- # unlisted takes DEFAULT_SIMILARITY_CALIBRATION. The RAW cosine is always
161
- # recorded beside the calibrated score, so a bad row here is visible in
162
- # the artifact and fixable after the fact rather than baked in.
163
- SIMILARITY_CALIBRATION: dict[str, dict] = {
164
- "text-embedding-3": {"floor": 0.10, "ceiling": 0.65},
165
- "text-embedding-ada": {"floor": 0.70, "ceiling": 0.92},
166
- "e5-": {"floor": 0.70, "ceiling": 0.92},
167
- "multilingual-e5": {"floor": 0.70, "ceiling": 0.92},
168
- "bge-": {"floor": 0.55, "ceiling": 0.85},
169
- "gte-": {"floor": 0.55, "ceiling": 0.88},
170
- "nomic-embed": {"floor": 0.40, "ceiling": 0.80},
171
- "embed-english": {"floor": 0.25, "ceiling": 0.80},
172
- "voyage": {"floor": 0.35, "ceiling": 0.85},
173
- "gemini-embedding": {"floor": 0.35, "ceiling": 0.85},
174
- }
175
-
176
- DEFAULT_SIMILARITY_CALIBRATION = {"floor": 0.25, "ceiling": 0.85}
177
-
178
- EMBEDDER_PREFIXES: dict[str, dict] = {
179
- "e5-": {"query": "query: ", "passage": "passage: "},
180
- "multilingual-e5": {"query": "query: ", "passage": "passage: "},
181
- "bge-": {"query": "Represent this sentence for searching relevant passages: ",
182
- "passage": ""},
183
- "gte-": {"query": "", "passage": ""},
184
- "nomic-embed": {"query": "search_query: ", "passage": "search_document: "},
185
- "gemini-embedding": {"query_task_type": "RETRIEVAL_QUERY",
186
- "passage_task_type": "RETRIEVAL_DOCUMENT"},
187
- "text-embedding-004": {"query_task_type": "RETRIEVAL_QUERY",
188
- "passage_task_type": "RETRIEVAL_DOCUMENT"},
189
- }
190
-
191
- # --- Source authority: domain classes (ROADMAP_v2 §45, SQ4) ---
192
- # What a source is worth before anything is known about the specific page.
193
- # Two tables, deliberately: a CLASS carries the number, and a SUFFIX names
194
- # which class a host belongs to. A user who thinks preprints deserve more
195
- # edits one number; a user adding their field's own trusted domain edits a
196
- # membership. One combined {suffix: score} table would make the first of
197
- # those a find-and-replace across a hundred rows.
198
- #
199
- # THE SIGNAL IS A RESTRICTED REGISTRY, NOT A FAMILIAR SUFFIX. `.gov`,
200
- # `.mil`, `.int` and `.edu` gate registration -- you cannot buy one -- and
201
- # so do `gov.uk`, `ac.uk`, `gc.ca` and their equivalents worldwide, which
202
- # is why source_scoring derives the `<kind>.<cc>` forms rather than
203
- # enumerating them here. `.org` gates nothing at all and never has, so it
204
- # sits barely above `.com`; treating it as trustworthy is the single most
205
- # common version of this mistake.
206
- #
207
- # INCOMPLETE ON PURPOSE, and safe when incomplete: an unlisted host takes
208
- # DEFAULT_DOMAIN_AUTHORITY, which is the generic-commercial number. The
209
- # failure mode is a good source scored ordinary, never a bad source scored
210
- # authoritative, and the model's bounded adjustment (below) is the route
211
- # for the first.
212
- DOMAIN_AUTHORITY_CLASSES: dict[str, float] = {
213
- "restricted_registry": 0.90, # .gov .mil .int .edu, gov.uk, ac.uk...
214
- "intergovernmental": 0.90, # WHO, UN, World Bank, OECD, EU
215
- "standards_body": 0.88, # IETF, W3C, ISO, NIST, IEC
216
- "peer_reviewed_publisher": 0.85,
217
- "established_news": 0.65,
218
- "preprint_server": 0.60, # not peer reviewed; §45 SQ5 refines this
219
- "reference_tertiary": 0.55, # encyclopaedias -- a pointer to a source
220
- "generic_org": 0.55, # an unrestricted registry, small bump
221
- "generic_commercial": 0.45,
222
- "blog_platform": 0.30,
223
- "forum_qa": 0.25,
224
- "social_media": 0.15,
225
- "content_farm": 0.10,
226
- }
227
-
228
- DEFAULT_DOMAIN_AUTHORITY = 0.45 # == generic_commercial, for an unknown host
229
-
230
- # host suffix -> class. Longest suffix wins, so `blogs.nature.com` can be
231
- # listed separately from `nature.com` if it ever needs to be.
232
- DOMAIN_AUTHORITY_SUFFIXES: dict[str, str] = {
233
- # Restricted registries. The bare TLDs; the `<kind>.<cc>` second-level
234
- # forms are derived in source_scoring.py rather than listed.
235
- "gov": "restricted_registry",
236
- "mil": "restricted_registry",
237
- "int": "restricted_registry",
238
- "edu": "restricted_registry",
239
-
240
- # Intergovernmental bodies, whose hosts are ordinary .org/.int names.
241
- "who.int": "intergovernmental",
242
- "un.org": "intergovernmental",
243
- "europa.eu": "intergovernmental",
244
- "oecd.org": "intergovernmental",
245
- "imf.org": "intergovernmental",
246
- "worldbank.org": "intergovernmental",
247
- "iaea.org": "intergovernmental",
248
-
249
- # Standards bodies.
250
- "ietf.org": "standards_body",
251
- "rfc-editor.org": "standards_body",
252
- "w3.org": "standards_body",
253
- "iso.org": "standards_body",
254
- "iec.ch": "standards_body",
255
- "ieee.org": "standards_body",
256
- "unicode.org": "standards_body",
257
- "ecma-international.org": "standards_body",
258
-
259
- # Peer-reviewed publishers and indexes.
260
- "nature.com": "peer_reviewed_publisher",
261
- "science.org": "peer_reviewed_publisher",
262
- "sciencemag.org": "peer_reviewed_publisher",
263
- "nejm.org": "peer_reviewed_publisher",
264
- "thelancet.com": "peer_reviewed_publisher",
265
- "bmj.com": "peer_reviewed_publisher",
266
- "cell.com": "peer_reviewed_publisher",
267
- "pnas.org": "peer_reviewed_publisher",
268
- "sciencedirect.com": "peer_reviewed_publisher",
269
- "springer.com": "peer_reviewed_publisher",
270
- "link.springer.com": "peer_reviewed_publisher",
271
- "onlinelibrary.wiley.com": "peer_reviewed_publisher",
272
- "wiley.com": "peer_reviewed_publisher",
273
- "tandfonline.com": "peer_reviewed_publisher",
274
- "sagepub.com": "peer_reviewed_publisher",
275
- "acm.org": "peer_reviewed_publisher",
276
- "aps.org": "peer_reviewed_publisher",
277
- "acs.org": "peer_reviewed_publisher",
278
- "plos.org": "peer_reviewed_publisher",
279
- "frontiersin.org": "peer_reviewed_publisher",
280
- "mdpi.com": "peer_reviewed_publisher",
281
- "jstor.org": "peer_reviewed_publisher",
282
- "pubmed.ncbi.nlm.nih.gov": "peer_reviewed_publisher",
283
-
284
- # Preprint servers and repositories -- not peer reviewed.
285
- "arxiv.org": "preprint_server",
286
- "biorxiv.org": "preprint_server",
287
- "medrxiv.org": "preprint_server",
288
- "chemrxiv.org": "preprint_server",
289
- "ssrn.com": "preprint_server",
290
- "papers.ssrn.com": "preprint_server",
291
- "osf.io": "preprint_server",
292
- "researchsquare.com": "preprint_server",
293
- "semanticscholar.org": "preprint_server",
294
-
295
- # News organisations with a correction policy and a masthead. An
296
- # ALLOWLIST, because "news site" is not a property of a domain suffix
297
- # and the alternative is scoring every .com that publishes articles.
298
- "reuters.com": "established_news",
299
- "apnews.com": "established_news",
300
- "bbc.com": "established_news",
301
- "bbc.co.uk": "established_news",
302
- "ft.com": "established_news",
303
- "economist.com": "established_news",
304
- "nytimes.com": "established_news",
305
- "washingtonpost.com": "established_news",
306
- "wsj.com": "established_news",
307
- "theguardian.com": "established_news",
308
- "npr.org": "established_news",
309
- "pbs.org": "established_news",
310
- "bloomberg.com": "established_news",
311
- "nikkei.com": "established_news",
312
- "afp.com": "established_news",
313
- "dw.com": "established_news",
314
-
315
- # Tertiary references -- they summarise sources rather than being one.
316
- "wikipedia.org": "reference_tertiary",
317
- "wikimedia.org": "reference_tertiary",
318
- "wiktionary.org": "reference_tertiary",
319
- "britannica.com": "reference_tertiary",
320
-
321
- "org": "generic_org",
322
-
323
- # Blog and newsletter platforms: the host says nothing about the author.
324
- "medium.com": "blog_platform",
325
- "substack.com": "blog_platform",
326
- "wordpress.com": "blog_platform",
327
- "blogspot.com": "blog_platform",
328
- "blogger.com": "blog_platform",
329
- "tumblr.com": "blog_platform",
330
- "wixsite.com": "blog_platform",
331
- "ghost.io": "blog_platform",
332
-
333
- # Forums and Q&A. Often correct, never attributable.
334
- "reddit.com": "forum_qa",
335
- "quora.com": "forum_qa",
336
- "stackexchange.com": "forum_qa",
337
- "stackoverflow.com": "forum_qa",
338
- "news.ycombinator.com": "forum_qa",
339
- "4chan.org": "content_farm",
340
-
341
- # Social media. Speculation and unattributed claims travel here fastest,
342
- # which is the whole reason a claim needs grounding elsewhere.
343
- "x.com": "social_media",
344
- "twitter.com": "social_media",
345
- "facebook.com": "social_media",
346
- "instagram.com": "social_media",
347
- "tiktok.com": "social_media",
348
- "threads.net": "social_media",
349
- "linkedin.com": "social_media",
350
- "mastodon.social": "social_media",
351
- "bsky.app": "social_media",
352
- "youtube.com": "social_media",
353
- "vk.com": "social_media",
354
- "weibo.com": "social_media",
355
- "t.me": "social_media",
356
-
357
- # Aggregators that republish without attribution, and image boards with
358
- # no text to ground anything in. The measured case: a Pinterest pin
359
- # scored similarity 1.0 on a Nobel Prize claim.
360
- "pinterest.com": "content_farm",
361
- "answers.com": "content_farm",
362
- "ehow.com": "content_farm",
363
- "scribd.com": "content_farm",
364
- "coursehero.com": "content_farm",
365
- "chegg.com": "content_farm",
366
- }
367
-
368
- # How far the model may move a computed authority, in either direction
369
- # (§45, SQ4). Small on purpose: it is a correction for what a domain
370
- # cannot see -- a primary source on an ordinary host, an opinion column on
371
- # a masthead -- not a second opinion about the number. An adjustment
372
- # arriving without a reason is discarded rather than clamped.
373
- AUTHORITY_ADJUSTMENT_CAP = 0.15
374
-
375
- # --- The sources/ artifact (ROADMAP_v2 §45, SQ8) ---
376
- # Whether output/<run_id>/sources/ keeps the TEXT each cited page served,
377
- # or only its hash, size and provenance.
378
- #
379
- # On by default, because it is what makes a similarity score reproducible
380
- # after the run -- and the directory output_writer has created since §12
381
- # was described by fetch_url.py's own comment for just as long. Everything
382
- # written there has been through redact_output_text on entry to the
383
- # corpus.
384
- #
385
- # It is new data at rest, so it has a switch and PRIVACY.md says what it
386
- # holds. Turning it off costs the audit trail, not the scores: the corpus
387
- # still exists in memory for the run that computes them.
388
- PERSIST_SOURCE_TEXT = True
389
-
390
- # --- Scholarly authority: OpenAlex (ROADMAP_v2 §45, SQ5/SQ9) ---
391
- # OFF BY DEFAULT. This is the first network call in this harness made by
392
- # something that is not a registered tool, so it bypasses the approval
393
- # registry and granted_calls.json -- and an out-of-the-box run must make
394
- # no call the user did not ask for. With it off, a paper takes its
395
- # preprint-server or publisher domain class and nothing else.
396
- SCHOLAR_LOOKUP = False
397
-
398
- SCHOLAR_API_URL = "https://api.openalex.org"
399
- SCHOLAR_TIMEOUT_S = 8.0
400
- SCHOLAR_MAX_RETRIES = 2
401
- SCHOLAR_CACHE_TTL_S = 900
402
-
403
- # OpenAlex asks for a contact address to put a caller in its "polite pool"
404
- # (higher rate limits). EMPTY BY DEFAULT AND NEVER DERIVED: an address is
405
- # personal data, and sending one the user did not type -- from a git
406
- # config, an environment variable, anywhere -- is not a rate-limit
407
- # optimisation, it is an unasked-for disclosure.
408
- SCHOLAR_MAILTO = ""
409
-
410
- # How a paper's score is composed. Renormalised over whichever terms are
411
- # actually available, so a paper too young to have a citation percentile
412
- # is not scored as though it had a bad one.
413
- SCHOLAR_VENUE_WEIGHT = 0.40
414
- SCHOLAR_CITATION_WEIGHT = 0.40
415
- SCHOLAR_AUTHOR_WEIGHT = 0.20
416
-
417
- # Venue credit. A preprint scores lower than a comparable published paper
418
- # -- generally, not strictly, which is why it is a weight and not a gate.
419
- SCHOLAR_VENUE_CREDIT = {
420
- "journal": 1.0,
421
- "conference": 1.0,
422
- "book series": 0.85,
423
- "repository": 0.55, # arXiv, bioRxiv, institutional repositories
424
- "unknown": 0.6,
425
- }
426
-
427
- # max h-index across a paper's authors, log-saturated. 60 is a full career
428
- # at the top of most fields; the curve is deliberately flat above it,
429
- # because the difference between 60 and 90 says more about field size and
430
- # career length than about this paper.
431
- SCHOLAR_H_SATURATION = 60
432
-
433
- # Below this many works, a field-and-year cohort is too small for a
434
- # percentile to mean anything and the window widens instead.
435
- SCHOLAR_MIN_COHORT_SIZE = 200
436
-
437
- # Below this age, citation counts are noise: 72% of computer-science
438
- # preprints from 2024 have zero citations, so a three-week-old paper's
439
- # zero says nothing at all. The term is DROPPED and the remaining weights
440
- # renormalise, rather than being scored as low impact.
441
- SCHOLAR_MIN_CITATION_AGE_DAYS = 60
442
-
443
- # A retracted paper is not evidence, whatever its venue or citation count
444
- # -- and a heavily cited retraction is the most dangerous shape there is.
445
- SCHOLAR_RETRACTED_AUTHORITY = 0.05
446
-
447
- # --- Reasoning effort (ROADMAP_v2 §16; default changed batch 25, #139) ---
448
- # The default effort level requested when the user has not chosen one.
449
- #
450
- # This shipped as None -- "send nothing", the one universally safe value,
451
- # because reasoning_effort is rejected by OpenAI-compatible NON-reasoning
452
- # models. Batch 25 changed it to "high" by owner decision: the pipeline
453
- # now consumes the setting (#139), so None meant the mode this project
454
- # exists for ran at the provider's own default forever, invisibly. The
455
- # risk the old note named is managed in MODEL_EFFORT_LEVELS rather than
456
- # by silence: known non-reasoning models are listed there with an EMPTY
457
- # level set, which effort_for() treats as authoritative and drops the
458
- # level cleanly instead of sending a parameter that would 400.
459
- DEFAULT_EFFORT: str | None = "high"
460
-
461
- # Fallback effort levels for providers whose APIs expose no capability
462
- # endpoint (every OpenAI-compatible provider, and Google). ANTHROPIC is NOT
463
- # listed here on purpose: its Models API reports per-model effort support,
464
- # so client.py queries it and new Anthropic models need no entry.
465
- #
466
- # An entry whose value is an EMPTY list means "this model takes no effort
467
- # parameter at all" and is authoritative: effort_for() DROPS the requested
468
- # level with a naming warning instead of sending it. That is the safety
469
- # mechanism behind DEFAULT_EFFORT="high" -- without these entries, the
470
- # fallback for an unknown model ASSUMES ["low","medium","high"] and the
471
- # default high would reach gpt-4o-class endpoints as a 400 on every call.
472
- # Incomplete on purpose (same posture as MODELS_REJECTING_SAMPLING_PARAMS):
473
- # an unlisted non-reasoning endpoint still fails loud, and the fix is one
474
- # line here or `--effort auto`.
475
- MODEL_EFFORT_LEVELS: dict[str, list[str]] = {
476
- "gpt-4o": [],
477
- "gpt-4o-mini": [],
478
- "gpt-4.1": [],
479
- "gpt-4.1-mini": [],
480
- "gpt-4.1-nano": [],
481
- "gpt-3.5-turbo": [],
482
- }
483
- DEFAULT_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max", "ultra"]
484
-
485
- # Google expresses reasoning depth as an integer token budget rather than an
486
- # enum, so a level has to be mapped to a number at the boundary. -1 is the
487
- # SDK's "decide dynamically" sentinel.
488
- GOOGLE_THINKING_BUDGETS = {
489
- "low": 2_048,
490
- "medium": 8_192,
491
- "high": 16_384,
492
- "xhigh": 24_576,
493
- "ultra": 32_768,
494
- "max": -1,
495
- }
496
-
497
- # --- Database ---
498
- DB_PATH = os.environ.get("APP_DB_PATH", "app.db")
499
-
500
- # --- Output artifacts ---
501
- #
502
- # BESIDE THE WORK, which since batch 44 means beside the WORKSPACE when one
503
- # was named. "State is global, artifacts are local" is the distribution
504
- # split, and the local half is only true if "local" tracks where the work
505
- # is: with AGENT_WORKSPACE pointing at a project, a run launched from the
506
- # harness checkout wrote its reports into the harness. Reading the env var
507
- # rather than WORKSPACE_DIR below, and defaulting it to ".", so this stays
508
- # one expression with no branch in it -- an unset AGENT_WORKSPACE gives
509
- # ./output exactly as before, not ./workspace/output.
510
- OUTPUT_DIR = os.environ.get(
511
- "AGENT_OUTPUT_DIR",
512
- os.path.join(os.environ.get("AGENT_WORKSPACE", "."), "output"))
513
-
514
- # --- File-ops workspace (ROADMAP §6) ---
515
- WORKSPACE_DIR = os.environ.get("AGENT_WORKSPACE", "./workspace")
516
-
517
- # Whether AGENT_WORKSPACE was NAMED, as opposed to defaulted (batch 44).
518
- #
519
- # The presence of the variable, never its value: the default "./workspace"
520
- # is a subdirectory of wherever you launched, so a value test would make
521
- # `./workspace` the project for everyone who never set anything -- which
522
- # is the whole population this must not disturb. main() reads this to
523
- # decide the project path; the decision is there, because config.py holds
524
- # plain values and this is one.
525
- WORKSPACE_DIR_EXPLICIT = "AGENT_WORKSPACE" in os.environ
526
- MAX_FILE_SIZE_BYTES = 25_000_000 # 25 MB — hard reject before opening
527
- MAX_READ_LINES = 500 # max lines per read call
528
- MAX_READ_CHARS = 50_000 # max chars per read call
529
-
530
- # --- /init (ROADMAP_v2 §24) ---
531
- INITIALIZER_AGENT = "initializer"
532
-
533
- # Three bounds, each doing a different job (I7). /init is a tool-heavy loop
534
- # over documentation that can run to hundreds of kilobytes -- this repo's own
535
- # root markdown is 721KB, with DEVLOG.md alone at 226KB.
536
- #
537
- # INIT_READ_CHARS is well below MAX_READ_CHARS because of TECHNICAL_DEBT
538
- # item 9 (now closed, batch 27): the billing meter re-counts the WHOLE
539
- # prompt on every step, so each 50KB read is re-billed for every step that
540
- # follows it. 20KB keeps a dozen reads affordable and still returns a
541
- # useful span of a document per call. It stays even though the meter no
542
- # longer caps anything by default -- it bounds per-read VOLUME, which is a
543
- # different axis from spend and from the number of reads.
544
- INIT_READ_CHARS = 20_000
545
- # The number of reads, which neither budget nor read size bounds: a model
546
- # can spend an unbounded number of small reads inside any ceiling.
547
- INIT_MAX_STEPS = 12
548
-
549
- # --- MCP teardown (ROADMAP_v2 §37 F6, #64) ---
550
- # ONE shared wall-clock budget for the whole goodbye -- polite close,
551
- # force-cancel, loop-thread join -- replacing three sequential 15-second
552
- # waits whose worst case hung a quitting harness for ~45s, Ctrl+C
553
- # included. Servers still alive when the budget expires are named in a
554
- # WARNING; their child processes may outlive this session. The value
555
- # lives with the other harness bounds and is re-exported by
556
- # mcp_client/client.py beside its sibling timeouts.
557
- TEARDOWN_BUDGET_S = 10.0
558
-
559
- # --- Shell / sandbox (ROADMAP §7) ---
560
- SHELL_BINARY = os.environ.get("AGENT_SHELL", "") # auto-detect if empty
561
- ALLOW_INSECURE_SANDBOX_FALLBACK = False # explicitly enable subprocess fallback
562
- AUTO_APPROVE_SANDBOX_FALLBACK = False # auto-approve fallback runs (no per-run prompt)
563
-
564
- # ROADMAP_v2 §28 (G3). WHICH shell commands need a human to say yes.
565
- #
566
- # "always" every command is asked about, whatever it does.
567
- # "tiered" the classifier decides -- see security/capability.py for the
568
- # one rule, and security/sandbox.py:classify_command for how a
569
- # command is measured against it.
570
- # "never" nothing is ever asked about.
571
- #
572
- # This is the gate. Before §28 the gate was ToolApprovals.shell, and
573
- # `_shell_approval_check` looked like a five-layer policy underneath it --
574
- # but four of those layers could only ever return False on the shipped
575
- # flags, so the whole thing was a pass-through for one boolean and the
576
- # harness had exactly two settings: ask about everything, or ask about
577
- # nothing. "tiered" is the rung that docstring already claimed existed.
578
- #
579
- # "never" is that second setting, preserved deliberately and now NAMED.
580
- # It is the pre-§28 `ToolApprovals.shell = False` behaviour exactly: an
581
- # inert command runs on the HOST with unrestricted arguments, so `cat
582
- # ~/.aws/credentials` returns your keys to the model. You reach that by
583
- # writing "never", not by switching off a field that reads like "stop
584
- # nagging me" -- which is the actual fix for audit #157.
585
- # The legal set lives with the code that ENFORCES it --
586
- # security/capability.APPROVAL_MODES, which validate_mode() reads. A second
587
- # copy here was read by nothing but a test asserting its literal, so the two
588
- # could have disagreed and only the unenforced one would have been wrong.
589
- SHELL_APPROVAL_MODE = "tiered"
590
- SANDBOX_DOCKER_IMAGE = os.environ.get("AGENT_SANDBOX_IMAGE", "python:3.13-slim")
591
- SANDBOX_TIMEOUT_SECONDS = 120
592
- SANDBOX_MEMORY_MB = 2048
593
- SANDBOX_CPU_SECONDS = 30
594
- SANDBOX_MAX_PIDS = 200
595
-
596
- # ---------------------------------------------------------------------------
597
- # --- Output redaction (#167/#49, batch 20) ----------------------------------
598
- # ---------------------------------------------------------------------------
599
-
600
- # The PERMANENT master switch for pattern-based redaction of what leaves a
601
- # tool: vendor token substitution and credential-shape redaction, applied
602
- # by check_output_policy() to every tool result and by param_digest() to
603
- # what the shells display of an argument. On by default; a user whose
604
- # workflow needs the model to see real values (debugging their own
605
- # credentials, say) turns it off here, or per-run with
606
- # VENASTINE_REDACT_OFF in the environment -- see redaction_enabled().
607
- #
608
- # DELIBERATELY NOT a settings.json key (decision recorded in DEVLOG,
609
- # batch 20): project tier beats user tier there, so a cloned repo could
610
- # ship `.venastine/settings.json` switching the scrubbing off behind a
611
- # trust prompt nobody reads -- the exact shape G7 rejected
612
- # shell_approval_mode for and R12 rejected research.granted_tools for.
613
- # Permanent means editing this line.
614
- #
615
- # NEVER covers three things, whatever this is set to: check_input_policy's
616
- # refusals (a denial is legible, not destructive); check_output_policy's
617
- # depth-cap substitution (fail-closed structure bound -- making it optional
618
- # would recreate the deterministic bypass its comment forbids); and
619
- # logging_setup.py's formatter redaction (the second sink keeps its own
620
- # guard).
621
- REDACT_TOOL_OUTPUTS = True
622
-
623
- # ROADMAP_v2 §31 (H9). The wall clock on a BUDGET_COMPUTE tool call --
624
- # the six math tools, which are pure functions of their params and have
625
- # nothing bounding them from the inside. dispatch runs them in a
626
- # killable subprocess under this budget (tools/isolation.py).
627
- #
628
- # 15s is chosen against measurement, not taste. The slowest LEGITIMATE
629
- # call found is `symbolic_math series order=1000` at 3.44s, so this is
630
- # roughly 4x headroom; the runaways it exists for do not return at all.
631
- # Ten passes each burning a full budget is 150s rather than forever,
632
- # which is the trade being made.
633
- #
634
- # ONE number, not one per tool: there is no evidence any two math tools
635
- # want different answers, and a per-tool budget makes each a judgement
636
- # call at the registration site. It sits beside SANDBOX_TIMEOUT_SECONDS
637
- # because that is the constant a reader would compare it against.
638
- TOOL_COMPUTE_TIMEOUT_S = 20
639
-
640
- # WARNING: commands matching these words get network access inside the
641
- # sandbox. A compromised package or script can exfiltrate data or
642
- # download payloads. Only add commands you trust.
643
- NETWORK_ALLOWED_COMMANDS = [
644
- "pip", "pip3", "curl", "wget", "git",
645
- "npm", "yarn", "pnpm", "apt", "apt-get",
646
- "yum", "dnf", "brew", "cargo",
647
- ]
648
-
649
- # WARNING: inert commands run WITHOUT filesystem isolation — they can
650
- # read files outside the workspace (e.g. cat /etc/passwd). They are
651
- # read-only inspection commands; the risk is information disclosure,
652
- # not modification.
653
- INERT_COMMANDS = [
654
- "ls", "cat", "pwd", "echo", "grep", "wc",
655
- "head", "tail", "date", "whoami", "uname", "which",
656
- "where", "type", "file", "stat", "du", "df", "tree",
657
- "uniq", "diff", "md5sum", "sha256sum",
658
- ]
659
-
660
-
661
- # ROADMAP_v2 §25 (R6). Ceiling on how many PRE-GRANTED tool calls one
662
- # research run may make without being asked again. Counts granted calls
663
- # only -- web_search, arxiv_search and every math tool are approval-free
664
- # and never touch it, so this is not a cap on tool use.
665
- #
666
- # Pre-flight authorization trades a per-call decision for one up-front
667
- # decision, and the thing it gives up is the natural bound on how many
668
- # times the granted tool runs. Set generously: the ceiling exists to stop
669
- # an injected loop spending the whole authorization unattended, not to
670
- # ration ordinary work across ten passes.
671
- MAX_GRANTED_TOOL_CALLS = 150
672
-
673
- # ROADMAP_v2 §25 (R9). How long an attended research run waits for a human
674
- # to answer one approval prompt before DENYING that call and carrying on.
675
- #
676
- # Denial is the safe direction, and continuing is the useful one: walking
677
- # away from an attended run degrades it rather than wedging it, so nine
678
- # completed passes are not lost to one unanswered question. Generous by
679
- # default because the whole point of the mode is that someone is there.
680
- ATTENDED_APPROVAL_TIMEOUT_S = 600
681
-
682
-
683
- # ROADMAP_v2 §20 (D9). Whether a finished research run gets a reviewer pass
684
- # over its own output. Off by default: it is one more model call plus a
685
- # re-synthesis whenever a correction is accepted, and it needs someone
686
- # present to consent to anything it changes.
687
- SUBAGENT_REVIEW = False
688
-
689
- # §20 (V4). Ceiling on how many findings one review may put to the user.
690
- # Consent fatigue is the failure mode a mutating review stage has and a
691
- # read-only one does not: the fiftieth prompt gets answered differently
692
- # from the first, and an injected "correction" only needs one reflexive
693
- # yes. Findings past the cap are dropped and the drop is TRACED -- a
694
- # silent truncation would read as "the reviewer found twelve things".
695
- MAX_REVIEW_FINDINGS = 25
696
-
697
- # §20 (V5). How many times one finding may be sent back for refinement.
698
- # A human asks for each round, so this is not a runaway guard -- it bounds
699
- # the case where the reviewer keeps producing a proposal that misses the
700
- # same point, which is when the honest answer is to reject it.
701
- MAX_REVIEW_REFINEMENTS = 3
702
-
703
-
704
- # ---------------------------------------------------------------------------
705
- # --- Compaction (ROADMAP_v2 §21) -------------------------------------------
706
- # ---------------------------------------------------------------------------
707
- #
708
- # D27: these are DEFAULTS, not settings. Every value is a starting point
709
- # chosen to be reasonable and explicitly not claimed to be right, and every
710
- # one is overridable through the existing settings mechanism -- config.py
711
- # default -> user ~/.config/venastine/settings.json -> trusted project
712
- # .venastine/settings.json -> a per-invocation `/compact --strength N`.
713
- # The architecture is what's locked; the numbers are expected to move once
714
- # there are real long threads to look at.
715
-
716
- # How much of the model's context window a thread may fill before
717
- # compaction folds it. thresholds() multiplies this by context_limit(),
718
- # so it is 850k on a 1M model and 170k on a 200k one.
719
- #
720
- # BATCH 44 REVERSED M1, AND THE REASON M1 GAVE HAS EXPIRED. M1 rejected a
721
- # window-derived trigger because "a window-derived trigger sits at a size
722
- # the thread can never reach in working order" -- and the arithmetic
723
- # behind that was about MAX_TOKEN_BUDGET, then a default spend ceiling of
724
- # 250k: the prompt is re-sent on every step of a tool-using turn, so a
725
- # thread at 160k got one response and no tool calls before the cap ended
726
- # the turn. Batch 27 DELETED that default ceiling. There is no cap for a
727
- # large trigger to collide with any more, so the premise is gone and the
728
- # flat 40k outlived it -- compacting a 1M-window thread at 4% of its
729
- # window, spending a model call and losing fidelity to solve a problem
730
- # the model did not have.
731
- #
732
- # THE COST OF THE REVERSAL, STATED. MODEL_CONTEXT_WINDOWS and the provider
733
- # query decide when every thread folds now, where under M1 a wrong entry
734
- # only mistimed a research backstop. That is why core/model_windows.py
735
- # exists (the user's own answer, outranking both) and why the fallback
736
- # still WARNS. A fraction rather than `window - margin`: a fixed margin
737
- # that is right for a 1M model leaves a 64k model no working room at all,
738
- # and one that is right for 64k never fires on 1M.
739
- COMPACTION_TRIGGER_FRACTION = 0.85
740
-
741
- # The trigger used when NO MODEL IS IN SCOPE -- and the default
742
- # settings.json's `compaction.trigger_tokens` overrides.
743
- #
744
- # One caller has no (provider, model) to derive a window from:
745
- # compaction.pin_measurements, which computes #89's cap as
746
- # PIN_MAX_TRIGGER_FRACTION x the trigger from a thread id alone. Left at
747
- # 40_000 deliberately, so the pin cap is exactly what it was before batch
748
- # 44 -- this batch changes when a thread compacts, not how much of one a
749
- # single pin may freeze, and a cap that grew with the window would let one
750
- # `pin` call freeze 425k tokens of a 1M-window thread.
751
- COMPACTION_TRIGGER_TOKENS = 40_000
752
-
753
- # Fires this many tokens BEFORE the trigger, so there is room to do
754
- # something about it -- pin a message, wrap up a thought, run /compact at a
755
- # natural break.
756
- #
757
- # STILL ABSOLUTE after batch 44, and that is a decision rather than an
758
- # oversight. What this buys is a HUMAN'S REACTION TIME, measured in turns,
759
- # and a turn does not get bigger because the window did: 8k is roughly a
760
- # turn or two of notice on a 64k model and on a 1M one alike. As a
761
- # fraction of the new trigger it would be 128k on a 1M model -- a warning
762
- # that fires while the thread is at 72% and has nothing to worry about
763
- # yet. §21 singles this out as the one value whose wrong setting
764
- # is not self-correcting: too small and it is an alert with no time
765
- # attached to it. Validated to be strictly less than the trigger.
766
- COMPACTION_WARNING_MARGIN_TOKENS = 8_000
767
-
768
- # The most recent tokens that always stay verbatim, never compacted.
769
- #
770
- # ABSOLUTE, like the warning margin above and for the same kind of reason:
771
- # this is an amount of CONVERSATION to keep intact, not a share of a
772
- # window. It is also the weaker of the two floors in practice -- M5 keeps
773
- # whichever protects more, and the three-turn floor below almost always
774
- # protects more than 4k on the long threads that reach the trigger at all.
775
- # Left where it was so batch 44 changes when a thread folds and not what
776
- # survives the fold.
777
- COMPACTION_KEEP_RECENT_TOKENS = 4_000
778
-
779
- # M5: a FLOOR in turns, on top of the token floor above, and the two
780
- # compose -- whichever protects more wins, plus the current turn, which is
781
- # never foldable at all. A single tool-heavy turn can consume the whole
782
- # keep-token budget by itself, leaving the immediately preceding exchange
783
- # summarized; a follow-up like "no, the other one" then has no referent.
784
- COMPACTION_KEEP_RECENT_TURNS = 3
785
-
786
- # #89 (batch 16). The most one `pin` call may protect, as a fraction of
787
- # the trigger above. A pin is a PERMANENT FLOOR under the derived view:
788
- # pinned rows re-enter it verbatim forever (M9), nothing folds them, and
789
- # before this cap one ungated call with last_n=40 could put a thread
790
- # permanently past the trigger with no unpin to undo it. 0.5 leaves room
791
- # for a real working session while making "floor the trigger by yourself"
792
- # structurally impossible. Enforced at the tool with a REFUSAL that states
793
- # the cap and the current share -- never silently trimmed (M15's rule: a
794
- # pin asked for more protection than allowed must not quietly deliver less).
795
- PIN_MAX_TRIGGER_FRACTION = 0.5
796
-
797
- # 1-5, mapping to the target compression ratios below.
798
- COMPACTION_STRENGTH = 3
799
-
800
- # Bounded corrective retries when the compactor misses its target ratio.
801
- COMPACTION_MAX_RETRIES = 2
802
-
803
- # §21: strength is an objectively measurable target, not a qualitative
804
- # instruction. "Be more aggressive" behaves differently across models with
805
- # different summarization tendencies and no amount of prompting fixes that;
806
- # a ratio is checkable after the fact. Qualitative guidance still belongs
807
- # in the compactor's prompt, shaping WHAT survives within the budget.
808
- COMPACTION_TARGET_RATIOS = {1: 0.40, 2: 0.25, 3: 0.15, 4: 0.10, 5: 0.05}
809
-
810
- # How far outside the target a summary may land before it is sent back.
811
- # Under-shooting is not an error: a summary tighter than asked for has
812
- # already done the job, and rejecting it would spend a second call to make
813
- # the context bigger.
814
- COMPACTION_RATIO_TOLERANCE = 0.5
815
-
816
- # M2 as amended by batch 16 (#90, owner decision). Two strategies:
817
- #
818
- # "chain" summarizes the PREVIOUS SUMMARY plus whatever followed it.
819
- # Constant cost per compaction forever -- the input never
820
- # grows past summary-plus-tail -- at the price of loss that
821
- # compounds over a long-lived thread (a summary of a summary
822
- # of a ...).
823
- # "rederive" summarizes the ORIGINAL messages every time, so exactly
824
- # one summarization step always sits between an original
825
- # message and what the model sees. Fidelity-optimal; input
826
- # grows with the covered span.
827
- #
828
- # The DEFAULT is "chain", reversing M2's original choice -- an explicit
829
- # owner decision recorded in DEVLOG (batch 16): rederive's whole-span
830
- # input made every compaction the most expensive call of the turn, and
831
- # cost compounds on exactly the threads that trigger most. Whatever is
832
- # configured here, BOTH strategies fall back to chain automatically when
833
- # a span outgrows one call (built at last, after three documents promised
834
- # it for two sections), saying so in a WARNING -- and truncate the oldest
835
- # material with a stated truncation when even chain cannot fit, because
836
- # an oversized send is never the right failure direction.
837
- COMPACTION_STRATEGY = "chain"
838
- COMPACTION_STRATEGIES = ("rederive", "chain")
839
-
840
- # ROADMAP_v2 §21b (M14). Ceiling on how many durable memories reach one
841
- # prompt. Newest first, and the truncation is stated in the fragment the
842
- # model reads rather than only in a log.
843
- #
844
- # Every in-scope memory would otherwise enter every turn forever, which is
845
- # the unbounded context growth §21 exists to fight -- a memory feature that
846
- # quietly reintroduces the problem compaction solves would be a poor trade.
847
- # Recency is the ordering because it is the only staleness signal available
848
- # without asking a model, and /forget is how a still-relevant old memory
849
- # gets kept ahead of the cap.
850
- MAX_INJECTED_MEMORIES = 50
851
-
852
- # --- Catalog text (ROADMAP_v2 §32, A5) ---
853
- #
854
- # The cap on a skill's or an agent's `name` and `description` -- the
855
- # two strings that go from a .md file straight into the system prompt
856
- # of every run in a project, with no tool call and no further consent
857
- # (#131).
858
- #
859
- # 300 is headroom rather than a squeeze: the longest description this
860
- # project ships is `compactor` at 171 characters, and all eight are
861
- # single-line. A project whose description does not fit in twice the
862
- # length of ours is writing instructions, not a summary, which is
863
- # exactly the thing the cap is for.
864
- #
865
- # THE NEWLINE COLLAPSE MATTERS MORE THAN THE NUMBER, and they are one
866
- # constant because they are one rule -- see config_loader._catalog_text.
867
- # Same posture as tools/builtin/arxiv.MAX_SUMMARY_CHARS (600) and
868
- # web_search.MAX_SNIPPET_CHARS (300): model-facing text from a source
869
- # this project did not write is bounded where it is produced.
870
- MAX_CATALOG_TEXT_CHARS = 300
871
-
872
- # The agent that does the summarizing. §21: this is the shape of an agent
873
- # call -- a system prompt, a task, a judgment-based output -- so it runs
874
- # through the same RunAgentLoop as everything else rather than needing its
875
- # own LLM-calling path, and that is also what gives it real autonomy over
876
- # WHAT to preserve. Mechanical truncation cannot exercise judgment at all.
877
- COMPACTOR_AGENT = "compactor"
878
-
879
- # ROADMAP_v2 §21c. How long a whole-thread summary may be, in characters.
880
- #
881
- # ABSOLUTE, not a COMPACTION_TARGET_RATIOS entry, and the difference is the
882
- # consumer rather than the summarizer. A fold's summary REPLACES the span it
883
- # came from, so scaling with that span is right: a bigger fold earns a bigger
884
- # summary and the thread still shrinks. §21c's summary is injected as a prompt
885
- # tier present on every turn of the REFERENCING thread, where nothing it
886
- # replaces bounds it -- a 500KB thread at strength 3 would put 75KB into every
887
- # call indefinitely.
888
- #
889
- # A thread whose rendered text already fits this is stored verbatim and costs
890
- # no model call at all.
891
- SUMMARY_TARGET_CHARS = 2_000
892
-
893
- # §21c. How many referenced threads may be attached to one thread at once.
894
- #
895
- # Small on purpose, and the cap REFUSES rather than dropping the oldest: a
896
- # reference is something a person chose by name, and silently discarding one
897
- # to make room for another is exactly what §21b's "removal is by id, never by
898
- # substring" rule exists to prevent. The count and the cap are stated in the
899
- # fragment the model reads, per M14's no-silent-caps rule.
900
- MAX_INJECTED_REFS = 3
901
-
902
- # §23 slice 2. The todo list's vocabulary and its ceiling.
903
- #
904
- # A plain tuple rather than an Enum, for storage.py's THREAD_KIND_* reason: a
905
- # list persisted under an older vocabulary reads back as data rather than
906
- # raising, and the tool can then say which status it did not recognise.
907
- TODO_STATUSES = ("pending", "in_progress", "completed")
908
-
909
- # The list is injected into every turn's system prompt, so its length is a
910
- # per-call cost for as long as the thread lives. REFUSES rather than
911
- # truncating, MAX_INJECTED_REFS' rule: a checklist silently cut to 50 would
912
- # have the model believe it had recorded work it has now forgotten, which is
913
- # worse than being told to write a shorter list.
914
- MAX_TODO_ITEMS = 50
915
-
916
- # M6. A research pass is headless and unattended, and each one already
917
- # returns a distillation, so routine compaction there would spend on a
918
- # judgment call nobody is watching. Passes compact only when approaching
919
- # the model's actual context window -- a safety net against a hard provider
920
- # error mid-pipeline, not a working-set policy.
921
- COMPACTION_PIPELINE_BACKSTOP_TOKENS = 20_000
922
-
923
- # The backstop's source, the summarizer's input budget, and M1's remaining
924
- # use for a window table.
925
- #
926
- # NOW A FALLBACK, NOT THE ONLY SOURCE. This said "deliberately NOT a
927
- # per-provider API query", on the grounds that the roster of fifteen had no
928
- # uniform endpoint and a query would need fifteen adapters to avoid a
929
- # fallback constant they would all still need. The premise was measured
930
- # against the PINNED SDKs and did not survive:
931
- #
932
- # anthropic 0.116.0 ModelInfo.max_input_tokens -- on the SAME object
933
- # core/client.py already retrieves to read
934
- # capabilities.effort. The answer was in hand and
935
- # being dropped; reading it costs no extra call.
936
- # google-genai 1.0.0 types.Model.input_token_limit, one field.
937
- # openai 2.45.0 Model is declared extra="allow", so a provider's
938
- # own field survives onto .model_extra. That makes
939
- # the OpenAI-compatible side ONE alias reader --
940
- # context_window (Groq), context_length (Together,
941
- # OpenRouter, Cohere), max_context_length (Mistral)
942
- # -- rather than thirteen adapters.
943
- #
944
- # So it is two attribute reads and one sniff, not fifteen adapters. The
945
- # query lives in core/client.py:context_window_for, beside the effort query
946
- # it mirrors; core/compaction.py:context_limit prefers it and falls back
947
- # here. (The old note also corrected itself on a provider count from the
948
- # dead APICredentials class -- audit #23. Fifteen is right; the count was
949
- # never what was wrong with the argument.)
950
- #
951
- # THE CONCLUSION OUTLIVED THE PREMISE, which is why this table stays: OpenAI,
952
- # DeepSeek and Perplexity answer /models with id/created/object/owned_by and
953
- # nothing else, and Grok, Fireworks, Qwen and Z.AI publish no model-metadata
954
- # endpoint at all. A fallback constant is still needed at the end of it.
955
- #
956
- # KEYS ARE STORED NORMALIZED -- no date suffix, no `vendor/` or `region.`
957
- # prefix. core/compaction.py:_normalized reduces an incoming id to this form
958
- # before looking it up, so a dated key here would be UNREACHABLE. That is
959
- # also the bug this fixed: matching was exact, so `claude-sonnet-5-20260724`
960
- # missed a million-token entry and silently took the default.
961
- #
962
- # AN INCOMPLETE ENTRY IS EXPENSIVE NOW. Under M1 it cost a mistimed
963
- # research backstop and a mistimed summarizer input budget, because the
964
- # working-set trigger was a flat number that never consulted this. Batch 44
965
- # made that trigger a FRACTION of what context_limit() returns, so a wrong
966
- # number here mistimes compaction on every thread -- too high and the
967
- # thread never folds and the provider raises a hard context-limit error
968
- # instead. core/model_windows.py is the user's answer to that, and /window
969
- # is how they give it; this table is what answers before they do.
970
- MODEL_CONTEXT_WINDOWS: dict[str, int] = {
971
- # 1M IS THE ORDINARY WINDOW ON THESE, not a beta.
972
- #
973
- # This block used to carry the opposite claim -- that 1M was gated
974
- # behind a `context-1m-2025-08-07` header this harness does not send,
975
- # so an ordinary account got 200_000 and these entries "want to be
976
- # 200_000". That was true of the Sonnet 4 era and was never true of
977
- # the models listed here; checked against the current model reference
978
- # in batch 44, the whole 4.6-and-later family is 1M and Haiku 4.5 is
979
- # 200K. The values were right and the comment was stale, which is the
980
- # dangerous combination now that the trigger reads them: a reader
981
- # following the old note would have "corrected" five entries by a
982
- # factor of five and compacted every Claude thread at a fifth of the
983
- # window.
984
- "claude-opus-5": 1_000_000,
985
- "claude-sonnet-5": 1_000_000,
986
- "claude-fable-5": 1_000_000,
987
- "claude-opus-4-8": 1_000_000,
988
- "claude-opus-4-7": 1_000_000,
989
- "claude-opus-4-6": 1_000_000,
990
- "claude-sonnet-4-6": 1_000_000,
991
- # Dateless, per the normalization note above: this was keyed
992
- # "claude-haiku-4-5-20251001" while its five siblings were dateless,
993
- # which is the inconsistency that exposed the exact-match bug.
994
- "claude-haiku-4-5": 200_000,
995
- "gpt-5.1": 400_000,
996
- "gemini-2.5-pro": 1_000_000,
997
- # Alibaba markets "1M"; the documented input limit is 983,616, and
998
- # drops to that figure specifically when thinking is enabled. The
999
- # SMALLER number is the right one to record: this feeds the pipeline
1000
- # compaction backstop (context_limit - COMPACTION_PIPELINE_BACKSTOP_
1001
- # TOKENS), where erring low compacts slightly early and erring high
1002
- # means a hard context-limit error from the provider mid-run.
1003
- "qwen3.8-max-preview": 983_616,
1004
- }
1005
- # Logged at WARNING ONCE PER MODEL, per §21 -- a wrong-by-default window
1006
- # means compaction and the backstop both fire at the wrong time in
1007
- # whichever direction the guess is wrong, and silent guessing turns a
1008
- # tuning problem into a mystery. Once per model rather than once per use,
1009
- # because context_limit() is on should_compact()'s path and that runs at
1010
- # the top of every step of every turn; the dedup set lives in
1011
- # core/compaction.py. A long session therefore says this once and is then
1012
- # silent, which is the trade -- the line is actionable exactly once, and
1013
- # since batch 44 it names the action (/window, which remembers).
1014
- #
1015
- # 256_000 rather than 200_000 (batch 44): the floor a hosted agentic model
1016
- # ships with today. Below that is essentially always a self-hosted
1017
- # deployment, whose operator knows the number and can say it once with
1018
- # /window -- which is the case this default cannot serve and does not try
1019
- # to. Erring low here would compact every unknown model early forever to
1020
- # protect the rarer case that has an owner who can answer.
1021
- DEFAULT_CONTEXT_WINDOW = 256_000
1022
-
1023
-
1024
- # APICredentials was here and is deleted (audit #23). It was dead -- nothing
1025
- # constructed it, imported it or type-hinted against it -- and its guidance
1026
- # contradicted the mechanism that is real: it told the reader to put the key
1027
- # in an environment variable and write the VARIABLE'S NAME here, while
1028
- # credentials.save_credentials stores the key value directly in
1029
- # providers.json. Anyone following it ended up with the literal string
1030
- # "MY_KEY_VAR" as their API key.
1031
- #
1032
- # Credentials flow through credentials.py (providers.json) and env_secrets.py
1033
- # (.env) -- the deliberate two-mechanism split D19 describes, which
1034
- # env_secrets.py documents at length on the other side. The provider roster
1035
- # lives in providers.json.example, beside the file it describes.
1036
-
1037
-
1038
- @dataclass
1039
- class ToolPermissions:
1040
- web_search: bool = True
1041
- # ROADMAP_v2 §15/D24: fetch_url was registered and documented as working
1042
- # but had no field here, so getattr(..., False) denied every call since
1043
- # the tool was added. Allowed by default, matching web_search -- it is
1044
- # already constrained by policy_enforcement's blocked-domain list and
1045
- # its output goes through secret redaction like every other tool's.
1046
- fetch_url: bool = True
1047
- get_time: bool = True
1048
- arxiv_search: bool = True
1049
- symbolic_math: bool = True
1050
- linear_algebra: bool = True
1051
- probability_stats: bool = True
1052
- discrete_math: bool = True
1053
- logic: bool = True
1054
- geometry: bool = True
1055
- read: bool = False
1056
- write: bool = False
1057
- edit: bool = False
1058
- shell: bool = False
1059
- load_skill: bool = True
1060
- # §18: spawning is allowed by default (model autonomy, D6) and needs no
1061
- # approval -- the spawned run's own tools are each gated by policy,
1062
- # intersection-capped by the parent's context (C6).
1063
- spawn_subagent: bool = True
1064
- # §21/D26. Thread-scoped, reversible (batch 16 gave that word a
1065
- # mechanism: `unpin`), and it takes effect inside a conversation the
1066
- # user is watching -- a wrong pin costs some context budget and nothing
1067
- # else.
1068
- pin: bool = True
1069
- # §21/D26, restored by batch 16 (#89). D26's premise called a pin
1070
- # reversible while nothing anywhere unpinned one; unpin is the other
1071
- # half of making the premise true rather than aspirational. Same axis,
1072
- # same gating posture, same reasons.
1073
- unpin: bool = True
1074
- # §21b. Allowed everywhere; whether it can actually RUN is decided
1075
- # by the approval gate below plus §13's headless rule.
1076
- remember: bool = True
1077
- # §24 (I2). Allowed, unlike `read`, because it is confined to the
1078
- # project directory by realpath and to documentation/manifest files by
1079
- # an allowlist -- see tools/builtin/project_docs.py for what that
1080
- # deliberately excludes and why the narrow set is load-bearing.
1081
- read_project_doc: bool = True
1082
- # §24 (I1). Allowed, unlike `write`, because it takes a document NAME
1083
- # from a fixed allowlist rather than a path: the destination is derived,
1084
- # so the tool cannot be aimed anywhere else. The gate is below.
1085
- write_project_doc: bool = True
1086
- # §23 slice 2. Allowed everywhere, and ungated below (J12): whether it
1087
- # can actually reach a person is decided by whether the run has a
1088
- # response channel, which the tool itself checks.
1089
- ask_user: bool = True
1090
- # §23 slice 2. Thread-scoped, reversible, and it asks nobody -- so it is
1091
- # allowed and ungated for `pin`'s reasons (J9).
1092
- todo_write: bool = True
1093
-
1094
- @dataclass
1095
- class ToolApprovals:
1096
- web_search: bool = False
1097
- # No approval: a tool with approval=True is unusable wherever there is
1098
- # no permission_channel to answer the prompt (the CLI chat loop and
1099
- # every research pass), so gating fetch_url would leave it denied in
1100
- # exactly the places the grounding passes need it -- the same outcome
1101
- # as the D24 bug, with a different error string. See DEVLOG §15.
1102
- fetch_url: bool = False
1103
- get_time: bool = False
1104
- arxiv_search: bool = False
1105
- symbolic_math: bool = False
1106
- linear_algebra: bool = False
1107
- probability_stats: bool = False
1108
- discrete_math: bool = False
1109
- logic: bool = False
1110
- geometry: bool = False
1111
- read: bool = False
1112
- write: bool = False
1113
- edit: bool = False
1114
- # ROADMAP_v2 §28 (G3). False since §28, and False here does NOT mean
1115
- # "never ask" -- SHELL_APPROVAL_MODE is the gate, and it ships
1116
- # "tiered". This field is the RATCHET, and it still only tightens:
1117
- # approval_needed() ORs the tool's own check with requires_approval(),
1118
- # and requires_approval() reads this field, so setting it True forces
1119
- # "always" whatever the mode says. An agent's approval_overrides
1120
- # reaches the same OR and has the same one-way power (D14).
1121
- #
1122
- # It stays declared because D24 requires every registered tool to have
1123
- # a field in both dataclasses, and because the ratchet needs somewhere
1124
- # to live. Do not delete it and do not read it as the gate.
1125
- shell: bool = False
1126
- load_skill: bool = False
1127
- # Approving a spawn is the §18 subagent sign-off: it authorises the
1128
- # child's whole approval-gated tool set for the rest of the turn, so
1129
- # delegation itself has to be the thing approved. Consequence, named
1130
- # rather than discovered: the headless callability filter drops
1131
- # spawn_subagent anywhere nothing can grant the approval -- CLI chat,
1132
- # and any research run that is neither attended nor granting. The
1133
- # once-per-run notice names it.
1134
- #
1135
- # §25 R4 declares it GRANT_NEVER (R13, on the ToolSpec): it can never
1136
- # be PRE-granted, in a research run OR at §18's sign-off, because
1137
- # approving a spawn hands the child a whole gated set and one
1138
- # launch-time tick would compound into unbounded delegated authority
1139
- # across ten unattended passes. #67 is why "or at the sign-off" is in
1140
- # that sentence: R4's argument is ABOUT the sign-off, and the
1141
- # exclusion had never reached it. An ATTENDED run can still approve a
1142
- # spawn live,
1143
- # which is a per-call human decision and exactly what the gate is for.
1144
- # The child then runs headless with nothing granted, since
1145
- # spawn_subagent forwards a grant only alongside a permission_channel.
1146
- spawn_subagent: bool = True
1147
- # §21/D26: pin does NOT require approval, and the asymmetry with
1148
- # remember (§21b) is the decision. They differ on the axis that already
1149
- # separates `read` from `write` -- pin is thread-scoped and reversible,
1150
- # while remember writes something that outlives the thread and silently
1151
- # shapes conversations the user has not started yet.
1152
- #
1153
- # Consequence, named rather than discovered: this is what lets pin work
1154
- # on the CLI and inside a research pass, where an approval-gated tool
1155
- # is not merely denied but not advertised at all (§13).
1156
- pin: bool = False
1157
- # §21/D26, batch 16 (#89). Ungated for pin's reasons, and now genuinely
1158
- # symmetric: releasing protection costs context budget in a
1159
- # conversation the user is watching, exactly like applying it.
1160
- unpin: bool = False
1161
- # §21b/D26, and the asymmetry with pin above IS the decision. A
1162
- # memory outlives its thread and silently shapes conversations the
1163
- # user has not started yet, so it is persistent and invisible at the
1164
- # moment it matters -- the same axis that separates write from read.
1165
- #
1166
- # Consequence: unreachable on any headless path, which includes every
1167
- # research pass. That is deliberate (§21's consequence 1) and is
1168
- # reinforced by the tool's GRANT_NEVER policy (M17, carried by R13),
1169
- # because a grant would otherwise route around it.
1170
- remember: bool = True
1171
- # §24 (I2): no approval. Reading the project's own documentation, at the
1172
- # user's explicit request, on the files the manifest already listed to
1173
- # them, is not an escalation -- and a gate here would mean a dozen
1174
- # prompts for one /init, which is the shape of consent that gets clicked
1175
- # through. The confinement in project_docs.py is the control.
1176
- read_project_doc: bool = False
1177
- # §24 (I1): gated, on the same axis that separates `read` from `write`.
1178
- # This writes a file into the user's project that is then injected into
1179
- # future prompts, and it invalidates the D17 trust hash as it goes.
1180
- # /init supplies the approval itself, as the yes to a rendered diff --
1181
- # so the gate is what makes "no silent overwrite" (§24 AC2) structural
1182
- # rather than a promise the command makes about itself.
1183
- write_project_doc: bool = True
1184
- # §23 slice 2 (J12): UNGATED. Two reasons, and the second is the one
1185
- # that decides it. Gating would mean approving a prompt in order to be
1186
- # shown a prompt -- but worse, §13 does not merely deny a gated tool
1187
- # where nothing can ask, it stops ADVERTISING it. Gated, this tool would
1188
- # be invisible in every headless run; §24 AC2 requires it be visible,
1189
- # called, and answered with a denial the model can work around. Asking
1190
- # a person is not an action that needs authorising -- it is the least
1191
- # unilateral thing a run can do.
1192
- ask_user: bool = False
1193
- # §23 slice 2 (J9): UNGATED, on the axis that already separates `pin`
1194
- # from `remember`. A todo list is thread-scoped and reversible, and
1195
- # rewriting it costs some prompt budget inside a conversation the user
1196
- # can see. Gating it would also make it invisible in every research pass
1197
- # (§13), which is where a checklist across ten passes helps most.
1198
- todo_write: bool = False
1
+ """config.py -- the harness's settings, as module attributes.
2
+
3
+ THE VALUES LIVE IN `config.yaml` NOW. This module is the compatibility layer
4
+ that publishes them: it reads the file once, through `config_schema.py`, and
5
+ binds each value as a plain module global, so `config.MAX_TOKENS` means what
6
+ it always meant to the 30 production modules and ~60 test files that read it.
7
+
8
+ WHERE TO LOOK FOR WHAT:
9
+
10
+ * `config.yaml` the values, with a short note on what each DOES
11
+ * `CONFIG_ARCHITECTURE.md` why each value is what it is -- the whole
12
+ history, section by section, under the same
13
+ names. Read it before changing a number.
14
+ * `config_schema.py` the schema, the environment overrides, and the
15
+ argument for why the file has exactly one
16
+ location and no override variable
17
+
18
+ FOUR THINGS ABOUT THIS FILE ARE DELIBERATE.
19
+
20
+ 1. THE GLOBALS ARE PLAIN AND MUTABLE, and are bound EAGERLY rather than
21
+ through a module `__getattr__`. Four access patterns in this codebase
22
+ depend on it and a lazy proxy breaks at least one of each:
23
+ `monkeypatch.setattr(config, ...)`, a bare `config.X = v` (an autouse
24
+ fixture in `tests/conftest.py` does this for every test in the suite),
25
+ `mocker.patch.dict(config.__dict__, {...})`, and
26
+ `getattr(config, "<NAME>", default)` -- which must raise `AttributeError`,
27
+ not `KeyError`, for a name that does not exist.
28
+
29
+ 2. THE READ HAPPENS AT IMPORT, and so does the environment fold-in.
30
+ `security/posture.py` depends on it: `config` binding at import is what
31
+ makes `os.environ[...] = ...` unable to move the security posture, where
32
+ anything reading `os.environ` at CALL time would follow the mutation (UN1,
33
+ and batch 37's asymmetry). `tools/builtin/shell.py` validates the approval
34
+ mode at its own import, so the values must be final before it runs.
35
+ Nothing re-reads the file; an edit to `config.yaml` takes effect at the
36
+ next launch.
37
+
38
+ 3. THERE IS STILL NO LOGIC HERE. No `if`, no function that decides anything,
39
+ no `os.environ` read -- those moved to `config_schema.py` rather than
40
+ arriving here. ARCHITECTURE.md §4.1's rule is unchanged in substance: a
41
+ function that reads these values and makes a decision belongs in whichever
42
+ file consumes the setting.
43
+
44
+ 4. `ToolPermissions` / `ToolApprovals` ARE REAL DATACLASSES, rebuilt from the
45
+ schema with `config.yaml`'s booleans as their field defaults. Not the
46
+ pydantic models themselves, because the codebase depends on the shape:
47
+ `security/permissions.py` calls `config.ToolPermissions()` with no
48
+ arguments on every check, tests mutate an instance and then swap this
49
+ module's attribute for a factory returning it, and
50
+ `tests/test_docs_consistency.py` enumerates `vars(instance)` to check
51
+ README's approval table names every registered tool. The FIELD NAMES are
52
+ declared in `config_schema.py`, in Python, so D24's build-time check that
53
+ every registered tool has a field cannot be turned into a runtime surprise
54
+ by an omission in a data file.
55
+ """
56
+
57
+ import config_schema
58
+
59
+ # Read, validate, apply the environment. Once, here, before anything else in
60
+ # the process has run. A missing file, an unknown key, a missing key, a
61
+ # duplicated key or a value of the wrong type raises `ValueError` naming the
62
+ # file and the key -- loudly, at startup, rather than as a wrong default
63
+ # three hours into a run.
64
+ #
65
+ # `force=True` IS LOAD-BEARING, and it is the one thing about this file that
66
+ # is not obvious. IMPORTING THIS MODULE is what "bind the configuration now"
67
+ # means, so this module -- not the schema's cache -- decides when the file is
68
+ # read. Without the flag, `config_schema`'s cache outlives a re-import of
69
+ # `config`, and re-importing `config` under a changed environment is a real
70
+ # technique in this repo rather than a hypothetical: `test_storage_e2e`'s
71
+ # `real_storage` fixture pops `sqlmodel`, `config`, `database` and `storage`
72
+ # out of `sys.modules`, sets `APP_DB_PATH` to a throwaway file, and imports
73
+ # them again to get real SQLite. `config_schema` is not in that list and
74
+ # cannot be -- the fixture predates it -- so a cached model would hand the
75
+ # fresh `config` the OLD `db_path` and point the engine at the developer's
76
+ # real `app.db`. That is how it was found: one test comparing a migrated
77
+ # column against a fresh one, reading a database that had accumulated
78
+ # migrations.
79
+ #
80
+ # The cache still does its job. `core/config_loader.py` reads five values off
81
+ # `config_schema.current()`, which returns whatever this import bound, so the
82
+ # two cannot disagree -- and a re-import replaces the cache rather than
83
+ # bypassing it.
84
+ _config = config_schema.load(force=True)
85
+
86
+ # Bind every value as a module global. `as_module_namespace` returns
87
+ # `{UPPER_CASE_NAME: value}` for every field in `config.yaml` except the two
88
+ # permission tables, plus the two values that have no key because they are
89
+ # derived from the environment rather than defaulted: OUTPUT_DIR (composed
90
+ # from AGENT_OUTPUT_DIR / AGENT_WORKSPACE) and WORKSPACE_DIR_EXPLICIT (the
91
+ # PRESENCE of AGENT_WORKSPACE, never its value).
92
+ globals().update(config_schema.as_module_namespace(_config))
93
+
94
+ ToolPermissions = config_schema.tool_permissions_dataclass()
95
+ ToolApprovals = config_schema.tool_approvals_dataclass()