@yahyahammad/venastine 0.3.8 → 0.3.10

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 (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
package/core/replay.py CHANGED
@@ -1,315 +1,315 @@
1
- """
2
- core/replay.py
3
-
4
- Turns a stored thread back into something a shell can display
5
- (ROADMAP_v2 §27, bug 1).
6
-
7
- WHY THIS EXISTS AT ALL. Resuming a thread loaded its history correctly and
8
- showed NOTHING: `ConversationMemory(thread_id=...)` reads the full history
9
- at construction, but the TUI's picker callback swapped the object and wrote
10
- one line, and `main.py --thread` printed "Resuming thread: <uuid>" and
11
- dropped straight into the prompt. In the TUI it was worse than blank -- the
12
- PREVIOUS thread's transcript stayed on screen under the new thread's id, so
13
- the screen actively lied about which conversation was loaded.
14
-
15
- WHY IT IS ONE FUNCTION AND NOT TWO RENDERERS. D12 makes the CLI a permanent
16
- fallback, so both shells replay (§27 T5, §26's L6 again). What may be shown,
17
- and in what form, is a policy decision that must not differ between them --
18
- so the policy lives here and each shell only decides how to paint the
19
- entries it is handed. §26 spent a decision (L2, "one translation site") on
20
- exactly this shape.
21
-
22
- THE ARCHIVE, NEVER THE DERIVED VIEW (T3). `storage.archive_history()`
23
- returns every message ever written, compaction or not.
24
- `ConversationMemory.messages` on a compacted thread BEGINS with the
25
- synthesized summary that §21's M8 says must never be mistaken for something
26
- a person said -- and replaying it would render harness-generated text under
27
- a `you ›` label, which is precisely the mistake M8 exists to prevent. It
28
- also means a replayed thread shows what was originally said rather than a
29
- condensation of it, which is what a human resuming a conversation is looking
30
- for.
31
-
32
- THE LIVE VIEW SHOWS MORE THAN THIS ONE, DELIBERATELY (§41). Since batch 41
33
- the TUI renders a `write` or an `edit` as an inline diff, and a REPLAYED one
34
- here still shows `param_digest`. That is not a gap to close: a replay reads
35
- the archive, which records what was called and never what the file held at
36
- the time, so the digest is genuinely all this function has. The live view is
37
- better informed because it was there.
38
-
39
- REASONING IS REPLAYED, SINCE §44. §38 captured thinking for display and
40
- persisted none of it, so reopening a thread showed the answers with the
41
- reasoning silently missing -- the same conversation rendered two different
42
- ways depending on whether the session had been closed. The blocks are
43
- stored now (storage.MessageLog.thinking) and _reasoning_text pulls the
44
- prose back out of them. What a shell does with the entry is still the
45
- shell's: the TUI honours tui.show_thinking, because that is a display
46
- setting rather than a fact about the thread.
47
-
48
- TOOL RESULTS ARE SKIPPED, TOOL CALLS ARE ONE LINE (T4). A grounding-heavy
49
- thread carries hundreds of kilobytes of fetched page text in its
50
- `tool_result` rows; replaying that would bury the conversation in the
51
- material the conversation was about. The call is what says what happened,
52
- and `param_digest` says WHICH url or query -- redacted, because a tool
53
- argument can carry a credential and this is now the third place one could
54
- surface.
55
-
56
- T4 IS UNCHANGED BY §55, AND §55 IS WHY IT CAN STAY. A result is still not
57
- replayed into the conversation; it is now REACHABLE from the line that
58
- produced it, because every tool line carries `(OPENS_CALL, call id)` and
59
- `core/call_view.py` reads the same archive on demand (TR6/TR7). That is
60
- the distinction worth keeping straight if either side is ever revisited:
61
- T4 is about what a replay PUTS IN FRONT of a reader, and §55 is about what
62
- a reader can ask for. A feature that inlined the output would be T4 undone
63
- rather than extended.
64
- """
65
-
66
- from __future__ import annotations
67
-
68
- from typing import Optional
69
- from uuid import UUID
70
-
71
- from storage import archive_history
72
- from tools.registry import registry
73
-
74
- #: One replayed entry: (role, text, links). The roles are transcript palette
75
- #: roles (tui/themes.role_styles), so the TUI can paint them with what it
76
- #: already has and the CLI can label them. Deliberately NOT the neutral
77
- #: message shape -- a caller of this function is rendering, not reasoning
78
- #: about history, and handing it messages would invite a second policy
79
- #: decision about tool results at the call site.
80
- #:
81
- #: `links` is batch 65's, and it does not narrow the sentence above: a
82
- #: click target is a RENDERING fact about a line, not part of what was
83
- #: said. It is here because the alternative is worse -- a tool line's
84
- #: digest truncates a long URL, so without it a resumed thread would draw
85
- #: the same characters as a live turn and quietly refuse to open them,
86
- #: which is the one conversation rendered two ways that Section 44 removed
87
- #: for thinking spans. Empty for every entry that is not a tool call.
88
- #:
89
- #: `opens` is §47's, widened by ROADMAP_v3 §49 (SS14) and again by §55
90
- #: (TR7): `(kind, call id)` for a tool line, and `()` only where there is
91
- #: no call id to carry. The id is the model's own id for the call that
92
- #: drew the line, and the kind is `OPENS_THREAD`, `OPENS_SESSION` or
93
- #: `OPENS_CALL` -- the registry is asked, so this file does not have to
94
- #: know that `spawn_subagent` is special and cannot come to disagree with
95
- #: the TUI about which lines are openable.
96
- #:
97
- #: SINCE §55 THE GATE IS THE ID, NOT THE KIND. `registry.opens()` has no
98
- #: empty answer any more, so an unarmed line is one whose call the archive
99
- #: cannot be asked about rather than one whose tool declared nothing.
100
- #: It does not widen the sentence above either: a caller is still
101
- #: rendering rather than reasoning about history, and what a line opened
102
- #: is a fact about the LINE. Without it a resumed conversation would draw
103
- #: `▸ spawn_subagent` exactly as the live turn did and refuse to open it
104
- #: -- the same divergence §44 removed for thinking spans, and batch 65
105
- #: for a truncated URL.
106
- #:
107
- #: IT CARRIES THE KIND, not just the id, and that is what SS14 needed:
108
- #: a `▸ shell_background` line opens a SESSION, which is read from the
109
- #: manager or rebuilt from the wake rows it wrote rather than replayed
110
- #: from the archive. A bare id would have left the reader on the other
111
- #: side of the click guessing, and guessing by tool name there is the
112
- #: second copy this slot exists to avoid.
113
- ReplayEntry = tuple[str, str, tuple[str, ...], tuple]
114
-
115
-
116
- def replay_entries(thread_id: UUID) -> list[ReplayEntry]:
117
- """A stored thread as display entries, oldest first (§27 T3/T4).
118
-
119
- Empty for a thread with no messages -- a `/new` thread that was never
120
- used is a real state, and the shells write their own "nothing here yet"
121
- line rather than this function inventing one.
122
- """
123
- entries: list[ReplayEntry] = []
124
- for message in archive_history(thread_id):
125
- role = message.get("role")
126
- if role == "user":
127
- text = _as_text(message.get("content"))
128
- if message.get("harness"):
129
- # ROADMAP_v3 §49 (SS5). The HARNESS wrote this row -- a
130
- # background session's result -- so it must not replay under
131
- # `you ›`, which is M8's mistake for the compaction summary.
132
- # Its first line only, for T4's reason: the rest is program
133
- # output the model was given, which can run to thousands of
134
- # lines and would bury the conversation it interrupted.
135
- header = text.split("\n", 1)[0].strip()
136
- if header:
137
- entries.append(("wake", header, (), ()))
138
- elif text:
139
- entries.append(("user", text, (), ()))
140
- # Batch 91. The run this message started FAILED, and why. Right
141
- # after it, because nothing else from that run was ever written:
142
- # without this a subagent whose first call failed replays as its
143
- # task and nothing else, which is indistinguishable from a run
144
- # still thinking. `error` is a harness voice (META_ROLES), so
145
- # /copy conversation leaves it out as it leaves out the live
146
- # `[error: ...]` line.
147
- failure = message.get("error")
148
- if failure:
149
- entries.append(("error", f"This run failed: {failure}", (), ()))
150
- elif role == "assistant":
151
- entries.extend(step_entries(
152
- _reasoning_text(message.get("thinking")),
153
- _as_text(message.get("text")),
154
- message.get("tool_calls") or []))
155
- # role == "tool": skipped by T4. Not a gap -- see the module
156
- # docstring. The CALL above is the record that it happened.
157
- return entries
158
-
159
-
160
- def step_entries(reasoning: str, text: str, tool_calls) -> list[ReplayEntry]:
161
- """One model step as display entries: its reasoning, its text, then a
162
- line per tool call.
163
-
164
- BEFORE the answer, because that is the order it happened in and the
165
- order the live transcript drew it in (§43 RM1 puts one `venastine ›`
166
- above whichever came first). A replay that reordered the turn would be
167
- the same defect as one that reflowed it.
168
-
169
- PUBLIC SINCE ROADMAP_v3 §86 (A81), because the CLI's live turn prints
170
- each step through this as it finishes. A replay and the turn it
171
- replays are then one function's output over the same three things,
172
- which is what keeps the CLI from showing a turn one way while it runs
173
- and another way when its thread is resumed (#225).
174
- """
175
- entries: list[ReplayEntry] = []
176
- if reasoning:
177
- entries.append(("thinking", reasoning, (), ()))
178
- if text:
179
- entries.append(("assistant", text, (), ()))
180
- for call in tool_calls:
181
- entries.append(("tool", *_tool_marker(call)))
182
- return entries
183
-
184
-
185
- def reasoning_text(record) -> str:
186
- """`_reasoning_text`, for a caller outside this module (§86, A81): the
187
- CLI reads a live response's reasoning with the replay's own reader."""
188
- return _reasoning_text(record)
189
-
190
-
191
- def _reasoning_text(record) -> str:
192
- """The displayable prose out of a stored thinking record (§44).
193
-
194
- The record holds the PROVIDER'S blocks, because that is what goes back
195
- on the wire; this is the other half of the same data, for a human. Two
196
- shapes reach here -- Anthropic's `thinking` blocks and the
197
- v1-compatible `reasoning_content` one -- and both are read by field
198
- name rather than by provider, so a third costs a name and not a
199
- branch.
200
-
201
- `redacted_thinking` contributes NOTHING and that is correct: it is
202
- opaque ciphertext meaningful only to the model, so rendering it would
203
- put a wall of base64 under a `venastine ›` label. It still travels on
204
- the wire; this function is about what a person sees.
205
-
206
- The third shape arrived with ROADMAP_v3 §83 and cost the name it was
207
- promised: a ChatGPT plan's `reasoning` item keeps its readable part in
208
- `summary`, a list of `summary_text` parts, beside `encrypted_content`,
209
- which contributes nothing for `redacted_thinking`'s reason.
210
- """
211
- if not isinstance(record, dict):
212
- return ""
213
- parts = []
214
- for block in record.get("blocks") or []:
215
- if not isinstance(block, dict):
216
- continue
217
- values = [block.get("thinking") or block.get("text")]
218
- values += [part.get("text") for part in block.get("summary") or []
219
- if isinstance(part, dict)]
220
- parts.extend(value.strip() for value in values
221
- if isinstance(value, str) and value.strip())
222
- return "\n\n".join(parts)
223
-
224
-
225
- def _tool_marker(call: dict) -> tuple[str, tuple[str, ...], str]:
226
- """One line for one tool call, its click targets, and its own id.
227
-
228
- The line is the name, then a redacted param digest.
229
-
230
- The digest comes from `registry.call_digest` rather than from a
231
- local copy -- it redacts BEFORE truncating, and a second
232
- implementation is how that ordering regresses in one place and
233
- not the other (§27's note on _param_digest, and the project's
234
- canonical producer/consumer bug).
235
-
236
- Through the REGISTRY since §42 (RA3), not `param_digest` direct,
237
- because dropping a tool's declared rationale param is part of the
238
- same rule and belongs at the same producer. Importing the registry
239
- here costs nothing measurable: `main.py` is this module's only
240
- caller and has already imported it, so it is in `sys.modules`
241
- (1.9s cold at process start, 0.0s here).
242
- """
243
- name = call.get("name") or "tool"
244
- params = call.get("input")
245
- digest = registry.call_digest(name, params)
246
- # Standardised to ▸ like the live transcript (tui/app.py both modes).
247
- # Replay stays redacted via param_digest, same producer as live.
248
- #
249
- # And the click targets from the same producer for the same reason
250
- # (batch 65): a resumed thread that armed fewer URLs than the live
251
- # turn would be the archive disagreeing with the screen it came from.
252
- line = f"▸ {name} {digest}".rstrip() if digest else f"▸ {name}"
253
- # §47, widened by §49 (SS14) and §55 (TR7). The registry is what says
254
- # WHICH kind -- naming `spawn_subagent` here would be a second copy of
255
- # a fact the tool already declares, free to disagree with the TUI's
256
- # copy. `str()` because it crosses into style metadata.
257
- #
258
- # `if opens` SURVIVES AS A GUARD WITH NOTHING LEFT TO GUARD: TR7 gave
259
- # `opens()` a fallback kind, so it is never empty now and the id below
260
- # is the only thing that can leave a line unarmed. Kept rather than
261
- # deleted because the tuple is indexed on the next line, and a reader
262
- # who has not met TR7 should find the shape intact.
263
- opens = registry.opens(name)
264
- call_id = str(call.get("id") or "") if opens else ""
265
- return (line, registry.call_links(name, params),
266
- (opens[0], call_id) if call_id else ())
267
-
268
-
269
- def _as_text(value: Optional[object]) -> str:
270
- """Message content as a displayable string.
271
-
272
- `content` is whatever was persisted through json.dumps, so it is
273
- normally a string but need not be; str() rather than a type assertion,
274
- because a replay that raises on one odd row would take the whole resumed
275
- conversation with it.
276
- """
277
- if value is None:
278
- return ""
279
- return value.strip() if isinstance(value, str) else str(value)
280
-
281
-
282
- def tool_lines(thread_id: UUID) -> list[tuple[str, tuple]]:
283
- """Every tool-call line a replay of `thread_id` draws, in order, with
284
- what each one opens: `(line, (kind, call_id))`, the second slot empty
285
- for a call with no id (ROADMAP_v3 §89, register item 45).
286
-
287
- THE CLI'S ROUTE TO A CALL, and read off `replay_entries` rather than
288
- walked separately: `/call` numbers these lines, and a second walk that
289
- drew one line differently, or skipped one, would number a call the
290
- reader cannot match to the line they are looking at.
291
- """
292
- return [(entry[1], entry[3]) for entry in replay_entries(thread_id)
293
- if entry[0] == "tool"]
294
-
295
-
296
- def thread_row(thread: dict) -> str:
297
- """One row of a thread list: timestamp, first message, id (§27).
298
-
299
- The TUI's picker draws it and the CLI's `/threads` prints it, so a
300
- conversation reads the same in either list (moved from tui/screens.py
301
- by §89).
302
-
303
- `created_at` and `id` are INDEXED deliberately, not .get: a row
304
- without either has nothing honest to render -- storage.list_threads()
305
- always supplies both, and the id is the row's whole payload on
306
- selection. Only `preview` is optional (.get): §27 added it, so
307
- hand-built test rows predate it, and a missing preview degrades to an
308
- id-only row rather than a KeyError in a test-only construction.
309
- """
310
- created = thread["created_at"]
311
- stamp = (f"{created:%Y-%m-%d %H:%M}"
312
- if hasattr(created, "strftime") else str(created))
313
- preview = (thread.get("preview") or "").strip()
314
- return f"{stamp} {preview} ({thread['id']})" if preview \
315
- else f"{stamp} {thread['id']}"
1
+ """
2
+ core/replay.py
3
+
4
+ Turns a stored thread back into something a shell can display
5
+ (ROADMAP_v2 §27, bug 1).
6
+
7
+ WHY THIS EXISTS AT ALL. Resuming a thread loaded its history correctly and
8
+ showed NOTHING: `ConversationMemory(thread_id=...)` reads the full history
9
+ at construction, but the TUI's picker callback swapped the object and wrote
10
+ one line, and `main.py --thread` printed "Resuming thread: <uuid>" and
11
+ dropped straight into the prompt. In the TUI it was worse than blank -- the
12
+ PREVIOUS thread's transcript stayed on screen under the new thread's id, so
13
+ the screen actively lied about which conversation was loaded.
14
+
15
+ WHY IT IS ONE FUNCTION AND NOT TWO RENDERERS. D12 makes the CLI a permanent
16
+ fallback, so both shells replay (§27 T5, §26's L6 again). What may be shown,
17
+ and in what form, is a policy decision that must not differ between them --
18
+ so the policy lives here and each shell only decides how to paint the
19
+ entries it is handed. §26 spent a decision (L2, "one translation site") on
20
+ exactly this shape.
21
+
22
+ THE ARCHIVE, NEVER THE DERIVED VIEW (T3). `storage.archive_history()`
23
+ returns every message ever written, compaction or not.
24
+ `ConversationMemory.messages` on a compacted thread BEGINS with the
25
+ synthesized summary that §21's M8 says must never be mistaken for something
26
+ a person said -- and replaying it would render harness-generated text under
27
+ a `you ›` label, which is precisely the mistake M8 exists to prevent. It
28
+ also means a replayed thread shows what was originally said rather than a
29
+ condensation of it, which is what a human resuming a conversation is looking
30
+ for.
31
+
32
+ THE LIVE VIEW SHOWS MORE THAN THIS ONE, DELIBERATELY (§41). Since batch 41
33
+ the TUI renders a `write` or an `edit` as an inline diff, and a REPLAYED one
34
+ here still shows `param_digest`. That is not a gap to close: a replay reads
35
+ the archive, which records what was called and never what the file held at
36
+ the time, so the digest is genuinely all this function has. The live view is
37
+ better informed because it was there.
38
+
39
+ REASONING IS REPLAYED, SINCE §44. §38 captured thinking for display and
40
+ persisted none of it, so reopening a thread showed the answers with the
41
+ reasoning silently missing -- the same conversation rendered two different
42
+ ways depending on whether the session had been closed. The blocks are
43
+ stored now (storage.MessageLog.thinking) and _reasoning_text pulls the
44
+ prose back out of them. What a shell does with the entry is still the
45
+ shell's: the TUI honours tui.show_thinking, because that is a display
46
+ setting rather than a fact about the thread.
47
+
48
+ TOOL RESULTS ARE SKIPPED, TOOL CALLS ARE ONE LINE (T4). A grounding-heavy
49
+ thread carries hundreds of kilobytes of fetched page text in its
50
+ `tool_result` rows; replaying that would bury the conversation in the
51
+ material the conversation was about. The call is what says what happened,
52
+ and `param_digest` says WHICH url or query -- redacted, because a tool
53
+ argument can carry a credential and this is now the third place one could
54
+ surface.
55
+
56
+ T4 IS UNCHANGED BY §55, AND §55 IS WHY IT CAN STAY. A result is still not
57
+ replayed into the conversation; it is now REACHABLE from the line that
58
+ produced it, because every tool line carries `(OPENS_CALL, call id)` and
59
+ `core/call_view.py` reads the same archive on demand (TR6/TR7). That is
60
+ the distinction worth keeping straight if either side is ever revisited:
61
+ T4 is about what a replay PUTS IN FRONT of a reader, and §55 is about what
62
+ a reader can ask for. A feature that inlined the output would be T4 undone
63
+ rather than extended.
64
+ """
65
+
66
+ from __future__ import annotations
67
+
68
+ from typing import Optional
69
+ from uuid import UUID
70
+
71
+ from storage import archive_history
72
+ from tools.registry import registry
73
+
74
+ #: One replayed entry: (role, text, links). The roles are transcript palette
75
+ #: roles (tui/themes.role_styles), so the TUI can paint them with what it
76
+ #: already has and the CLI can label them. Deliberately NOT the neutral
77
+ #: message shape -- a caller of this function is rendering, not reasoning
78
+ #: about history, and handing it messages would invite a second policy
79
+ #: decision about tool results at the call site.
80
+ #:
81
+ #: `links` is batch 65's, and it does not narrow the sentence above: a
82
+ #: click target is a RENDERING fact about a line, not part of what was
83
+ #: said. It is here because the alternative is worse -- a tool line's
84
+ #: digest truncates a long URL, so without it a resumed thread would draw
85
+ #: the same characters as a live turn and quietly refuse to open them,
86
+ #: which is the one conversation rendered two ways that Section 44 removed
87
+ #: for thinking spans. Empty for every entry that is not a tool call.
88
+ #:
89
+ #: `opens` is §47's, widened by ROADMAP_v3 §49 (SS14) and again by §55
90
+ #: (TR7): `(kind, call id)` for a tool line, and `()` only where there is
91
+ #: no call id to carry. The id is the model's own id for the call that
92
+ #: drew the line, and the kind is `OPENS_THREAD`, `OPENS_SESSION` or
93
+ #: `OPENS_CALL` -- the registry is asked, so this file does not have to
94
+ #: know that `spawn_subagent` is special and cannot come to disagree with
95
+ #: the TUI about which lines are openable.
96
+ #:
97
+ #: SINCE §55 THE GATE IS THE ID, NOT THE KIND. `registry.opens()` has no
98
+ #: empty answer any more, so an unarmed line is one whose call the archive
99
+ #: cannot be asked about rather than one whose tool declared nothing.
100
+ #: It does not widen the sentence above either: a caller is still
101
+ #: rendering rather than reasoning about history, and what a line opened
102
+ #: is a fact about the LINE. Without it a resumed conversation would draw
103
+ #: `▸ spawn_subagent` exactly as the live turn did and refuse to open it
104
+ #: -- the same divergence §44 removed for thinking spans, and batch 65
105
+ #: for a truncated URL.
106
+ #:
107
+ #: IT CARRIES THE KIND, not just the id, and that is what SS14 needed:
108
+ #: a `▸ shell_background` line opens a SESSION, which is read from the
109
+ #: manager or rebuilt from the wake rows it wrote rather than replayed
110
+ #: from the archive. A bare id would have left the reader on the other
111
+ #: side of the click guessing, and guessing by tool name there is the
112
+ #: second copy this slot exists to avoid.
113
+ ReplayEntry = tuple[str, str, tuple[str, ...], tuple]
114
+
115
+
116
+ def replay_entries(thread_id: UUID) -> list[ReplayEntry]:
117
+ """A stored thread as display entries, oldest first (§27 T3/T4).
118
+
119
+ Empty for a thread with no messages -- a `/new` thread that was never
120
+ used is a real state, and the shells write their own "nothing here yet"
121
+ line rather than this function inventing one.
122
+ """
123
+ entries: list[ReplayEntry] = []
124
+ for message in archive_history(thread_id):
125
+ role = message.get("role")
126
+ if role == "user":
127
+ text = _as_text(message.get("content"))
128
+ if message.get("harness"):
129
+ # ROADMAP_v3 §49 (SS5). The HARNESS wrote this row -- a
130
+ # background session's result -- so it must not replay under
131
+ # `you ›`, which is M8's mistake for the compaction summary.
132
+ # Its first line only, for T4's reason: the rest is program
133
+ # output the model was given, which can run to thousands of
134
+ # lines and would bury the conversation it interrupted.
135
+ header = text.split("\n", 1)[0].strip()
136
+ if header:
137
+ entries.append(("wake", header, (), ()))
138
+ elif text:
139
+ entries.append(("user", text, (), ()))
140
+ # Batch 91. The run this message started FAILED, and why. Right
141
+ # after it, because nothing else from that run was ever written:
142
+ # without this a subagent whose first call failed replays as its
143
+ # task and nothing else, which is indistinguishable from a run
144
+ # still thinking. `error` is a harness voice (META_ROLES), so
145
+ # /copy conversation leaves it out as it leaves out the live
146
+ # `[error: ...]` line.
147
+ failure = message.get("error")
148
+ if failure:
149
+ entries.append(("error", f"This run failed: {failure}", (), ()))
150
+ elif role == "assistant":
151
+ entries.extend(step_entries(
152
+ _reasoning_text(message.get("thinking")),
153
+ _as_text(message.get("text")),
154
+ message.get("tool_calls") or []))
155
+ # role == "tool": skipped by T4. Not a gap -- see the module
156
+ # docstring. The CALL above is the record that it happened.
157
+ return entries
158
+
159
+
160
+ def step_entries(reasoning: str, text: str, tool_calls) -> list[ReplayEntry]:
161
+ """One model step as display entries: its reasoning, its text, then a
162
+ line per tool call.
163
+
164
+ BEFORE the answer, because that is the order it happened in and the
165
+ order the live transcript drew it in (§43 RM1 puts one `venastine ›`
166
+ above whichever came first). A replay that reordered the turn would be
167
+ the same defect as one that reflowed it.
168
+
169
+ PUBLIC SINCE ROADMAP_v3 §86 (A81), because the CLI's live turn prints
170
+ each step through this as it finishes. A replay and the turn it
171
+ replays are then one function's output over the same three things,
172
+ which is what keeps the CLI from showing a turn one way while it runs
173
+ and another way when its thread is resumed (#225).
174
+ """
175
+ entries: list[ReplayEntry] = []
176
+ if reasoning:
177
+ entries.append(("thinking", reasoning, (), ()))
178
+ if text:
179
+ entries.append(("assistant", text, (), ()))
180
+ for call in tool_calls:
181
+ entries.append(("tool", *_tool_marker(call)))
182
+ return entries
183
+
184
+
185
+ def reasoning_text(record) -> str:
186
+ """`_reasoning_text`, for a caller outside this module (§86, A81): the
187
+ CLI reads a live response's reasoning with the replay's own reader."""
188
+ return _reasoning_text(record)
189
+
190
+
191
+ def _reasoning_text(record) -> str:
192
+ """The displayable prose out of a stored thinking record (§44).
193
+
194
+ The record holds the PROVIDER'S blocks, because that is what goes back
195
+ on the wire; this is the other half of the same data, for a human. Two
196
+ shapes reach here -- Anthropic's `thinking` blocks and the
197
+ v1-compatible `reasoning_content` one -- and both are read by field
198
+ name rather than by provider, so a third costs a name and not a
199
+ branch.
200
+
201
+ `redacted_thinking` contributes NOTHING and that is correct: it is
202
+ opaque ciphertext meaningful only to the model, so rendering it would
203
+ put a wall of base64 under a `venastine ›` label. It still travels on
204
+ the wire; this function is about what a person sees.
205
+
206
+ The third shape arrived with ROADMAP_v3 §83 and cost the name it was
207
+ promised: a ChatGPT plan's `reasoning` item keeps its readable part in
208
+ `summary`, a list of `summary_text` parts, beside `encrypted_content`,
209
+ which contributes nothing for `redacted_thinking`'s reason.
210
+ """
211
+ if not isinstance(record, dict):
212
+ return ""
213
+ parts = []
214
+ for block in record.get("blocks") or []:
215
+ if not isinstance(block, dict):
216
+ continue
217
+ values = [block.get("thinking") or block.get("text")]
218
+ values += [part.get("text") for part in block.get("summary") or []
219
+ if isinstance(part, dict)]
220
+ parts.extend(value.strip() for value in values
221
+ if isinstance(value, str) and value.strip())
222
+ return "\n\n".join(parts)
223
+
224
+
225
+ def _tool_marker(call: dict) -> tuple[str, tuple[str, ...], str]:
226
+ """One line for one tool call, its click targets, and its own id.
227
+
228
+ The line is the name, then a redacted param digest.
229
+
230
+ The digest comes from `registry.call_digest` rather than from a
231
+ local copy -- it redacts BEFORE truncating, and a second
232
+ implementation is how that ordering regresses in one place and
233
+ not the other (§27's note on _param_digest, and the project's
234
+ canonical producer/consumer bug).
235
+
236
+ Through the REGISTRY since §42 (RA3), not `param_digest` direct,
237
+ because dropping a tool's declared rationale param is part of the
238
+ same rule and belongs at the same producer. Importing the registry
239
+ here costs nothing measurable: `main.py` is this module's only
240
+ caller and has already imported it, so it is in `sys.modules`
241
+ (1.9s cold at process start, 0.0s here).
242
+ """
243
+ name = call.get("name") or "tool"
244
+ params = call.get("input")
245
+ digest = registry.call_digest(name, params)
246
+ # Standardised to ▸ like the live transcript (tui/app.py both modes).
247
+ # Replay stays redacted via param_digest, same producer as live.
248
+ #
249
+ # And the click targets from the same producer for the same reason
250
+ # (batch 65): a resumed thread that armed fewer URLs than the live
251
+ # turn would be the archive disagreeing with the screen it came from.
252
+ line = f"▸ {name} {digest}".rstrip() if digest else f"▸ {name}"
253
+ # §47, widened by §49 (SS14) and §55 (TR7). The registry is what says
254
+ # WHICH kind -- naming `spawn_subagent` here would be a second copy of
255
+ # a fact the tool already declares, free to disagree with the TUI's
256
+ # copy. `str()` because it crosses into style metadata.
257
+ #
258
+ # `if opens` SURVIVES AS A GUARD WITH NOTHING LEFT TO GUARD: TR7 gave
259
+ # `opens()` a fallback kind, so it is never empty now and the id below
260
+ # is the only thing that can leave a line unarmed. Kept rather than
261
+ # deleted because the tuple is indexed on the next line, and a reader
262
+ # who has not met TR7 should find the shape intact.
263
+ opens = registry.opens(name)
264
+ call_id = str(call.get("id") or "") if opens else ""
265
+ return (line, registry.call_links(name, params),
266
+ (opens[0], call_id) if call_id else ())
267
+
268
+
269
+ def _as_text(value: Optional[object]) -> str:
270
+ """Message content as a displayable string.
271
+
272
+ `content` is whatever was persisted through json.dumps, so it is
273
+ normally a string but need not be; str() rather than a type assertion,
274
+ because a replay that raises on one odd row would take the whole resumed
275
+ conversation with it.
276
+ """
277
+ if value is None:
278
+ return ""
279
+ return value.strip() if isinstance(value, str) else str(value)
280
+
281
+
282
+ def tool_lines(thread_id: UUID) -> list[tuple[str, tuple]]:
283
+ """Every tool-call line a replay of `thread_id` draws, in order, with
284
+ what each one opens: `(line, (kind, call_id))`, the second slot empty
285
+ for a call with no id (ROADMAP_v3 §89, register item 45).
286
+
287
+ THE CLI'S ROUTE TO A CALL, and read off `replay_entries` rather than
288
+ walked separately: `/call` numbers these lines, and a second walk that
289
+ drew one line differently, or skipped one, would number a call the
290
+ reader cannot match to the line they are looking at.
291
+ """
292
+ return [(entry[1], entry[3]) for entry in replay_entries(thread_id)
293
+ if entry[0] == "tool"]
294
+
295
+
296
+ def thread_row(thread: dict) -> str:
297
+ """One row of a thread list: timestamp, first message, id (§27).
298
+
299
+ The TUI's picker draws it and the CLI's `/threads` prints it, so a
300
+ conversation reads the same in either list (moved from tui/screens.py
301
+ by §89).
302
+
303
+ `created_at` and `id` are INDEXED deliberately, not .get: a row
304
+ without either has nothing honest to render -- storage.list_threads()
305
+ always supplies both, and the id is the row's whole payload on
306
+ selection. Only `preview` is optional (.get): §27 added it, so
307
+ hand-built test rows predate it, and a missing preview degrades to an
308
+ id-only row rather than a KeyError in a test-only construction.
309
+ """
310
+ created = thread["created_at"]
311
+ stamp = (f"{created:%Y-%m-%d %H:%M}"
312
+ if hasattr(created, "strftime") else str(created))
313
+ preview = (thread.get("preview") or "").strip()
314
+ return f"{stamp} {preview} ({thread['id']})" if preview \
315
+ else f"{stamp} {thread['id']}"