@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/call_view.py CHANGED
@@ -1,364 +1,364 @@
1
- """
2
- core/call_view.py
3
-
4
- ROADMAP_v3 §55 (TR6-TR15). What ONE tool call's view shows: the whole
5
- command the agent ran, and what it printed.
6
-
7
- WHY THERE WAS NOTHING TO SHOW. A successful tool's result reached the model
8
- and no screen. `tui/app.py`'s `tool_result` branch writes a transcript line
9
- only when the call FAILED, plus an inline diff for `write` and `edit`; the
10
- command itself is a one-line 140-character `param_digest`. And
11
- `core/replay.py` skips `role == "tool"` rows outright (T4), because "a
12
- grounding-heavy thread carries hundreds of kilobytes of fetched page text in
13
- its tool_result rows; replaying that would bury the conversation in the
14
- material the conversation was about".
15
-
16
- T4 IS STILL RIGHT, AND IT IS WHY THIS IS A PANE (TR6). The question §55
17
- asks is not "should tool output be in the transcript" -- T4 answered that
18
- and the answer has not changed -- but "can a reader reach it on purpose".
19
- A pane is reachable and never in the way; an expanding block in the
20
- transcript would be T4 undone by a feature, and would cost a full
21
- `rerender()` and the reader's scroll position every time it was toggled.
22
-
23
- NOTHING IS RETAINED FOR THIS (TR8). Measured before a line was written:
24
- `core/memory.add_tool_result` persists `str(result)` to the messages table
25
- keyed by `tool_call_id`, and `core/client.py` hands the provider that SAME
26
- string. So the archive already holds, byte for byte, what the agent was
27
- given -- SS18's promise reaching a one-shot call for free. There is no cap
28
- to choose, no eviction policy, and a restart costs nothing.
29
-
30
- WHY IT IS HERE AND NOT IN `tui/`. core/session_view.py's reason, one
31
- subject over: D12 makes the CLI a permanent fallback, so what may be shown
32
- for a call is a policy decision that must not differ between the two
33
- shells. Each shell decides how to paint the entries; this decides what they
34
- are. Both shells paint them since ROADMAP_v3 §89: the TUI on a ctrl+click,
35
- the CLI on `/call N` (`cli_commands.py`), which closed TECHNICAL_DEBT 45.
36
-
37
- THE PRICE OF `str(result)` IS READABILITY, AND IT IS PAID HERE (TR9). The
38
- stored string is a Python repr -- `{'stdout': 'hello\\n', ...}` -- so the
39
- newlines a reader wants are two characters. `ast.literal_eval` turns it
40
- back into the dict whenever it round-trips, and the raw string is drawn
41
- when it does not. The fallback is never WRONG: it is what the model read.
42
- It is not a security boundary either, because `literal_eval` evaluates
43
- nothing; and a hostile nesting cannot exhaust the stack here, because
44
- `check_output_policy`'s `_MAX_SCAN_DEPTH` already failed CLOSED on anything
45
- deeper than twelve levels before this string was ever written. What the
46
- fallback is actually for is a repr that was never a literal --
47
- `<Foo object at 0x7f…>` from a tool returning something exotic.
48
-
49
- REDACTED FOR DISPLAY, BOTH HALVES, AND THEY ARE NOT SYMMETRIC (TR15). The
50
- RESULT was redacted inside `registry.dispatch`, so running it through
51
- `check_output_policy` again is idempotent and costs one walk --
52
- core/session_wake.py says why a local copy would be the implementation
53
- that drifts. The PARAMS were never redacted at rest: `param_digest`
54
- redacts for DISPLAY and the archive keeps what the model sent, so this
55
- pane is a NEW place a credential could surface, and that is why the params
56
- go through the real policy rather than being trusted because they are
57
- "only arguments".
58
- """
59
-
60
- from __future__ import annotations
61
-
62
- import ast
63
- from typing import Optional
64
- from uuid import UUID
65
-
66
- from core.session_view import ViewEntry, output_lines, tail_chars
67
- from safety.policy_enforcement import check_output_policy
68
- from storage import archive_history
69
-
70
- #: Said above a result that is not a Python literal, so a reader knows the
71
- #: escaped newlines they are looking at are the string itself rather than
72
- #: this view declining to do its job (TR9).
73
- UNPARSED = ("This result is not a Python literal, so it is shown exactly "
74
- "as the model received it.")
75
-
76
- #: Said when the call has no result row yet (TR11). D20 persists the
77
- #: assistant turn with its tool_use blocks BEFORE anything runs, so the
78
- #: command is readable the instant the line is drawn and the result
79
- #: genuinely is not there -- a real state, and one that has to be said
80
- #: rather than drawn as an empty section. `open_agent_thread`'s rule: a
81
- #: deliberate click answered with silence reads as a broken feature.
82
- NOT_FINISHED = ("Its result is not in the archive yet. This is the call, "
83
- "not what it returned.")
84
-
85
- #: Said when a call is drawn for a tool whose result row is there but
86
- #: whose assistant row is not -- a thread hand-edited, or one whose
87
- #: assistant row was written by something older. The name is unknown
88
- #: rather than guessed.
89
- UNNAMED = "tool"
90
-
91
- #: Params drawn before the rest, in this order, because the shell family
92
- #: puts the thing a reader came for in `command` and `param_digest`'s own
93
- #: ordering problem (§42, RA3) was a rationale leading the line. Every
94
- #: other param keeps the order the model sent it in -- which is a fact
95
- #: about the call, and sorting it would be this view inventing one.
96
- _LEADING = ("command", "rationale")
97
-
98
- #: `rationale` reads as `why:` here, exactly as `core/session_view.py`
99
- #: spells it. One vocabulary across the two panes: a reader who has opened
100
- #: a session view already knows what the word means.
101
- _LABELS = {"rationale": "why"}
102
-
103
-
104
- class _Budget:
105
- """How much text one section of one view may draw (TR13).
106
-
107
- PER SECTION, NOT PER VIEW, and that is the whole reason this is an
108
- object rather than a slice. One budget shared between the params and
109
- the result would let a `write` whose `content` is a large file eat
110
- the allowance before the result -- which is the half a reader opened
111
- the pane for. Two sections, one NUMBER (`tail_chars()`), so there is
112
- still a single answer to "how much output is one read".
113
- """
114
-
115
- def __init__(self, limit: int) -> None:
116
- self.left = max(0, int(limit))
117
-
118
- def take(self, text: str) -> tuple[str, int]:
119
- """`(what to draw, how many characters were left out)`."""
120
- if len(text) <= self.left:
121
- self.left -= len(text)
122
- return text, 0
123
- kept = text[:self.left]
124
- self.left = 0
125
- return kept, len(text) - len(kept)
126
-
127
-
128
- def _omitted(count: int) -> ViewEntry:
129
- """The notice a cut section carries.
130
-
131
- THE COUNT, not the word "truncated". PG4's complaint about a
132
- truncated value that says nothing: a reader who knows 180,000
133
- characters are missing knows to go to the archive, and one told only
134
- that something was cut does not know whether it was a line or a
135
- library.
136
- """
137
- return ("system", f"… {count:,} more characters, not shown here.")
138
-
139
-
140
- def _clean_params(name: str, params: dict) -> dict:
141
- """The call's params through the real output policy (TR15).
142
-
143
- FLAT, with each value starting at depth 0, which is what a tool
144
- RESULT's values do -- so the depth cap means here exactly what it
145
- means where it was designed. Wrapping them under one key to save a
146
- call would have quietly spent a level of the budget that fails
147
- closed.
148
-
149
- THE NAME IS DECORATED, which is a one-word fix to an honest-logging
150
- problem rather than a flourish. `check_output_policy` logs one
151
- WARNING naming the tool whenever it replaces something, and its
152
- sentence says "result" -- so a credential found in a call's ARGUMENTS
153
- would be reported as having been found in its output. The tool name
154
- is the only thing that message reads (verified: nothing in that
155
- function branches on it), so saying which half this was costs
156
- nothing and keeps the one place a reader learns a secret surfaced
157
- from pointing at the wrong half of the call.
158
- """
159
- return check_output_policy(f"{name} (call params)", dict(params))
160
-
161
-
162
- def _clean_result(name: str, text: str) -> str:
163
- """The stored result string, re-run through the policy (TR15).
164
-
165
- Idempotent by construction -- it was redacted at dispatch -- and run
166
- anyway, because that is what keeps this function's promise true of
167
- BOTH sources rather than of one plus an assumption about the other.
168
- core/session_view.py makes the same choice for the same reason.
169
- """
170
- return str(check_output_policy(name, {"result": text})["result"])
171
-
172
-
173
- def _parse(text: str):
174
- """`(value, True)` when the stored repr round-trips, `(None, False)`
175
- when it does not (TR9).
176
-
177
- CAUGHT BROADLY, and the reason is `_as_text`'s: this feeds a display
178
- surface, so a stored row that raises must cost its own section rather
179
- than the whole pane. The fallback is not a degraded answer either --
180
- it is the exact string the model read -- so there is nothing to gain
181
- from enumerating which exceptions `ast` can raise for input this
182
- module did not write.
183
- """
184
- try:
185
- return ast.literal_eval(text), True
186
- except Exception: # noqa: BLE001
187
- return None, False
188
-
189
-
190
- def _status(parsed, parsed_ok: bool, has_result: bool) -> str:
191
- """The clause after the tool's name in the header.
192
-
193
- "finished" FOR AN UNPARSED RESULT, rather than a guess. Whether a
194
- call failed is a fact about a key in its result dict, and a string
195
- this module could not read is a string it cannot answer that about.
196
- Searching the raw text for `'error'` would be a guess wearing the
197
- clothes of a fact, which is the instrument-that-lies shape batches
198
- 118 and 119 each paid for once.
199
- """
200
- if not has_result:
201
- return "has not finished"
202
- if not parsed_ok:
203
- return "finished"
204
- if isinstance(parsed, dict):
205
- if "error" in parsed:
206
- return "failed"
207
- code = parsed.get("return_code")
208
- if isinstance(code, int) and not isinstance(code, bool):
209
- return f"exit code {code}"
210
- return "succeeded"
211
-
212
-
213
- def _keyed(key: str, value, budget: _Budget) -> list[ViewEntry]:
214
- """One key of a params or result dict, as entries.
215
-
216
- INLINE WHEN IT HAS NO NEWLINE, and there is no length threshold
217
- beside that test on purpose: a long single-line value is something
218
- the transcript already wraps, and a second number deciding when a
219
- row becomes a block would be a number with no measurement behind it.
220
- A value WITH newlines becomes a labelled block, because that is the
221
- case §55 exists for -- a heredoc, an inline `python3 - <<EOF` -- and
222
- one entry holding newlines shears its own left edge (output_lines).
223
-
224
- AN EMPTY STRING IS DROPPED and a falsy non-string is not. `stderr:
225
- ''` is noise on a call that succeeded; `return_code: 0` is the fact
226
- a reader came for, and `if not value` would have eaten it.
227
- """
228
- label = _LABELS.get(key, key)
229
- if isinstance(value, str):
230
- if not value:
231
- return []
232
- text = value
233
- else:
234
- # repr, NOT json.dumps. These values are Python literals already
235
- # -- either straight from `literal_eval` or JSON-decoded out of
236
- # the archive -- so repr shows what is actually there, where
237
- # re-encoding would redraw a tuple as a list and tell the reader
238
- # about a shape the call did not have.
239
- text = repr(value)
240
- drawn, left_out = budget.take(text)
241
- if not drawn:
242
- return [("system", f"{label}:"), _omitted(left_out)]
243
- rows: list[ViewEntry] = (
244
- [("system", f"{label}: {drawn}")] if "\n" not in drawn
245
- else [("system", f"{label}:")] + output_lines(drawn))
246
- if left_out:
247
- rows.append(_omitted(left_out))
248
- return rows
249
-
250
-
251
- def _call_rows(name: str, params: dict) -> list[ViewEntry]:
252
- """The tool, then its params, leading with the ones that matter."""
253
- rows: list[ViewEntry] = [("tool", f"▸ {name}")]
254
- budget = _Budget(tail_chars())
255
- clean = _clean_params(name, params)
256
- for key in _LEADING:
257
- if key in clean:
258
- rows.extend(_keyed(key, clean[key], budget))
259
- for key, value in clean.items():
260
- if key not in _LEADING:
261
- rows.extend(_keyed(key, value, budget))
262
- return rows
263
-
264
-
265
- def _result_rows(parsed, parsed_ok: bool, raw: str) -> list[ViewEntry]:
266
- """What the call returned, as entries."""
267
- budget = _Budget(tail_chars())
268
- if not parsed_ok:
269
- drawn, left_out = budget.take(raw)
270
- rows: list[ViewEntry] = [("system", UNPARSED), ("system", "result:")]
271
- rows.extend(output_lines(drawn))
272
- if left_out:
273
- rows.append(_omitted(left_out))
274
- return rows
275
- if isinstance(parsed, dict):
276
- rows = []
277
- for key, value in parsed.items():
278
- rows.extend(_keyed(key, value, budget))
279
- # Every key dropped means a dict of empty strings, or an empty
280
- # dict. Said, for NOT_FINISHED's reason: a section that renders
281
- # to nothing is indistinguishable from this view failing.
282
- return rows or [("system", "It returned nothing.")]
283
- return _keyed("result", parsed, budget)
284
-
285
-
286
- def _read(thread_id: UUID, call_id: str):
287
- """One pass over the thread's archive for one call.
288
-
289
- `(name, params, result text, whether a result row exists)`.
290
-
291
- ONE PASS, `core/session_view.stored_entries`' shape: the assistant row
292
- that made the call carries the name and the exact params the model
293
- sent, and the `tool` row carries the result as the model received it.
294
- Two reads would be two chances to disagree about which call this is.
295
-
296
- KEYED BY THE MODEL'S CALL ID, which is unique to the call and is what
297
- a tool line carries anyway -- the same reason stored_entries refuses
298
- to key a session by its per-process `s1` counter.
299
- """
300
- name: Optional[str] = None
301
- params: dict = {}
302
- result_text = ""
303
- has_result = False
304
- for message in archive_history(thread_id):
305
- role = message.get("role")
306
- if role == "assistant":
307
- for made in message.get("tool_calls") or []:
308
- if str(made.get("id") or "") == str(call_id):
309
- name = str(made.get("name") or "") or None
310
- found = made.get("input")
311
- params = found if isinstance(found, dict) else {}
312
- elif role == "tool":
313
- if str(message.get("tool_call_id") or "") == str(call_id):
314
- # LAST WINS, and it cannot happen twice: a tool_call_id is
315
- # the model's own and M4's pairing is one result per call.
316
- # Written as an assignment rather than a break because the
317
- # assistant row can come after the tool row in a thread
318
- # whose rows were written out of order, and stopping early
319
- # would then lose the name.
320
- result_text = _as_text(message.get("content"))
321
- has_result = True
322
- return name, params, result_text, has_result
323
-
324
-
325
- def _as_text(value: object) -> str:
326
- """core/session_view.py's `_as_text`, for the one shape this file reads.
327
-
328
- A tool row's content is written as a string by
329
- `memory.add_tool_result`, so nothing else should arrive -- but a
330
- stored row is data, and reading it as though its shape were
331
- guaranteed is how a display surface raises on somebody else's thread.
332
- """
333
- if isinstance(value, str):
334
- return value
335
- return "" if value is None else str(value)
336
-
337
-
338
- def call_entries(thread_id: UUID, call_id: str) -> list[ViewEntry]:
339
- """What one tool call's view shows (§55, TR6-TR15).
340
-
341
- The header names the tool and how the call ended, then the whole
342
- command -- un-collapsed, which is the half of TR1 `param_digest`
343
- cannot answer and must not try to (TR2) -- then what it printed.
344
-
345
- EMPTY when the call is not in this thread at all, which the caller
346
- turns into its own refusal. A view of nothing is worse than a
347
- sentence saying why, and the caller is the only thing that knows
348
- which pane the reader is looking at.
349
- """
350
- name, params, raw, has_result = _read(thread_id, call_id)
351
- if name is None and not has_result:
352
- return []
353
- named = name or UNNAMED
354
- result_text = _clean_result(named, raw) if has_result else ""
355
- parsed, parsed_ok = _parse(result_text) if has_result else (None, False)
356
-
357
- entries: list[ViewEntry] = [
358
- ("system", f"{named} — {_status(parsed, parsed_ok, has_result)}.")]
359
- entries.extend(_call_rows(named, params))
360
- if not has_result:
361
- entries.append(("system", NOT_FINISHED))
362
- return entries
363
- entries.extend(_result_rows(parsed, parsed_ok, result_text))
364
- return entries
1
+ """
2
+ core/call_view.py
3
+
4
+ ROADMAP_v3 §55 (TR6-TR15). What ONE tool call's view shows: the whole
5
+ command the agent ran, and what it printed.
6
+
7
+ WHY THERE WAS NOTHING TO SHOW. A successful tool's result reached the model
8
+ and no screen. `tui/app.py`'s `tool_result` branch writes a transcript line
9
+ only when the call FAILED, plus an inline diff for `write` and `edit`; the
10
+ command itself is a one-line 140-character `param_digest`. And
11
+ `core/replay.py` skips `role == "tool"` rows outright (T4), because "a
12
+ grounding-heavy thread carries hundreds of kilobytes of fetched page text in
13
+ its tool_result rows; replaying that would bury the conversation in the
14
+ material the conversation was about".
15
+
16
+ T4 IS STILL RIGHT, AND IT IS WHY THIS IS A PANE (TR6). The question §55
17
+ asks is not "should tool output be in the transcript" -- T4 answered that
18
+ and the answer has not changed -- but "can a reader reach it on purpose".
19
+ A pane is reachable and never in the way; an expanding block in the
20
+ transcript would be T4 undone by a feature, and would cost a full
21
+ `rerender()` and the reader's scroll position every time it was toggled.
22
+
23
+ NOTHING IS RETAINED FOR THIS (TR8). Measured before a line was written:
24
+ `core/memory.add_tool_result` persists `str(result)` to the messages table
25
+ keyed by `tool_call_id`, and `core/client.py` hands the provider that SAME
26
+ string. So the archive already holds, byte for byte, what the agent was
27
+ given -- SS18's promise reaching a one-shot call for free. There is no cap
28
+ to choose, no eviction policy, and a restart costs nothing.
29
+
30
+ WHY IT IS HERE AND NOT IN `tui/`. core/session_view.py's reason, one
31
+ subject over: D12 makes the CLI a permanent fallback, so what may be shown
32
+ for a call is a policy decision that must not differ between the two
33
+ shells. Each shell decides how to paint the entries; this decides what they
34
+ are. Both shells paint them since ROADMAP_v3 §89: the TUI on a ctrl+click,
35
+ the CLI on `/call N` (`cli_commands.py`), which closed TECHNICAL_DEBT 45.
36
+
37
+ THE PRICE OF `str(result)` IS READABILITY, AND IT IS PAID HERE (TR9). The
38
+ stored string is a Python repr -- `{'stdout': 'hello\\n', ...}` -- so the
39
+ newlines a reader wants are two characters. `ast.literal_eval` turns it
40
+ back into the dict whenever it round-trips, and the raw string is drawn
41
+ when it does not. The fallback is never WRONG: it is what the model read.
42
+ It is not a security boundary either, because `literal_eval` evaluates
43
+ nothing; and a hostile nesting cannot exhaust the stack here, because
44
+ `check_output_policy`'s `_MAX_SCAN_DEPTH` already failed CLOSED on anything
45
+ deeper than twelve levels before this string was ever written. What the
46
+ fallback is actually for is a repr that was never a literal --
47
+ `<Foo object at 0x7f…>` from a tool returning something exotic.
48
+
49
+ REDACTED FOR DISPLAY, BOTH HALVES, AND THEY ARE NOT SYMMETRIC (TR15). The
50
+ RESULT was redacted inside `registry.dispatch`, so running it through
51
+ `check_output_policy` again is idempotent and costs one walk --
52
+ core/session_wake.py says why a local copy would be the implementation
53
+ that drifts. The PARAMS were never redacted at rest: `param_digest`
54
+ redacts for DISPLAY and the archive keeps what the model sent, so this
55
+ pane is a NEW place a credential could surface, and that is why the params
56
+ go through the real policy rather than being trusted because they are
57
+ "only arguments".
58
+ """
59
+
60
+ from __future__ import annotations
61
+
62
+ import ast
63
+ from typing import Optional
64
+ from uuid import UUID
65
+
66
+ from core.session_view import ViewEntry, output_lines, tail_chars
67
+ from safety.policy_enforcement import check_output_policy
68
+ from storage import archive_history
69
+
70
+ #: Said above a result that is not a Python literal, so a reader knows the
71
+ #: escaped newlines they are looking at are the string itself rather than
72
+ #: this view declining to do its job (TR9).
73
+ UNPARSED = ("This result is not a Python literal, so it is shown exactly "
74
+ "as the model received it.")
75
+
76
+ #: Said when the call has no result row yet (TR11). D20 persists the
77
+ #: assistant turn with its tool_use blocks BEFORE anything runs, so the
78
+ #: command is readable the instant the line is drawn and the result
79
+ #: genuinely is not there -- a real state, and one that has to be said
80
+ #: rather than drawn as an empty section. `open_agent_thread`'s rule: a
81
+ #: deliberate click answered with silence reads as a broken feature.
82
+ NOT_FINISHED = ("Its result is not in the archive yet. This is the call, "
83
+ "not what it returned.")
84
+
85
+ #: Said when a call is drawn for a tool whose result row is there but
86
+ #: whose assistant row is not -- a thread hand-edited, or one whose
87
+ #: assistant row was written by something older. The name is unknown
88
+ #: rather than guessed.
89
+ UNNAMED = "tool"
90
+
91
+ #: Params drawn before the rest, in this order, because the shell family
92
+ #: puts the thing a reader came for in `command` and `param_digest`'s own
93
+ #: ordering problem (§42, RA3) was a rationale leading the line. Every
94
+ #: other param keeps the order the model sent it in -- which is a fact
95
+ #: about the call, and sorting it would be this view inventing one.
96
+ _LEADING = ("command", "rationale")
97
+
98
+ #: `rationale` reads as `why:` here, exactly as `core/session_view.py`
99
+ #: spells it. One vocabulary across the two panes: a reader who has opened
100
+ #: a session view already knows what the word means.
101
+ _LABELS = {"rationale": "why"}
102
+
103
+
104
+ class _Budget:
105
+ """How much text one section of one view may draw (TR13).
106
+
107
+ PER SECTION, NOT PER VIEW, and that is the whole reason this is an
108
+ object rather than a slice. One budget shared between the params and
109
+ the result would let a `write` whose `content` is a large file eat
110
+ the allowance before the result -- which is the half a reader opened
111
+ the pane for. Two sections, one NUMBER (`tail_chars()`), so there is
112
+ still a single answer to "how much output is one read".
113
+ """
114
+
115
+ def __init__(self, limit: int) -> None:
116
+ self.left = max(0, int(limit))
117
+
118
+ def take(self, text: str) -> tuple[str, int]:
119
+ """`(what to draw, how many characters were left out)`."""
120
+ if len(text) <= self.left:
121
+ self.left -= len(text)
122
+ return text, 0
123
+ kept = text[:self.left]
124
+ self.left = 0
125
+ return kept, len(text) - len(kept)
126
+
127
+
128
+ def _omitted(count: int) -> ViewEntry:
129
+ """The notice a cut section carries.
130
+
131
+ THE COUNT, not the word "truncated". PG4's complaint about a
132
+ truncated value that says nothing: a reader who knows 180,000
133
+ characters are missing knows to go to the archive, and one told only
134
+ that something was cut does not know whether it was a line or a
135
+ library.
136
+ """
137
+ return ("system", f"… {count:,} more characters, not shown here.")
138
+
139
+
140
+ def _clean_params(name: str, params: dict) -> dict:
141
+ """The call's params through the real output policy (TR15).
142
+
143
+ FLAT, with each value starting at depth 0, which is what a tool
144
+ RESULT's values do -- so the depth cap means here exactly what it
145
+ means where it was designed. Wrapping them under one key to save a
146
+ call would have quietly spent a level of the budget that fails
147
+ closed.
148
+
149
+ THE NAME IS DECORATED, which is a one-word fix to an honest-logging
150
+ problem rather than a flourish. `check_output_policy` logs one
151
+ WARNING naming the tool whenever it replaces something, and its
152
+ sentence says "result" -- so a credential found in a call's ARGUMENTS
153
+ would be reported as having been found in its output. The tool name
154
+ is the only thing that message reads (verified: nothing in that
155
+ function branches on it), so saying which half this was costs
156
+ nothing and keeps the one place a reader learns a secret surfaced
157
+ from pointing at the wrong half of the call.
158
+ """
159
+ return check_output_policy(f"{name} (call params)", dict(params))
160
+
161
+
162
+ def _clean_result(name: str, text: str) -> str:
163
+ """The stored result string, re-run through the policy (TR15).
164
+
165
+ Idempotent by construction -- it was redacted at dispatch -- and run
166
+ anyway, because that is what keeps this function's promise true of
167
+ BOTH sources rather than of one plus an assumption about the other.
168
+ core/session_view.py makes the same choice for the same reason.
169
+ """
170
+ return str(check_output_policy(name, {"result": text})["result"])
171
+
172
+
173
+ def _parse(text: str):
174
+ """`(value, True)` when the stored repr round-trips, `(None, False)`
175
+ when it does not (TR9).
176
+
177
+ CAUGHT BROADLY, and the reason is `_as_text`'s: this feeds a display
178
+ surface, so a stored row that raises must cost its own section rather
179
+ than the whole pane. The fallback is not a degraded answer either --
180
+ it is the exact string the model read -- so there is nothing to gain
181
+ from enumerating which exceptions `ast` can raise for input this
182
+ module did not write.
183
+ """
184
+ try:
185
+ return ast.literal_eval(text), True
186
+ except Exception: # noqa: BLE001
187
+ return None, False
188
+
189
+
190
+ def _status(parsed, parsed_ok: bool, has_result: bool) -> str:
191
+ """The clause after the tool's name in the header.
192
+
193
+ "finished" FOR AN UNPARSED RESULT, rather than a guess. Whether a
194
+ call failed is a fact about a key in its result dict, and a string
195
+ this module could not read is a string it cannot answer that about.
196
+ Searching the raw text for `'error'` would be a guess wearing the
197
+ clothes of a fact, which is the instrument-that-lies shape batches
198
+ 118 and 119 each paid for once.
199
+ """
200
+ if not has_result:
201
+ return "has not finished"
202
+ if not parsed_ok:
203
+ return "finished"
204
+ if isinstance(parsed, dict):
205
+ if "error" in parsed:
206
+ return "failed"
207
+ code = parsed.get("return_code")
208
+ if isinstance(code, int) and not isinstance(code, bool):
209
+ return f"exit code {code}"
210
+ return "succeeded"
211
+
212
+
213
+ def _keyed(key: str, value, budget: _Budget) -> list[ViewEntry]:
214
+ """One key of a params or result dict, as entries.
215
+
216
+ INLINE WHEN IT HAS NO NEWLINE, and there is no length threshold
217
+ beside that test on purpose: a long single-line value is something
218
+ the transcript already wraps, and a second number deciding when a
219
+ row becomes a block would be a number with no measurement behind it.
220
+ A value WITH newlines becomes a labelled block, because that is the
221
+ case §55 exists for -- a heredoc, an inline `python3 - <<EOF` -- and
222
+ one entry holding newlines shears its own left edge (output_lines).
223
+
224
+ AN EMPTY STRING IS DROPPED and a falsy non-string is not. `stderr:
225
+ ''` is noise on a call that succeeded; `return_code: 0` is the fact
226
+ a reader came for, and `if not value` would have eaten it.
227
+ """
228
+ label = _LABELS.get(key, key)
229
+ if isinstance(value, str):
230
+ if not value:
231
+ return []
232
+ text = value
233
+ else:
234
+ # repr, NOT json.dumps. These values are Python literals already
235
+ # -- either straight from `literal_eval` or JSON-decoded out of
236
+ # the archive -- so repr shows what is actually there, where
237
+ # re-encoding would redraw a tuple as a list and tell the reader
238
+ # about a shape the call did not have.
239
+ text = repr(value)
240
+ drawn, left_out = budget.take(text)
241
+ if not drawn:
242
+ return [("system", f"{label}:"), _omitted(left_out)]
243
+ rows: list[ViewEntry] = (
244
+ [("system", f"{label}: {drawn}")] if "\n" not in drawn
245
+ else [("system", f"{label}:")] + output_lines(drawn))
246
+ if left_out:
247
+ rows.append(_omitted(left_out))
248
+ return rows
249
+
250
+
251
+ def _call_rows(name: str, params: dict) -> list[ViewEntry]:
252
+ """The tool, then its params, leading with the ones that matter."""
253
+ rows: list[ViewEntry] = [("tool", f"▸ {name}")]
254
+ budget = _Budget(tail_chars())
255
+ clean = _clean_params(name, params)
256
+ for key in _LEADING:
257
+ if key in clean:
258
+ rows.extend(_keyed(key, clean[key], budget))
259
+ for key, value in clean.items():
260
+ if key not in _LEADING:
261
+ rows.extend(_keyed(key, value, budget))
262
+ return rows
263
+
264
+
265
+ def _result_rows(parsed, parsed_ok: bool, raw: str) -> list[ViewEntry]:
266
+ """What the call returned, as entries."""
267
+ budget = _Budget(tail_chars())
268
+ if not parsed_ok:
269
+ drawn, left_out = budget.take(raw)
270
+ rows: list[ViewEntry] = [("system", UNPARSED), ("system", "result:")]
271
+ rows.extend(output_lines(drawn))
272
+ if left_out:
273
+ rows.append(_omitted(left_out))
274
+ return rows
275
+ if isinstance(parsed, dict):
276
+ rows = []
277
+ for key, value in parsed.items():
278
+ rows.extend(_keyed(key, value, budget))
279
+ # Every key dropped means a dict of empty strings, or an empty
280
+ # dict. Said, for NOT_FINISHED's reason: a section that renders
281
+ # to nothing is indistinguishable from this view failing.
282
+ return rows or [("system", "It returned nothing.")]
283
+ return _keyed("result", parsed, budget)
284
+
285
+
286
+ def _read(thread_id: UUID, call_id: str):
287
+ """One pass over the thread's archive for one call.
288
+
289
+ `(name, params, result text, whether a result row exists)`.
290
+
291
+ ONE PASS, `core/session_view.stored_entries`' shape: the assistant row
292
+ that made the call carries the name and the exact params the model
293
+ sent, and the `tool` row carries the result as the model received it.
294
+ Two reads would be two chances to disagree about which call this is.
295
+
296
+ KEYED BY THE MODEL'S CALL ID, which is unique to the call and is what
297
+ a tool line carries anyway -- the same reason stored_entries refuses
298
+ to key a session by its per-process `s1` counter.
299
+ """
300
+ name: Optional[str] = None
301
+ params: dict = {}
302
+ result_text = ""
303
+ has_result = False
304
+ for message in archive_history(thread_id):
305
+ role = message.get("role")
306
+ if role == "assistant":
307
+ for made in message.get("tool_calls") or []:
308
+ if str(made.get("id") or "") == str(call_id):
309
+ name = str(made.get("name") or "") or None
310
+ found = made.get("input")
311
+ params = found if isinstance(found, dict) else {}
312
+ elif role == "tool":
313
+ if str(message.get("tool_call_id") or "") == str(call_id):
314
+ # LAST WINS, and it cannot happen twice: a tool_call_id is
315
+ # the model's own and M4's pairing is one result per call.
316
+ # Written as an assignment rather than a break because the
317
+ # assistant row can come after the tool row in a thread
318
+ # whose rows were written out of order, and stopping early
319
+ # would then lose the name.
320
+ result_text = _as_text(message.get("content"))
321
+ has_result = True
322
+ return name, params, result_text, has_result
323
+
324
+
325
+ def _as_text(value: object) -> str:
326
+ """core/session_view.py's `_as_text`, for the one shape this file reads.
327
+
328
+ A tool row's content is written as a string by
329
+ `memory.add_tool_result`, so nothing else should arrive -- but a
330
+ stored row is data, and reading it as though its shape were
331
+ guaranteed is how a display surface raises on somebody else's thread.
332
+ """
333
+ if isinstance(value, str):
334
+ return value
335
+ return "" if value is None else str(value)
336
+
337
+
338
+ def call_entries(thread_id: UUID, call_id: str) -> list[ViewEntry]:
339
+ """What one tool call's view shows (§55, TR6-TR15).
340
+
341
+ The header names the tool and how the call ended, then the whole
342
+ command -- un-collapsed, which is the half of TR1 `param_digest`
343
+ cannot answer and must not try to (TR2) -- then what it printed.
344
+
345
+ EMPTY when the call is not in this thread at all, which the caller
346
+ turns into its own refusal. A view of nothing is worse than a
347
+ sentence saying why, and the caller is the only thing that knows
348
+ which pane the reader is looking at.
349
+ """
350
+ name, params, raw, has_result = _read(thread_id, call_id)
351
+ if name is None and not has_result:
352
+ return []
353
+ named = name or UNNAMED
354
+ result_text = _clean_result(named, raw) if has_result else ""
355
+ parsed, parsed_ok = _parse(result_text) if has_result else (None, False)
356
+
357
+ entries: list[ViewEntry] = [
358
+ ("system", f"{named} — {_status(parsed, parsed_ok, has_result)}.")]
359
+ entries.extend(_call_rows(named, params))
360
+ if not has_result:
361
+ entries.append(("system", NOT_FINISHED))
362
+ return entries
363
+ entries.extend(_result_rows(parsed, parsed_ok, result_text))
364
+ return entries