@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/core/memory.py ADDED
@@ -0,0 +1,370 @@
1
+ """
2
+ core/memory.py
3
+
4
+ Keeps the running message history for one agent conversation, backed by
5
+ real persistence. Stores history in a PROVIDER-NEUTRAL shape -- not
6
+ Anthropic's content-block format, not OpenAI's tool_calls format -- so
7
+ this file has no idea which provider is in use. core/client.py is the
8
+ only place that translates this neutral shape into whatever wire format
9
+ a specific provider's API actually wants, the same way it already
10
+ translates tool schemas per provider.
11
+
12
+ Neutral shapes stored in self._messages:
13
+ user: {"role": "user", "content": "text"}
14
+ assistant: {"role": "assistant", "text": "...", "tool_calls": [
15
+ {"id": "...", "name": "...", "input": {...}}, ...]}
16
+ tool: {"role": "tool", "tool_call_id": "...", "content": "..."}
17
+ (one entry per individual tool result)
18
+
19
+ PERSISTENCE, AND WHY THERE'S NO NORMALIZATION STEP HERE:
20
+ Each add_* method passes storage.save_message() only the PAYLOAD that
21
+ role actually needs -- plain text for user, {"text", "tool_calls"} for
22
+ assistant, a plain result string for tool -- never the whole neutral
23
+ entry dict, which would redundantly re-wrap "role" (and, for tool rows,
24
+ "tool_call_id") a second time inside the persisted content itself.
25
+ storage.get_session_history() reconstructs the exact neutral shape
26
+ above directly, per msg.role, so what comes back on resume is
27
+ identical to what a fresh add_* call would have produced -- no
28
+ post-hoc reshaping step is needed here, for this role or any future one.
29
+
30
+ An earlier version of this file had exactly the bug this design avoids:
31
+ add_assistant_message's persisted shape was nested and lossy on
32
+ resume, a read-side "_normalize_resumed_history()" function was added
33
+ to fix it -- but only for role == "assistant". add_tool_result had the
34
+ identical root cause (same "pass the whole entry dict" pattern) and was
35
+ never touched, because the fix lived one layer above where the actual
36
+ divergence was produced. Fixing what gets WRITTEN, once, here, closes
37
+ this for every role without a matching special case at every point
38
+ it's read back. See tests/test_memory_write_through.py for the
39
+ regression tests (now covering the tool row's `content`, not just its
40
+ `role`/`tool_call_id`, which is exactly the assertion that was missing
41
+ before).
42
+ """
43
+
44
+ from typing import Optional
45
+ from uuid import UUID
46
+
47
+ from storage import (
48
+ create_thread, get_thread, save_message, get_session_history,
49
+ update_thread_extra, latest_checkpoint, pinned_through,
50
+ message_ids_from, set_pinned, turn_start_ids, THREAD_KIND_CHAT,
51
+ )
52
+
53
+ # ROADMAP_v2 §21 (M8). How a compaction summary is introduced to the model.
54
+ #
55
+ # The neutral shape has three roles -- user, assistant, tool -- and no
56
+ # "system" among them, because the system prompt travels separately. A
57
+ # leading USER message is therefore the only form all three providers
58
+ # accept in the message list, and it is where a conversation naturally
59
+ # starts anyway.
60
+ #
61
+ # It is NEVER persisted as a MessageLog row. Doing so would put derived
62
+ # content in an append-only archive whose whole value is being original,
63
+ # and the next compaction would then summarize the previous summary as if
64
+ # it were something the user said -- chaining by accident, on a code path
65
+ # that means to re-derive.
66
+ SUMMARY_PREFIX = (
67
+ "[Summary of the earlier part of this conversation, compacted to save "
68
+ "context. The full history is preserved and unedited; this is what is "
69
+ "being shown to you now.]\n\n"
70
+ )
71
+
72
+
73
+ class ConversationMemory:
74
+ def __init__(self, thread_id: Optional[UUID] = None,
75
+ kind: str = THREAD_KIND_CHAT) -> None:
76
+ """`kind` (§27 T1) says what a NEW thread is, and is forwarded to
77
+ storage.create_thread and nowhere else.
78
+
79
+ This class does not learn what a kind means, store it, or read it
80
+ back. It owns active in-run state and must stay unaware of what
81
+ data exists -- that boundary is storage.py's. Ignored when
82
+ `thread_id` is given, because resuming does not reclassify: a
83
+ thread's kind was decided when it was created.
84
+ """
85
+ # Session-scoped billing (#4): zero on EVERY construction, fresh or
86
+ # resumed -- see record_billed for why this one is deliberately not
87
+ # extra_data like its neighbour.
88
+ self.billed_tokens = 0
89
+ if thread_id is None:
90
+ self.thread_id = create_thread(kind=kind)
91
+ self._messages: list[dict] = []
92
+ self._extra: dict = {}
93
+ self._kind = kind
94
+ else:
95
+ thread = get_thread(thread_id)
96
+ if thread is None:
97
+ raise ValueError(f"No conversation thread found with id {thread_id}")
98
+ self.thread_id = thread_id
99
+ self._extra = dict(thread.get("extra_data") or {})
100
+ self._messages = self._derived_view()
101
+ # The kind fallback (missing column on a database whose ALTER
102
+ # has not run) lives inside get_thread's copy now; resuming is
103
+ # not reclassifying, so the stored kind is simply reported.
104
+ self._kind = thread.get("kind") or THREAD_KIND_CHAT
105
+
106
+ @property
107
+ def kind(self) -> str:
108
+ """What this thread IS (§27 T1): "chat", "research_pass" or
109
+ "subagent".
110
+
111
+ A deliberate boundary bend, recorded rather than slipped in
112
+ (#43, batch 16). §27 says this class "learns nothing from kind" --
113
+ it forwards the kwarg at creation and ignores it on resume --
114
+ because kind SEMANTICS are storage's to store and the loop's to
115
+ decide. That still holds: nothing here branches on the value.
116
+ What changed is that the loop can now ASK, because batch 16 gave
117
+ it a decision to make from the answer -- which compaction mode a
118
+ re-entered thread runs under derives from what the thread IS
119
+ (research_pass and subagent threads get M6's backstop wherever
120
+ they are resumed), and the memory is the object holding the
121
+ thread. Reporting a stored fact is not interpreting it.
122
+ """
123
+ return self._kind
124
+
125
+ # -- the derived view (§21) --------------------------------------------
126
+
127
+ def _derived_view(self) -> list[dict]:
128
+ """What the agent sees this turn: a view computed over the archive,
129
+ not a second copy of it.
130
+
131
+ Three parts, in order:
132
+ 1. the latest checkpoint's summary, as a leading user message
133
+ 2. pinned rows from inside the span that summary covers (M9),
134
+ verbatim -- the summary skipped them, and one watermark
135
+ cannot say "everything through K except these"
136
+ 3. every archive row after the watermark, verbatim
137
+
138
+ A thread that has never been compacted has no checkpoint, so this
139
+ returns exactly what get_session_history() always returned. That
140
+ equivalence is what keeps every pre-§21 caller untouched until the
141
+ trigger first fires on a thread, and it is asserted directly.
142
+ """
143
+ checkpoint = latest_checkpoint(self.thread_id)
144
+ if checkpoint is None:
145
+ return get_session_history(self.thread_id)
146
+
147
+ watermark = checkpoint["covers_up_to_message_id"]
148
+ summary = {
149
+ "role": "user",
150
+ "content": f"{SUMMARY_PREFIX}{checkpoint['summary_text']}",
151
+ }
152
+ return (
153
+ [summary]
154
+ + pinned_through(self.thread_id, watermark)
155
+ + get_session_history(self.thread_id, after_message_id=watermark)
156
+ )
157
+
158
+ def apply_checkpoint(self) -> None:
159
+ """Rebuild the in-memory view after a compaction was recorded.
160
+
161
+ Deliberately re-reads rather than splicing the summary into the
162
+ list it already holds. The assembly rules (a leading summary,
163
+ pinned re-inclusion, the tail) then live in exactly one place, so
164
+ a mid-run compaction and a resumed thread cannot produce different
165
+ views of the same checkpoint -- which is the divergence a second
166
+ assembly path would eventually introduce.
167
+ """
168
+ self._messages = self._derived_view()
169
+
170
+ # -- measured context size (§21) ----------------------------------------
171
+
172
+ @property
173
+ def last_input_tokens(self) -> int:
174
+ """The provider's own count of everything it was last sent on this
175
+ thread, or 0 if it has never been measured.
176
+
177
+ This is what §21's compaction trigger reads. It is exact and it
178
+ comes from the provider rather than from a local tokenizer that
179
+ would have to be right per model -- but it is retrospective, which
180
+ is why the trigger is evaluated after a response and acts before
181
+ the next call.
182
+
183
+ PERSISTED, via the same extra_data write-through goal mode uses.
184
+ §21 says a resumed thread needs a rough character estimate before
185
+ its first call because nothing has been measured yet; carrying the
186
+ last real measurement across the process boundary means the
187
+ estimate is only ever needed for a thread written before this
188
+ section existed.
189
+ """
190
+ return int(self._extra.get("last_input_tokens") or 0)
191
+
192
+ def record_input_tokens(self, tokens: int) -> None:
193
+ """Store the measurement from the call that just returned. Ignores
194
+ a zero, which is what D21's raise exists to prevent reaching here
195
+ and what a provider reporting no usage would otherwise write over
196
+ a real earlier number."""
197
+ if tokens:
198
+ self.set_extra("last_input_tokens", int(tokens))
199
+
200
+ # -- session billing (#4) -------------------------------------------------
201
+
202
+ def record_billed(self, tokens: int) -> None:
203
+ """Accumulate this thread's billed input+output for the SESSION.
204
+
205
+ Deliberately NOT persisted, unlike last_input_tokens beside it:
206
+ the scope the TUI's usage line shows is THREAD-SINCE-RESUME. A
207
+ lifetime total would need a schema column to mean anything (a
208
+ resumed thread would silently restart at zero anyway, reading as
209
+ a reset), and #4's figure exists for relative reasoning about
210
+ this session, not as a ledger.
211
+ """
212
+ self.billed_tokens += int(tokens or 0)
213
+
214
+ def completed_turns(self) -> int:
215
+ """How many turns of this thread are already finished (§21 M5/M11).
216
+
217
+ COUNTED FROM THE ARCHIVE, never from `self._messages`. M8 makes a
218
+ checkpoint summary a `role: "user"` message, so a compacted view
219
+ holds one user message that is not a turn -- and this number is
220
+ compared against archive-space turn indices in
221
+ compaction.compactable_span(). Counting the view was §21a's shipped
222
+ defect: the floor came out several turns too low, the computed
223
+ watermark went BACKWARDS, and the second automatic compaction of a
224
+ thread un-compacted it. See tests/test_storage_e2e.py.
225
+
226
+ Lives here rather than in core/loop.py because this is the file
227
+ that owns the thread's persistence -- the loop imports no storage
228
+ at all, and should not start.
229
+
230
+ Called before the first model call of a turn, and every wrapper
231
+ adds the user message first, so the turn about to run is the last
232
+ entry and is excluded. That off-by-one IS the structural floor:
233
+ everything from this index on is the current turn and can never be
234
+ folded.
235
+
236
+ Archive-space also makes the value STABLE for a whole turn. The
237
+ archive never changes under compaction, so a count taken at the top
238
+ of a turn stays correct after a mid-turn compaction rebuilds the
239
+ view; the view-based version silently went stale at exactly that
240
+ point.
241
+ """
242
+ return len(turn_start_ids(self.thread_id)) - 1
243
+
244
+ # -- pinning (§21) ------------------------------------------------------
245
+
246
+ def pin_last(self, turns: int = 1) -> int:
247
+ """Mark the last `turns` turns compaction-exempt. Returns how many
248
+ rows were newly pinned.
249
+
250
+ ORDINAL, not an id. §21 keeps MessageLog.id out of the neutral
251
+ shape -- the model never sees one and so cannot name one -- and
252
+ adding it would put a persistence concept into the provider-neutral
253
+ contract the whole memory design rests on, with three translation
254
+ branches then needing to strip it before the wire. "Pin the last N
255
+ turns" needs no id and is how the tool would actually be used.
256
+
257
+ A turn starts at a user message and runs to just before the next
258
+ one, so pinning a turn keeps the question together with its answer
259
+ and any tool results between them. Asking for more turns than the
260
+ thread has pins the whole thread rather than erroring: the intent
261
+ ("keep this conversation") is unambiguous and there is nothing to
262
+ clarify.
263
+ """
264
+ if turns < 1:
265
+ return 0
266
+ starts = turn_start_ids(self.thread_id)
267
+ if not starts:
268
+ return 0
269
+ first = starts[max(0, len(starts) - turns)]
270
+ return set_pinned(message_ids_from(self.thread_id, first))
271
+
272
+ def unpin_last(self, turns: int = 1) -> int:
273
+ """Release the protection on the last `turns` turns (#89). The
274
+ mirror of pin_last, and what D26's "reversible" premise needed to
275
+ become true: set_pinned's pinned=False branch was written since
276
+ §21 and unreachable until this existed.
277
+
278
+ Same ordinal interface, same clamp (asking for more turns than
279
+ the thread has releases everything -- the intent is unambiguous),
280
+ same return contract (rows actually flipped, so "nothing was
281
+ pinned" reads as zero)."""
282
+ if turns < 1:
283
+ return 0
284
+ starts = turn_start_ids(self.thread_id)
285
+ if not starts:
286
+ return 0
287
+ first = starts[max(0, len(starts) - turns)]
288
+ return set_pinned(message_ids_from(self.thread_id, first),
289
+ pinned=False)
290
+
291
+ @property
292
+ def extra(self) -> dict:
293
+ """Snapshot of the thread's extra_data (goal mode §18). A copy --
294
+ mutate via set_extra(), which persists write-through like the
295
+ message methods."""
296
+ return dict(self._extra)
297
+
298
+ def set_extra(self, key: str, value) -> None:
299
+ """Write one extra_data key (value=None deletes), persisting
300
+ immediately so a goal set from the TUI is visible to the next
301
+ run in any shell."""
302
+ update_thread_extra(self.thread_id, key, value)
303
+ if value is None:
304
+ self._extra.pop(key, None)
305
+ else:
306
+ self._extra[key] = value
307
+
308
+ def add_user_message(self, text: str) -> None:
309
+ entry = {"role": "user", "content": text}
310
+ self._messages.append(entry)
311
+ save_message(self.thread_id, role="user", content=text)
312
+
313
+ def add_assistant_message(self, response) -> None:
314
+ """
315
+ Takes the NORMALIZED ModelResponse from
316
+ core.client.call_model_stream() directly -- not a raw SDK object.
317
+ This is what eliminated the previous Anthropic-only
318
+ `response.raw.content` reach-through in loop.py; all three
319
+ provider branches produce the same ModelResponse shape (.text,
320
+ .tool_calls), so this method never needs to know which provider
321
+ generated it.
322
+
323
+ This used to name `call_model()`, which had no production caller
324
+ (#38) -- so the one sentence telling a reader where this argument
325
+ comes from named a function that never produced one. `raw` went
326
+ with it: it was set only there, so it was None on every live path
327
+ while its comment said it held the SDK response.
328
+ """
329
+ tool_calls = [
330
+ {"id": tc.id, "name": tc.name, "input": tc.input}
331
+ for tc in response.tool_calls
332
+ ]
333
+ entry = {"role": "assistant", "text": response.text, "tool_calls": tool_calls}
334
+ # §44: the turn's reasoning, in the provider's own blocks. Read
335
+ # off the response rather than accumulated from the display
336
+ # deltas, because an Anthropic block carries a signature the
337
+ # prose does not -- see ModelResponse.thinking. Attached to the
338
+ # in-memory entry as well as persisted, so a live turn and a
339
+ # resumed one hand _messages_for_provider the same shape; that is
340
+ # the whole point, and it is why this is one field and not two
341
+ # code paths.
342
+ thinking = getattr(response, "thinking", None)
343
+ if thinking:
344
+ entry["thinking"] = thinking
345
+ self._messages.append(entry)
346
+ # Persist only the assistant-specific payload, not the whole
347
+ # entry -- "role" is already carried by save_message's own
348
+ # `role=` argument, and duplicating it inside `content` is
349
+ # exactly the redundancy that caused the resume-shape bug. The
350
+ # reasoning has its own column for the same reason: it is not
351
+ # part of what the model said.
352
+ save_message(
353
+ self.thread_id,
354
+ role="assistant",
355
+ content={"text": response.text, "tool_calls": tool_calls},
356
+ thinking=thinking,
357
+ )
358
+
359
+ def add_tool_result(self, tool_call_id: str, result: dict) -> None:
360
+ result_text = str(result)
361
+ entry = {"role": "tool", "tool_call_id": tool_call_id, "content": result_text}
362
+ self._messages.append(entry)
363
+ # Persist only the result string. tool_call_id already has its
364
+ # own column (passed below) -- it doesn't need to also be
365
+ # duplicated inside content.
366
+ save_message(self.thread_id, role="tool", content=result_text, tool_call_id=tool_call_id)
367
+
368
+ @property
369
+ def messages(self) -> list[dict]:
370
+ return self._messages
@@ -0,0 +1,175 @@
1
+ """
2
+ core/model_windows.py
3
+
4
+ A remembered context window per (provider, model). Batch 44.
5
+
6
+ WHY THIS EXISTS. Since batch 44 the chat compaction trigger is a FRACTION
7
+ of the model's context window rather than a flat number, so `context_limit`
8
+ stopped being a number that only mistimed a research backstop and became
9
+ the number that decides when every thread folds. Three things can answer
10
+ it and all three can be wrong: the provider may not report a window at all
11
+ (OpenAI, DeepSeek and Perplexity answer with id/created/object/owned_by),
12
+ `config.MODEL_CONTEXT_WINDOWS` cannot know about a model shipped after this
13
+ release, and `DEFAULT_CONTEXT_WINDOW` is a guess by construction. The one
14
+ source that is never wrong is the person running a self-hosted endpoint,
15
+ who knows what they configured.
16
+
17
+ So this is the user's answer, and it OUTRANKS BOTH the query and the table.
18
+ That is the inversion worth stating: everywhere else in this project a
19
+ measured value beats a configured one, because a static table goes stale.
20
+ Here the direction flips, because a query can be confidently wrong in the
21
+ expensive direction -- a gateway reporting its own default rather than the
22
+ deployment's -- while a value someone typed is a statement about the
23
+ deployment they are actually running.
24
+
25
+ KEYED ON THE PAIR, AND EVERY PAIR IS KEPT. §31's session override was one
26
+ slot bound to one pair, so setting a window for a second model discarded
27
+ the first; the whole point of persisting is that a value is entered once
28
+ per model and never again, and a store that remembered only the latest
29
+ would ask again on every switch between two models.
30
+
31
+ USER TIER, LIKE ITS THREE SIBLINGS. `expanduser` at CALL time (a moved HOME
32
+ is picked up, and tests redirect without a restart), versioned, atomic on
33
+ write, failing soft on anything unreadable -- workspace_trust's
34
+ trusted_projects.json, mcp_client's known_mcp_servers.json and
35
+ tui/preferences.py's ui_preferences.json all do exactly this.
36
+
37
+ ITS OWN FILE, NOT ui_preferences.json, AND THAT IS A LAYERING FACT rather
38
+ than a filing preference. `core/compaction.py` reads this, and D12 makes
39
+ the TUI a shell that core must never import -- a window remembered in the
40
+ TUI has to answer for the CLI and for all ten research passes too, which is
41
+ §25's whole lesson about a capability the pipeline could not reach. It is
42
+ equally not `core/session.py`: that module's contract is that NOTHING there
43
+ reaches disk, and the honest way to persist was a new module rather than a
44
+ clause carved out of that one.
45
+
46
+ NOTHING HERE VALIDATES A NUMBER. This module stores ints; tui/app.py's
47
+ /window decides whether an int is a sensible window (it refuses one at or
48
+ below the pipeline backstop margin, and warns above what the provider
49
+ reports). Same split as tui/preferences.py, which stores strings and knows
50
+ no theme names.
51
+ """
52
+
53
+ import logging
54
+ import os
55
+ from typing import Optional
56
+
57
+ from json_store import read_versioned, write_json_atomic
58
+
59
+ logger = logging.getLogger(__name__)
60
+
61
+ # Bumped when the SHAPE changes. An unknown version reads as an empty
62
+ # store, which costs the derived window -- there is nothing here that was
63
+ # consented to, so the MCP store's careful legacy handling has no
64
+ # counterpart.
65
+ STORE_VERSION = 1
66
+
67
+
68
+ def store_path() -> str:
69
+ # Call time, not import time: tests redirect it, and a moved config
70
+ # directory is picked up without a restart. workspace_trust and
71
+ # tui/preferences resolve theirs the same way.
72
+ return os.path.expanduser("~/.config/venastine/model_windows.json")
73
+
74
+
75
+ def _key(provider_name: str, model: str) -> str:
76
+ """One flat string, because JSON object keys cannot be tuples.
77
+
78
+ The separator is a pipe rather than a slash: an OpenRouter model id is
79
+ `vendor/model`, so a slash would make `OPENROUTER/minimax/m3`
80
+ ambiguous about where the provider ended. A provider name is an
81
+ uppercase identifier and cannot contain one.
82
+ """
83
+ return f"{provider_name}|{model}"
84
+
85
+
86
+ def _read_raw() -> dict:
87
+ """The remembered windows, or {} for anything unusable.
88
+
89
+ json_store.read_versioned covers a missing file, an unreadable one, a
90
+ non-object and a version this build does not know. The worst
91
+ consequence of forgetting is falling back to the derived window, which
92
+ is where every user starts; there is no security property here to fail
93
+ closed for, which is why the shared fail-soft reader is the right one
94
+ and workspace_trust's is not.
95
+
96
+ The `windows` sub-key is unwrapped HERE, because the shape under the
97
+ version is this module's business and not the store helper's.
98
+ """
99
+ data = read_versioned(store_path(), STORE_VERSION,
100
+ "using derived context windows.")
101
+ windows = data.get("windows")
102
+ return windows if isinstance(windows, dict) else {}
103
+
104
+
105
+ def _write(windows: dict, action: str) -> bool:
106
+ """Persist the whole map. True if it reached disk.
107
+
108
+ The atomic write itself is json_store's, shared with the three sibling
109
+ stores; the ERROR POLICY stays here, because whether a failed write is
110
+ a warning or an exception is a fact about what the file means.
111
+
112
+ A failure WARNS and returns False rather than raising. The TUI routes
113
+ WARNING+ into the transcript through TranscriptLogHandler, so someone
114
+ whose value could not be saved is told at the moment they set it
115
+ rather than discovering it at the next launch.
116
+ """
117
+ path = store_path()
118
+ try:
119
+ write_json_atomic(path, {"version": STORE_VERSION, "windows": windows},
120
+ sort_keys=True)
121
+ except OSError as exc:
122
+ logger.warning("Could not %s the context window in %s (%s).",
123
+ action, path, exc)
124
+ return False
125
+ return True
126
+
127
+
128
+ def window_for(provider_name: Optional[str],
129
+ model: Optional[str]) -> Optional[int]:
130
+ """The remembered window for exactly this pair, or None.
131
+
132
+ `provider_name` is Optional because compaction.context_limit still
133
+ accepts callers that do not know it; without a provider no entry can
134
+ match, which is the same answer as having none. A stored value that is
135
+ not a positive int is ignored rather than raising -- the file is
136
+ hand-editable, and a bad entry must cost the derived window, not the
137
+ session.
138
+ """
139
+ if not provider_name or not model:
140
+ return None
141
+ value = _read_raw().get(_key(provider_name, model))
142
+ if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
143
+ return None
144
+ return value
145
+
146
+
147
+ def remember_window(provider_name: str, model: str, tokens: int) -> bool:
148
+ """Record `tokens` for this pair. True if it reached disk."""
149
+ windows = _read_raw()
150
+ windows[_key(provider_name, model)] = int(tokens)
151
+ return _write(windows, "save")
152
+
153
+
154
+ def forget_window(provider_name: str, model: str) -> str:
155
+ """Drop this pair's entry. "removed", "absent" or "failed".
156
+
157
+ Three outcomes rather than a bool because the shell says a different
158
+ sentence for each, and a failed write reported as "nothing was set"
159
+ would be a lie about the state of a file the user can go and read.
160
+ """
161
+ windows = _read_raw()
162
+ if windows.pop(_key(provider_name, model), None) is None:
163
+ return "absent"
164
+ return "removed" if _write(windows, "clear") else "failed"
165
+
166
+
167
+ def all_windows() -> dict:
168
+ """{(provider, model): tokens}, for a report. Empty when nothing is set."""
169
+ out = {}
170
+ for key, value in _read_raw().items():
171
+ provider, _, model = key.partition("|")
172
+ if model and isinstance(value, int) and not isinstance(value, bool) \
173
+ and value > 0:
174
+ out[(provider, model)] = value
175
+ return out