@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/tui/diffs.py ADDED
@@ -0,0 +1,265 @@
1
+ """
2
+ tui/diffs.py
3
+
4
+ What a `write` or an `edit` actually changed, as a block the transcript can
5
+ paint (ROADMAP_v2 §41, X4-X6).
6
+
7
+ Both tools used to render as `▸ {name} {param_digest(input)}`, and
8
+ `param_digest` caps every value at 60 characters -- so an edit showed the
9
+ first 60 characters of `old_text`, the first 60 of `new_text`, and nothing
10
+ at all about where in the file they landed. Three questions a reader
11
+ actually has (what changed, where, and what is around it) and the line
12
+ answered none of them.
13
+
14
+ PURE. No I/O, no `core/` import, no harness state -- `tui/widgets.py`'s own
15
+ rule, because the widget imports this. Reading the file is `tui/app.py`'s
16
+ job, and the tool's own path resolution is what it uses to do it.
17
+
18
+ THE BLOCK IS TEXT, and that is deliberate (X5). `Transcript._entries` holds
19
+ `(role, text)` pairs and everything downstream -- `/copy`, `rerender()`
20
+ after a `/theme` -- reads them as text. A structured payload would have
21
+ meant widening that tuple for one caller. So `build_block()` renders a
22
+ canonical form and `parse()` reads it back, both here so the format has one
23
+ definition:
24
+
25
+ tui/widgets.py
26
+ 317 │ except Exception:
27
+ - 319 │ MARKERS = {"completed": "x"}
28
+ + 319 │ MARKERS = {"completed": "☑"}
29
+ … +812 more lines
30
+
31
+ Line 0 is the path. Every other line is a kind character, a gutter, ` │ `
32
+ and the source text. The DISPLAY furniture -- the indent, the padding, the
33
+ colours -- belongs to the renderer and is not stored, for the reason §38
34
+ gives for the thinking span's bar: `/copy` should hand back the diff, and a
35
+ replay under a new theme should re-derive the painting rather than replay a
36
+ string that was decorated once.
37
+
38
+ DEGRADATION IS PART OF THE CONTRACT (X6). A diff that cannot be computed
39
+ narrows; it never raises. `pre=None` -- a new file, one too large to
40
+ snapshot, one that could not be read -- renders every line as an addition.
41
+ An `edit` whose file could not be read still renders its `old_text` and
42
+ `new_text` as `-`/`+` rows with an empty gutter, because those came from
43
+ the call's own arguments and need no file at all.
44
+ """
45
+
46
+ from __future__ import annotations
47
+
48
+ import difflib
49
+ from typing import List, Optional, Tuple
50
+
51
+ #: Lines of unchanged context either side of a change.
52
+ CONTEXT_LINES = 3
53
+
54
+ #: Rows in one block before the rest is summarised. A `write` of an
55
+ #: 800-line file is a legitimate call, and rendering it whole would put
56
+ #: eight hundred solid-green rows into the transcript and push the
57
+ #: conversation out of view.
58
+ MAX_ROWS = 40
59
+
60
+ CONTEXT, DELETED, ADDED, ELIDED = "context", "del", "add", "elided"
61
+
62
+ _MARKS = {CONTEXT: " ", DELETED: "-", ADDED: "+"}
63
+ _KINDS = {" ": CONTEXT, "-": DELETED, "+": ADDED}
64
+
65
+ #: Between the gutter and the source text. A box-drawing bar rather than a
66
+ #: colon or a pipe, so it cannot be mistaken for part of either side.
67
+ GUTTER_SEP = " │ "
68
+
69
+ _ELIDE_MARK = "…"
70
+
71
+ #: (kind, gutter, text). `gutter` is a string, not an int: a `-` row
72
+ #: carries the OLD line number and a `+` row the NEW one, and a row from a
73
+ #: degraded block carries neither.
74
+ Row = Tuple[str, str, str]
75
+
76
+
77
+ def build_block(path: str, pre: Optional[str], post: str, *,
78
+ context: int = CONTEXT_LINES,
79
+ max_rows: int = MAX_ROWS) -> str:
80
+ """The canonical block for one file change.
81
+
82
+ `pre` is the file's contents before the call, or None when there was
83
+ no file to read. `post` is what it contains now -- reconstructed from
84
+ the call's own arguments rather than read back, so the block cannot
85
+ disagree with the call it describes.
86
+ """
87
+ post_lines = post.splitlines()
88
+ if pre is None:
89
+ rows = [(ADDED, str(n), line) for n, line in enumerate(post_lines, 1)]
90
+ else:
91
+ rows = _rows(pre.splitlines(), post_lines, context)
92
+ return _render(path, _capped(rows, max_rows))
93
+
94
+
95
+ def wrap_source(text: str, width: int) -> list:
96
+ """One source line as the rows it will occupy, at `width` columns.
97
+
98
+ The same rule `Transcript._split_committable` uses for a streamed
99
+ answer -- break at the last space that fits, and hard-cut a run
100
+ longer than a row -- rather than `textwrap`, which collapses runs
101
+ of whitespace and would silently re-indent the code it is
102
+ displaying.
103
+
104
+ The wrap has to be OURS for the reason §38 gives: Rich would
105
+ soft-wrap the row and the padding that carries the background
106
+ would land on the first rendered row only, so a wrapped addition
107
+ would be half green. Width <= 0 means nothing is measurable (a
108
+ widget built bare in the suite) and the line is returned whole.
109
+ """
110
+ if width <= 0 or len(text) <= width:
111
+ return [text]
112
+ rows, rest = [], text
113
+ while len(rest) > width:
114
+ space = rest.rfind(" ", 1, width + 1)
115
+ cut = space if space > 0 else width
116
+ rows.append(rest[:cut])
117
+ rest = rest[cut:].lstrip(" ") if space > 0 else rest[cut:]
118
+ if not rest:
119
+ break
120
+ if rest:
121
+ rows.append(rest)
122
+ return rows
123
+
124
+
125
+ def build_replacement_block(path: str, old: str, new: str, *,
126
+ max_rows: int = MAX_ROWS) -> str:
127
+ """The degraded form for an `edit` whose file could not be read (X6).
128
+
129
+ No line numbers and no surrounding context, because both need the
130
+ file. The replaced and replacing text do not: they are the call's own
131
+ arguments, and showing them is strictly better than showing the first
132
+ 60 characters of each.
133
+ """
134
+ rows = [(DELETED, "", line) for line in old.splitlines()]
135
+ rows += [(ADDED, "", line) for line in new.splitlines()]
136
+ return _render(path, _capped(rows, max_rows))
137
+
138
+
139
+ def parse(block: str) -> Tuple[str, List[Row]]:
140
+ """A block back into (path, rows). The renderer's half of the format.
141
+
142
+ Tolerant by construction: a line this cannot make sense of comes back
143
+ as context with an empty gutter. The block is produced two lines above
144
+ in the same module, so a malformed one is a bug -- but it arrives here
145
+ from `Transcript._entries`, which is replayed after a `/theme` and
146
+ copied out by `/copy`, and neither of those is worth an exception.
147
+ """
148
+ lines = block.split("\n")
149
+ path = lines[0] if lines else ""
150
+ rows: List[Row] = []
151
+ for line in lines[1:]:
152
+ if not line:
153
+ continue
154
+ if line.startswith(_ELIDE_MARK):
155
+ rows.append((ELIDED, "", line[len(_ELIDE_MARK):].strip()))
156
+ continue
157
+ kind = _KINDS.get(line[:1])
158
+ if kind is None:
159
+ rows.append((CONTEXT, "", line))
160
+ continue
161
+ gutter, sep, text = line[1:].partition(GUTTER_SEP)
162
+ if not sep:
163
+ rows.append((CONTEXT, "", line))
164
+ continue
165
+ rows.append((kind, gutter.strip(), text))
166
+ return path, rows
167
+
168
+
169
+ # ---------------------------------------------------------------------------
170
+ # ---- internals ------------------------------------------------------------
171
+ # ---------------------------------------------------------------------------
172
+
173
+ def _rows(pre_lines: List[str], post_lines: List[str], context: int) -> List[Row]:
174
+ """Changed lines with `context` unchanged lines either side.
175
+
176
+ `SequenceMatcher` rather than `unified_diff`, because what is wanted
177
+ here is the opcodes: a unified diff would have to be re-parsed to
178
+ recover the line numbers this puts in the gutter, and re-parsing a
179
+ format one line after emitting it is the second definition this module
180
+ exists to avoid.
181
+ """
182
+ rows: List[Row] = []
183
+ opcodes = difflib.SequenceMatcher(None, pre_lines, post_lines).get_opcodes()
184
+ if all(tag == "equal" for tag, *_rest in opcodes):
185
+ return rows
186
+
187
+ for index, (tag, i1, i2, j1, j2) in enumerate(opcodes):
188
+ if tag != "equal":
189
+ for offset in range(i2 - i1):
190
+ rows.append(
191
+ (DELETED, str(i1 + offset + 1), pre_lines[i1 + offset]))
192
+ for offset in range(j2 - j1):
193
+ rows.append(
194
+ (ADDED, str(j1 + offset + 1), post_lines[j1 + offset]))
195
+ continue
196
+ # Opcodes alternate, so an equal run shows context at its head when
197
+ # a change precedes it and at its tail when one follows.
198
+ head = context if index and opcodes[index - 1][0] != "equal" else 0
199
+ tail = (context if index + 1 < len(opcodes)
200
+ and opcodes[index + 1][0] != "equal" else 0)
201
+ rows.extend(_equal_rows(post_lines, i2 - i1, j1, j2, head, tail))
202
+ return rows
203
+
204
+
205
+ def _equal_rows(post_lines, length, j1, j2, head, tail) -> List[Row]:
206
+ """One unchanged run, trimmed to `head` lines at its start and `tail`
207
+ at its end.
208
+
209
+ Numbered from the NEW side, which is what the reader is looking at
210
+ after the call: an unchanged line's two numbers diverge once anything
211
+ above it has been added or removed, and the file on disk has the new
212
+ one.
213
+
214
+ The count of what was skipped is emitted only BETWEEN two hunks --
215
+ where it says something the gutter does not, namely how far apart two
216
+ changes are. Before the first hunk and after the last there is no
217
+ second change to measure against, and the line numbers already say
218
+ where in the file the reader is, so a leading "316 unchanged lines"
219
+ would be furniture reporting the obvious.
220
+ """
221
+ if head + tail >= length:
222
+ return [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n])
223
+ for n in range(length)]
224
+ rows = [(CONTEXT, str(j1 + n + 1), post_lines[j1 + n]) for n in range(head)]
225
+ hidden = length - head - tail
226
+ if hidden > 0 and head and tail:
227
+ rows.append((ELIDED, "",
228
+ f"{hidden} unchanged line{'s' if hidden > 1 else ''}"))
229
+ rows += [(CONTEXT, str(j2 - tail + n + 1), post_lines[j2 - tail + n])
230
+ for n in range(tail)]
231
+ return rows
232
+
233
+
234
+ def _capped(rows: List[Row], max_rows: int) -> List[Row]:
235
+ """At most `max_rows`, with the remainder counted rather than dropped
236
+ silently -- M14's no-silent-caps rule, applied to a rendering."""
237
+ if max_rows <= 0 or len(rows) <= max_rows:
238
+ return rows
239
+ kept = rows[:max_rows]
240
+ hidden = len(rows) - max_rows
241
+ kept.append((ELIDED, "",
242
+ f"+{hidden} more line{'s' if hidden > 1 else ''}"))
243
+ return kept
244
+
245
+
246
+ def _render(path: str, rows: List[Row]) -> str:
247
+ # An EMPTY string when nothing changed, so a caller can treat the
248
+ # block as falsy rather than inspecting it. `write` with identical
249
+ # content is a real call and a real no-op, and a block carrying a
250
+ # path and no rows would render as a header announcing nothing.
251
+ if not rows:
252
+ return ""
253
+ width = max((len(gutter) for _kind, gutter, _text in rows), default=0)
254
+ out = [path]
255
+ for kind, gutter, text in rows:
256
+ if kind == ELIDED:
257
+ out.append(f"{_ELIDE_MARK} {text}")
258
+ continue
259
+ # A space between the sign and the number, matching what the
260
+ # renderer draws, so the copied block and the drawn block
261
+ # differ only in the indent the renderer owns. parse()
262
+ # strips the gutter, so the space costs it nothing.
263
+ out.append(
264
+ f"{_MARKS[kind]} {gutter.rjust(width)}{GUTTER_SEP}{text}")
265
+ return "\n".join(out)
@@ -0,0 +1,182 @@
1
+ """
2
+ tui/preferences.py
3
+
4
+ The TUI's remembered UI choices. Two: the last theme selected, and the
5
+ last provider/model pair chosen with /model.
6
+
7
+ A user-tier JSON store at ~/.config/venastine/ui_preferences.json,
8
+ written by the harness, sitting BESIDE settings.json rather than in it.
9
+ That split is the whole point. /theme, /effort and /model read
10
+ settings.json at startup and never write to it, because settings.json is
11
+ the one config file where a trusted project tier beats the user tier
12
+ (D29) -- a session rewriting it is a decision, not a convenience. It is
13
+ also a file a person hand-authors, and rewriting one of those reorders
14
+ and reformats what they wrote.
15
+
16
+ Remembering what you last chose is a convenience, so it gets its own
17
+ file, at the user tier only, that no project can reach. Same shape as
18
+ the two stores that already live there: core/workspace_trust.py's
19
+ trusted_projects.json and mcp_client/config.py's known_mcp_servers.json
20
+ -- expanduser at CALL time (so a moved HOME is picked up, and tests
21
+ redirect without a restart), versioned, and failing soft on anything it
22
+ cannot read.
23
+
24
+ Each record stores the choice AND the settings.json value it was chosen
25
+ against, which is what makes an edited settings.json re-assert itself
26
+ instead of being silently outranked forever. Same staleness rule as the
27
+ trust store's content hash and the MCP store's entry digest, applied to
28
+ a preference rather than to a consent.
29
+
30
+ TWO RECORDS, ONE FILE, AND THEREFORE READ-MODIFY-WRITE (§43, RM4). The
31
+ theme and the model are chosen at different moments by different
32
+ commands. A writer that serialised only its own fields would silently
33
+ drop the other's -- /theme forgetting the model, then /model forgetting
34
+ the theme, each looking correct in its own test. `_remember` reads the
35
+ store first and updates its own keys, and `load_theme` / `load_model`
36
+ each validate only their own, so a store written before the model
37
+ existed still yields a theme.
38
+
39
+ Nothing in core/ is imported, and nothing here knows a theme name or a
40
+ provider name: this module stores strings, and tui/app.py decides
41
+ whether they still mean anything. The read and the atomic write are
42
+ json_store's, at the project root -- shared with the three sibling
43
+ stores and reachable from every layer, so borrowing them costs no edge
44
+ into core/ and the sentence above still holds.
45
+ """
46
+
47
+ import logging
48
+ import os
49
+
50
+ from json_store import read_versioned, write_json_atomic
51
+
52
+ logger = logging.getLogger(__name__)
53
+
54
+ # Bumped when the SHAPE changes. An unknown version reads as no memory --
55
+ # which costs one launch on the defaults, so there is no need for the MCP
56
+ # store's careful legacy handling: nothing here was consented to.
57
+ #
58
+ # NOT bumped when the model record was added (§43): the model keys are
59
+ # optional and their absence already reads as "nothing remembered", so a
60
+ # v1 store holding only a theme keeps working and gains the new keys the
61
+ # first time /model is used. Bumping would have thrown away every
62
+ # existing user's theme once, to express something the load functions
63
+ # already handle.
64
+ STORE_VERSION = 1
65
+
66
+
67
+ def store_path() -> str:
68
+ # Resolved at call time, not import time, matching
69
+ # workspace_trust._trust_store_path for the same two reasons: tests
70
+ # redirect it, and a moved config directory is picked up without a
71
+ # restart.
72
+ return os.path.expanduser("~/.config/venastine/ui_preferences.json")
73
+
74
+
75
+ def _read_raw() -> dict:
76
+ """The store as it stands, or {} for anything unusable.
77
+
78
+ {} covers every unhappy case -- missing file, unreadable file, not
79
+ an object, a version this build does not know -- because the worst
80
+ consequence of forgetting a preference is starting on the configured
81
+ one. Contrast with the trust store, which fails closed for a security
82
+ reason; there is no security property here to preserve.
83
+
84
+ Shared by the loaders and by `_remember`, so a write can only ever
85
+ preserve records this build would also have read.
86
+ """
87
+ return read_versioned(store_path(), STORE_VERSION,
88
+ "starting on the configured preferences.")
89
+
90
+
91
+ def load_theme() -> dict | None:
92
+ """The remembered theme, or None for "nothing remembered".
93
+
94
+ None also covers a missing or non-string theme, for _read_raw's
95
+ reason.
96
+
97
+ `settings_theme` is deliberately allowed to be None: that is the
98
+ recorded fact "settings.json named no theme when this was chosen",
99
+ and it has to stay distinguishable from "settings.json said
100
+ dark-plain".
101
+ """
102
+ data = _read_raw()
103
+ theme = data.get("theme")
104
+ settings_theme = data.get("settings_theme")
105
+ if not isinstance(theme, str):
106
+ return None
107
+ if settings_theme is not None and not isinstance(settings_theme, str):
108
+ return None
109
+ return {"theme": theme, "settings_theme": settings_theme}
110
+
111
+
112
+ def load_model() -> dict | None:
113
+ """The remembered provider/model pair, or None (§43, RM3).
114
+
115
+ A PAIR, always. A model name means nothing against the wrong
116
+ provider, so half a record is no record: if either side is missing
117
+ or is not a string, this returns None rather than mixing a
118
+ remembered model with a configured provider.
119
+
120
+ The two `settings_*` fields are the staleness key and follow
121
+ `settings_theme` exactly -- None is the recorded fact "settings.json
122
+ named no default_provider/default_model when this was chosen", which
123
+ has to stay distinguishable from an explicit value, or ADDING one of
124
+ those keys would become a silent no-op.
125
+ """
126
+ data = _read_raw()
127
+ provider = data.get("provider")
128
+ model = data.get("model")
129
+ if not isinstance(provider, str) or not isinstance(model, str):
130
+ return None
131
+ out = {"provider": provider, "model": model}
132
+ for key in ("settings_provider", "settings_model"):
133
+ value = data.get(key)
134
+ if value is not None and not isinstance(value, str):
135
+ return None
136
+ out[key] = value
137
+ return out
138
+
139
+
140
+ def _remember(fields: dict, noun: str) -> bool:
141
+ """Merge `fields` into the store. True if it reached disk.
142
+
143
+ READ-MODIFY-WRITE, per the module docstring: the theme record and
144
+ the model record share a file and are written at different moments.
145
+
146
+ The atomic write is json_store's, shared with the three sibling
147
+ stores -- _save_trust_store's reasoning, which that module now states
148
+ once. No 0600 is passed, because this holds no secret; the trust
149
+ store's mode protects the list of projects a user trusts.
150
+
151
+ A failure WARNS and returns False rather than raising. The TUI's
152
+ TranscriptLogHandler routes WARNING+ into the transcript, so a user
153
+ whose choice could not be saved is told rather than discovering it at
154
+ the next launch. Deliberately not latched to once per session:
155
+ unlike context_limit()'s per-model warning this fires only on a
156
+ human's own action, so someone switching again after a failure should
157
+ hear that it failed again.
158
+ """
159
+ path = store_path()
160
+ payload = dict(_read_raw())
161
+ payload.update(fields)
162
+ payload["version"] = STORE_VERSION
163
+ try:
164
+ write_json_atomic(path, payload)
165
+ except OSError as exc:
166
+ logger.warning("Could not save the %s preference to %s (%s). The "
167
+ "%s applies to this session only.", noun, path, exc,
168
+ noun)
169
+ return False
170
+ return True
171
+
172
+
173
+ def remember_theme(theme: str, settings_theme: str | None) -> bool:
174
+ return _remember({"theme": theme, "settings_theme": settings_theme},
175
+ "theme")
176
+
177
+
178
+ def remember_model(provider: str, model: str, settings_provider: str | None,
179
+ settings_model: str | None) -> bool:
180
+ return _remember({"provider": provider, "model": model,
181
+ "settings_provider": settings_provider,
182
+ "settings_model": settings_model}, "model")
package/tui/ravens.py ADDED
@@ -0,0 +1,146 @@
1
+ """
2
+ tui/ravens.py
3
+
4
+ ROADMAP_v2 §16. The two ravens, and the mapping from loop activity to a
5
+ raven state.
6
+
7
+ Deliberately data-only: this module owns the art and the state table, and
8
+ nothing else. The widgets in tui/widgets.py render it; tui/app.py decides
9
+ when the state changes. Keeping the mapping here means adding a tool never
10
+ requires touching a widget.
11
+
12
+ Why a table rather than a match on tool names inside the app: §17 (MCP)
13
+ registers tools at runtime with names nobody has written down yet, and §18
14
+ adds subagents. Unknown names resolve to WORKING rather than falling
15
+ through to an unchanged raven, so a new tool always animates something.
16
+ """
17
+
18
+ from dataclasses import dataclass
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class RavenState:
23
+ key: str
24
+ label: str
25
+ frames: tuple[str, ...] # cycled when animations are on; frames[0] is static
26
+
27
+
28
+ # Three-line art. Each state varies the head/wing so the change is legible
29
+ # at a glance in a small corner panel rather than needing the label read.
30
+ IDLE = RavenState(
31
+ "idle", "idle",
32
+ (
33
+ " __\n<o )___\n `----'",
34
+ " __\n<- )___\n `----'", # blink
35
+ ),
36
+ )
37
+
38
+ THINKING = RavenState(
39
+ "thinking", "thinking",
40
+ (
41
+ " __\n<o )___\n `--^-'",
42
+ " __\n<o )___\n `--`-'",
43
+ " __\n<o )___\n `--,-'",
44
+ ),
45
+ )
46
+
47
+ SEARCHING = RavenState(
48
+ "searching", "searching",
49
+ (
50
+ " __\n<o )___ o\n `----'",
51
+ " __\n<o )___ o\n `----'",
52
+ " __\n<o )___ o\n `----'",
53
+ ),
54
+ )
55
+
56
+ READING = RavenState(
57
+ "reading", "reading",
58
+ (
59
+ " __\n<o )___\n `--[]'",
60
+ " __\n<- )___\n `--[]'",
61
+ ),
62
+ )
63
+
64
+ EDITING = RavenState(
65
+ "editing", "editing",
66
+ (
67
+ " __\n<o )___\n `--/-'",
68
+ " __\n<o )___\n `--\\-'",
69
+ ),
70
+ )
71
+
72
+ RUNNING = RavenState(
73
+ "running", "running",
74
+ (
75
+ " __\n<o )___\n `--$-'",
76
+ " __\n<0 )___\n `--$-'",
77
+ ),
78
+ )
79
+
80
+ WAITING = RavenState(
81
+ "waiting", "waiting on you",
82
+ (
83
+ " __\n<? )___\n `----'",
84
+ " __\n<! )___\n `----'",
85
+ ),
86
+ )
87
+
88
+ WORKING = RavenState(
89
+ "working", "working",
90
+ (
91
+ " __\n<o )___\n `--*-'",
92
+ " __\n<o )___\n `--+-'",
93
+ ),
94
+ )
95
+
96
+ # Tool name -> state. Anything not listed maps to WORKING (see module
97
+ # docstring): runtime-registered MCP tools and §18 subagents must animate
98
+ # without this table being edited.
99
+ TOOL_STATES = {
100
+ "web_search": SEARCHING,
101
+ "arxiv_search": SEARCHING,
102
+ "fetch_url": SEARCHING,
103
+ "read": READING,
104
+ "load_skill": READING,
105
+ "write": EDITING,
106
+ "edit": EDITING,
107
+ "shell": RUNNING,
108
+ }
109
+
110
+
111
+ def state_for_tool(tool_name: str) -> RavenState:
112
+ return TOOL_STATES.get(tool_name, WORKING)
113
+
114
+
115
+ # --- Effort raven -----------------------------------------------------------
116
+ # A separate, one-line raven whose plumage reflects the current reasoning
117
+ # effort, so the setting is visible rather than remembered. Ordered
118
+ # least-to-most. An UNSET level renders as "auto" (the provider's own
119
+ # default, which is what effort=None sends); an unknown one renders by
120
+ # name with no bar, since its rank is exactly what we don't know.
121
+ EFFORT_PLUMAGE = {
122
+ "low": "▁",
123
+ "medium": "▃",
124
+ "high": "▅",
125
+ "xhigh": "▇",
126
+ "ultra": "▇",
127
+ "max": "█",
128
+ }
129
+
130
+
131
+ def effort_raven(effort: str | None) -> str:
132
+ """One-line effort indicator: a small raven plus a plumage bar.
133
+
134
+ An unknown level keeps its NAME but gets no plumage, rather than
135
+ borrowing "low"'s single bar. Levels are discovered at runtime from
136
+ the Models API, so a provider reporting one outside this table is a
137
+ reachable state -- and drawing it as the least-effort setting
138
+ misreports the rank while the comment above promised the neutral
139
+ display.
140
+ """
141
+ if not effort:
142
+ return "<o)~ auto"
143
+ plumage = EFFORT_PLUMAGE.get(effort)
144
+ if plumage is None:
145
+ return f"<o)~ {effort}"
146
+ return f"<o)~ {plumage * 3} {effort}"