@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
package/core/approval.py CHANGED
@@ -1,115 +1,137 @@
1
- """
2
- core/approval.py
3
-
4
- ROADMAP_v2 §25. How a run obtains human authorization for a tool call,
5
- as data rather than as a mechanism baked into one shell.
6
-
7
- There are exactly two ways an approval-gated call can proceed, and they
8
- compose:
9
-
10
- * a GRANT -- the user said yes before the run started, naming tools.
11
- * a PROVIDER -- the user is present and can be asked, per call.
12
-
13
- Neither is a policy relaxation. security/permissions.py still decides
14
- whether a tool is allowed at all and whether a call needs approval (D14,
15
- "stricter wins"); this module only carries the human's answer to the
16
- question that policy raised. That is why a grant lives on RunInfo and not
17
- in ToolContext.approval_overrides -- those OR, so they can only tighten.
18
-
19
- §23 CARRIED OUT the generalisation this module used to anticipate.
20
- `ApprovalProvider` and `ReviewConsent` both lived here and are gone: they
21
- were two caller-supplied ways to ask a question and block for an answer,
22
- and they are now one, `core.interaction.ResponseChannel`. What remains
23
- here is authorization DATA -- what the human already decided and how much
24
- of it is left to spend -- which is a different thing from the means of
25
- asking, and is why the two are separate modules rather than one.
26
-
27
- `RunAuthorization.provider` therefore holds a ResponseChannel now. The
28
- field keeps its name because it plays the same role in the bundle: the
29
- route by which a run can obtain an answer it does not already have.
30
-
31
- Deliberately a leaf module with no project imports -- core/interaction.py
32
- is imported for typing only, and it is itself a leaf. core/loop.py,
33
- main.py, tui/app.py and core/reasoning/ all depend on both; neither
34
- depends on them.
35
- """
36
-
37
- from dataclasses import dataclass, field
38
- from typing import TYPE_CHECKING, Optional
39
-
40
- if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
41
- from core.interaction import ResponseChannel
42
-
43
-
44
- class GrantBudget:
45
- """A ceiling on how many pre-granted calls one run may make.
46
-
47
- Pre-flight authorization trades a per-call decision for a single
48
- up-front one, so the thing it gives up is the natural bound on how
49
- many times a granted tool runs. A ten-pass pipeline reading
50
- attacker-controlled web pages is exactly where an injected loop would
51
- spend that authority, and where nobody is watching it happen.
52
-
53
- ONE instance per pipeline run, shared across all ten passes BY
54
- REFERENCE -- a budget rebuilt per pass would multiply the ceiling by
55
- ten and read as if it were enforcing one.
56
-
57
- Exhaustion is not a failure: take() returning False means the grant
58
- stops applying, so the call falls back to being ASKED. With a provider
59
- present the run continues under supervision; without one it is denied,
60
- which is what a headless run does with any gated tool anyway.
61
- """
62
-
63
- def __init__(self, limit: int) -> None:
64
- self.limit = limit
65
- self.used = 0
66
-
67
- def take(self) -> bool:
68
- """Consume one unit. False when the ceiling is reached."""
69
- if self.used >= self.limit:
70
- return False
71
- self.used += 1
72
- return True
73
-
74
- @property
75
- def exhausted(self) -> bool:
76
- return self.used >= self.limit
77
-
78
-
79
- @dataclass
80
- class RunAuthorization:
81
- """Everything a run needs to answer "may this gated call proceed?".
82
-
83
- Bundled rather than passed as three parameters because it threads
84
- through four layers -- shell, orchestrator, pass entry point, loop --
85
- and three of those only forward it. A bundle means adding a fourth
86
- kind of authorization later touches the layers that USE it, not every
87
- layer it passes through.
88
-
89
- granted_tools: names authorised before the run. Only meaningful for
90
- tools the registry reports as grantable; the loop re-checks rather
91
- than trusting the set, so a stale or hand-edited name cannot widen
92
- anything.
93
- provider: a core.interaction.ResponseChannel, present iff someone can
94
- be asked during the run. §23 replaced ApprovalProvider here; the
95
- field name stays because its role in the bundle is unchanged.
96
- budget: shared across every pass of one pipeline run.
97
- """
98
-
99
- granted_tools: set = field(default_factory=set)
100
- provider: Optional["ResponseChannel"] = None
101
- budget: Optional[GrantBudget] = None
102
- # Calls that proceeded on the grant, accumulated across every pass of
103
- # one run. Lives here rather than in module state or a per-pass return
104
- # value for the same reason the budget does: the bundle is already
105
- # shared by reference, and what the authorization was SPENT ON is
106
- # authorization state. The orchestrator points PipelineRun.granted_calls
107
- # at THIS SAME LIST at the start of the run, so the trail is on the run
108
- # at every §5 checkpoint and on the failure path.
109
- #
110
- # Not a copy taken at the end -- this comment used to say it was, which
111
- # is the design §25 rejected and the opposite of what the code does
112
- # (audit #83). Copying at the end would lose the trail on exactly the
113
- # runs most worth auditing; unit 9 mutated the share into `list(...)`
114
- # and it went red.
115
- granted_calls: list = field(default_factory=list)
1
+ """
2
+ core/approval.py
3
+
4
+ ROADMAP_v2 §25. How a run obtains human authorization for a tool call,
5
+ as data rather than as a mechanism baked into one shell.
6
+
7
+ There are exactly two ways an approval-gated call can proceed, and they
8
+ compose:
9
+
10
+ * a GRANT -- the user said yes before the run started, naming tools.
11
+ * a PROVIDER -- the user is present and can be asked, per call.
12
+
13
+ Neither is a policy relaxation. security/permissions.py still decides
14
+ whether a tool is allowed at all and whether a call needs approval (D14,
15
+ "stricter wins"); this module only carries the human's answer to the
16
+ question that policy raised. That is why a grant lives on RunInfo and not
17
+ in ToolContext.approval_overrides -- those OR, so they can only tighten.
18
+
19
+ §23 CARRIED OUT the generalisation this module used to anticipate.
20
+ `ApprovalProvider` and `ReviewConsent` both lived here and are gone: they
21
+ were two caller-supplied ways to ask a question and block for an answer,
22
+ and they are now one, `core.interaction.ResponseChannel`. What remains
23
+ here is authorization DATA -- what the human already decided and how much
24
+ of it is left to spend -- which is a different thing from the means of
25
+ asking, and is why the two are separate modules rather than one.
26
+
27
+ `RunAuthorization.provider` therefore holds a ResponseChannel now. The
28
+ field keeps its name because it plays the same role in the bundle: the
29
+ route by which a run can obtain an answer it does not already have.
30
+
31
+ Deliberately a leaf module with no project imports -- core/interaction.py
32
+ is imported for typing only, and it is itself a leaf. core/loop.py,
33
+ main.py, tui/app.py and core/reasoning/ all depend on both; neither
34
+ depends on them.
35
+ """
36
+
37
+ import threading
38
+ from dataclasses import dataclass, field
39
+ from typing import TYPE_CHECKING, Optional
40
+
41
+ if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
42
+ from core.interaction import ResponseChannel
43
+
44
+
45
+ class GrantBudget:
46
+ """A ceiling on how many pre-granted calls one run may make.
47
+
48
+ Pre-flight authorization trades a per-call decision for a single
49
+ up-front one, so the thing it gives up is the natural bound on how
50
+ many times a granted tool runs. A ten-pass pipeline reading
51
+ attacker-controlled web pages is exactly where an injected loop would
52
+ spend that authority, and where nobody is watching it happen.
53
+
54
+ ONE instance per pipeline run, shared across all ten passes BY
55
+ REFERENCE -- a budget rebuilt per pass would multiply the ceiling by
56
+ ten and read as if it were enforcing one.
57
+
58
+ Exhaustion is not a failure: take() returning False means the grant
59
+ stops applying, so the call falls back to being ASKED. With a provider
60
+ present the run continues under supervision; without one it is denied,
61
+ which is what a headless run does with any gated tool anyway.
62
+
63
+ §47 slice 8: GUARDED, because the sentence above -- one instance
64
+ shared by reference -- is exactly what makes it a shared mutable under
65
+ threads. `take()` is a read-modify-write, so two children reading
66
+ `used` before either writes it both proceed, and the ceiling that is
67
+ the whole point of the class is exceeded. Guarded rather than copied
68
+ per child for the reason the sharing exists at all: a budget rebuilt
69
+ per branch multiplies the ceiling by the branch count while reading as
70
+ if it enforced one.
71
+ """
72
+
73
+ def __init__(self, limit: int) -> None:
74
+ self.limit = limit
75
+ self.used = 0
76
+ # Not an RLock: nothing under `take` re-enters this object, and a
77
+ # plain Lock is what makes that claim checkable.
78
+ self._lock = threading.Lock()
79
+
80
+ def take(self) -> bool:
81
+ """Consume one unit. False when the ceiling is reached.
82
+
83
+ The test AND the increment are inside the lock. Guarding only the
84
+ increment would keep the overshoot -- the decision to spend is the
85
+ read, and a decision made on a stale read is the defect.
86
+ """
87
+ with self._lock:
88
+ if self.used >= self.limit:
89
+ return False
90
+ self.used += 1
91
+ return True
92
+
93
+ @property
94
+ def exhausted(self) -> bool:
95
+ # One read of one int, so no lock: the answer is a snapshot either
96
+ # way, and every CALLER that acts on it goes through take(), which
97
+ # re-decides under the lock. This property is for reporting.
98
+ return self.used >= self.limit
99
+
100
+
101
+ @dataclass
102
+ class RunAuthorization:
103
+ """Everything a run needs to answer "may this gated call proceed?".
104
+
105
+ Bundled rather than passed as three parameters because it threads
106
+ through four layers -- shell, orchestrator, pass entry point, loop --
107
+ and three of those only forward it. A bundle means adding a fourth
108
+ kind of authorization later touches the layers that USE it, not every
109
+ layer it passes through.
110
+
111
+ granted_tools: names authorised before the run. Only meaningful for
112
+ tools the registry reports as grantable; the loop re-checks rather
113
+ than trusting the set, so a stale or hand-edited name cannot widen
114
+ anything.
115
+ provider: a core.interaction.ResponseChannel, present iff someone can
116
+ be asked during the run. §23 replaced ApprovalProvider here; the
117
+ field name stays because its role in the bundle is unchanged.
118
+ budget: shared across every pass of one pipeline run.
119
+ """
120
+
121
+ granted_tools: set = field(default_factory=set)
122
+ provider: Optional["ResponseChannel"] = None
123
+ budget: Optional[GrantBudget] = None
124
+ # Calls that proceeded on the grant, accumulated across every pass of
125
+ # one run. Lives here rather than in module state or a per-pass return
126
+ # value for the same reason the budget does: the bundle is already
127
+ # shared by reference, and what the authorization was SPENT ON is
128
+ # authorization state. The orchestrator points PipelineRun.granted_calls
129
+ # at THIS SAME LIST at the start of the run, so the trail is on the run
130
+ # at every §5 checkpoint and on the failure path.
131
+ #
132
+ # Not a copy taken at the end -- this comment used to say it was, which
133
+ # is the design §25 rejected and the opposite of what the code does
134
+ # (audit #83). Copying at the end would lose the trail on exactly the
135
+ # runs most worth auditing; unit 9 mutated the share into `list(...)`
136
+ # and it went red.
137
+ granted_calls: list = field(default_factory=list)
@@ -0,0 +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