@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/tui/meters.py CHANGED
@@ -1,268 +1,364 @@
1
- """
2
- tui/meters.py
3
-
4
- What a turn is costing, while it is being spent (batch 61).
5
-
6
- THE PROBLEM IS SILENCE, and it is a silence this project built on purpose.
7
- `markdown.commit_span` holds a table from its header row until a line that
8
- is not a row arrives -- and a table, like an open ``` fence, is EXEMPT from
9
- HOLD_LIMIT, the ceiling that bounds every other hold. So the gap between
10
- "the model is writing a table" and "the table appears" has no upper bound.
11
- Beside that, `tui/app.py` pauses the raven on every token delta, because a
12
- redraw loop competing with deltas is the one place animation costs
13
- responsiveness. Both decisions are right and they compose into one wrong
14
- thing: the screen is most static exactly when the harness is busiest.
15
-
16
- This module is the state behind three figures that move while that happens
17
- -- elapsed, throughput, uptime -- and the fourth that lands in the
18
- transcript when the turn ends, which is the part that says "done".
19
-
20
- PURE. No I/O, no `core/` import, no harness state, and -- the one that is
21
- easy to miss -- NO CLOCK. `tui/markdown.py`'s and `tui/diffs.py`'s rule with
22
- one addition, because nothing in `tui/` or `core/` read a clock before this
23
- batch and the first one to do it decides how every later one is tested.
24
- Every method here takes `now` as a parameter. The clock lives in `app.py`,
25
- which is the only file that has to know what a real second is; a test drives
26
- this with the numbers it chooses and needs neither a Pilot nor a real timer.
27
-
28
- WHAT THIS OWNS
29
-
30
- - `start` / `stop` -- turn boundaries, and the elapsed time between.
31
- - `set_blocked` -- the pause while a modal is waiting on a human.
32
- - `add_output_chars` -- the live estimate's numerator.
33
- - `subtitle` -- the three live figures as one string, or None.
34
- - `completion` -- the line written under the finished answer.
35
-
36
- TWO INSTRUMENTS, AND THEY ARE NOT THE SAME ONE. The live rate is an
37
- ESTIMATE from characters, because `StreamToken` carries no incremental
38
- usage and only three of the nineteen configured providers report usage on
39
- a streaming call at all (D21: OpenAI-compatible streaming returns none
40
- unless `stream_options` is sent, and Mistral rejects that parameter
41
- outright). An exact live rate would therefore read `0 tok/s` forever on
42
- sixteen providers, which is D21's own failure mode -- correct-looking
43
- output -- one layer up in the UI. The estimate also keeps MOVING during a
44
- table hold, because the deltas are still arriving; it is the renderer that
45
- is withholding, not the stream. That is the whole point of the feature, so
46
- the estimate is not a compromise here, it is the requirement.
47
-
48
- The exact figure is the completion line's, from the provider's own count,
49
- and it is marked with no tilde because it is not a guess. Where a provider
50
- reports nothing the line says the time and MAKES NO TOKEN CLAIM -- it does
51
- not print a zero, which is the difference between "we did not measure" and
52
- "the model wrote nothing".
53
- """
54
-
55
- #: Characters per token, for the live estimate ONLY. A rough divisor
56
- #: rather than a tokenizer: the exact count arrives at the end of the
57
- #: turn from the provider, so anything spent being precise here would be
58
- #: spent twice and still be wrong for whatever model is answering. The
59
- #: tilde in front of the rendered figure is this constant, admitted.
60
- CHARS_PER_TOKEN = 4
61
-
62
- #: Below this many active seconds no rate is shown. A rate over a tenth of
63
- #: a second is arithmetic on noise -- the first delta of a turn would
64
- #: render four thousand tokens a second and then collapse, which reads as a
65
- #: bug rather than as a measurement settling.
66
- RATE_FLOOR_S = 0.5
67
-
68
-
69
- def _duration(seconds: float) -> str:
70
- """A turn's length, at a granularity that does not flicker.
71
-
72
- Tenths under a minute, because that is the range a turn is usually in
73
- and a whole-second figure looks stopped. Whole seconds above it, where
74
- a tenth is noise the eye has to filter out on every redraw.
75
- """
76
- if seconds < 60:
77
- return "%.1fs" % seconds
78
- minutes, secs = divmod(int(seconds), 60)
79
- if minutes < 60:
80
- return "%dm%02ds" % (minutes, secs)
81
- hours, minutes = divmod(minutes, 60)
82
- return "%dh%02dm" % (hours, minutes)
83
-
84
-
85
- def _uptime(seconds: float) -> str:
86
- """How long this session has been on screen.
87
-
88
- COARSER than `_duration` on purpose, and the reason is the change
89
- guard in `app.py` rather than taste: a figure carrying tenths changes
90
- on every tick, so it would repaint the border twice a second forever
91
- to tell the reader something they are not watching. Minutes change a
92
- minute apart, which is how often this is worth drawing.
93
- """
94
- if seconds < 60:
95
- return "up %ds" % int(seconds)
96
- minutes = int(seconds) // 60
97
- if minutes < 60:
98
- return "up %dm" % minutes
99
- hours, minutes = divmod(minutes, 60)
100
- return "up %dh%02dm" % (hours, minutes)
101
-
102
-
103
- class TurnMeter:
104
- """Elapsed, throughput and uptime for one shell session.
105
-
106
- One object holds all three because they share a clock and a turn
107
- boundary, and two objects agreeing about when a turn started is the
108
- shape this project keeps removing.
109
- """
110
-
111
- def __init__(self):
112
- # None until the session is on screen. `app.py` begins it in
113
- # on_mount rather than __init__: "up" means the shell has been
114
- # drawing, not that an object was constructed.
115
- self._session_at = None
116
- # None while idle. This IS the busy flag as far as this object is
117
- # concerned, which is why `app.py` drives it from `_busy`'s setter
118
- # -- one funnel, so a turn cannot start without starting a clock.
119
- self._turn_at = None
120
- # The modal pause, as a pair: when the current block began, and
121
- # how much blocked time this turn has already accumulated.
122
- self._blocked_at = None
123
- self._blocked_total = 0.0
124
- self._chars = 0
125
-
126
- # -- session ------------------------------------------------------------
127
-
128
- def begin_session(self, now: float) -> None:
129
- """Idempotent: the first call wins.
130
-
131
- A second call would restart uptime, and every caller that might
132
- make one -- a remount, a screen push -- means "the session is
133
- still going", not "a new one began".
134
- """
135
- if self._session_at is None:
136
- self._session_at = now
137
-
138
- # -- the turn -----------------------------------------------------------
139
-
140
- @property
141
- def running(self) -> bool:
142
- return self._turn_at is not None
143
-
144
- def start(self, now: float) -> None:
145
- """Begin a turn. Idempotent, for `begin_session`'s reason: `_busy`
146
- is assigned True at four sites and re-assigned inside at least one
147
- of them, and the SECOND assignment must not reset the clock to
148
- zero mid-turn."""
149
- if self._turn_at is not None:
150
- return
151
- self._turn_at = now
152
- self._blocked_at = None
153
- self._blocked_total = 0.0
154
- self._chars = 0
155
-
156
- def stop(self, now: float):
157
- """End a turn; the active seconds it took, or None if none was
158
- running.
159
-
160
- None rather than 0.0 is load-bearing: `_busy` is cleared on paths
161
- where it was never set (a starter's early-return error branch runs
162
- `self._busy = False` after its own `= True`, but `on_turn_finished`
163
- can also arrive for a turn this object never saw), and a caller
164
- must be able to tell "nothing was running" from "it took no time".
165
- """
166
- if self._turn_at is None:
167
- return None
168
- elapsed = self.elapsed(now)
169
- self._turn_at = None
170
- self._blocked_at = None
171
- return elapsed
172
-
173
- def set_blocked(self, blocked: bool, now: float) -> None:
174
- """A modal is up (or is no longer up).
175
-
176
- IDEMPOTENT, and that is what lets two routes drive it without
177
- being two mechanisms. The tick reads `len(screen_stack) > 1` on
178
- every refresh, which covers every modal including ones added
179
- later; the permission path calls this directly, because with
180
- `tui.animations: false` there is no tick to notice the
181
- transition. Both land on one piece of state, so they cannot
182
- disagree about whether the clock is paused -- only about how
183
- promptly they noticed, and the earlier of the two wins.
184
- """
185
- if blocked:
186
- if self._blocked_at is None:
187
- self._blocked_at = now
188
- return
189
- if self._blocked_at is not None:
190
- self._blocked_total += max(0.0, now - self._blocked_at)
191
- self._blocked_at = None
192
-
193
- def add_output_chars(self, count: int) -> None:
194
- """Characters of answer received. The live rate's numerator.
195
-
196
- Called per token delta, INCLUDING the ones being withheld by the
197
- commit cap -- which is the point. The deltas arrive whether or not
198
- the renderer is drawing them, so this is what keeps a figure
199
- moving through a table hold.
200
- """
201
- if self._turn_at is not None:
202
- self._chars += max(0, int(count or 0))
203
-
204
- # -- reading it ---------------------------------------------------------
205
-
206
- def elapsed(self, now: float) -> float:
207
- """Active seconds in the current turn: wall clock minus the time a
208
- modal spent waiting on a human.
209
-
210
- Clamped at zero. `now` comes from a monotonic clock so it should
211
- not go backwards, but a meter is not the thing that should raise
212
- if it ever does.
213
- """
214
- if self._turn_at is None:
215
- return 0.0
216
- blocked = self._blocked_total
217
- if self._blocked_at is not None:
218
- blocked += max(0.0, now - self._blocked_at)
219
- return max(0.0, (now - self._turn_at) - blocked)
220
-
221
- def rate(self, now: float):
222
- """Estimated tokens per second, or None when it would be noise."""
223
- if self._turn_at is None or not self._chars:
224
- return None
225
- active = self.elapsed(now)
226
- if active < RATE_FLOOR_S:
227
- return None
228
- return (self._chars / CHARS_PER_TOKEN) / active
229
-
230
- def subtitle(self, now: float):
231
- """The three live figures as one string, or None when there is
232
- nothing to say yet.
233
-
234
- None before the session has begun, so a bare-built app renders
235
- the border it always rendered. Otherwise uptime is always there
236
- -- it is the half that says the shell is alive when no turn is --
237
- and the turn figures join it while one is running.
238
- """
239
- if self._session_at is None:
240
- return None
241
- parts = []
242
- if self._turn_at is not None:
243
- parts.append(_duration(self.elapsed(now)))
244
- rate = self.rate(now)
245
- if rate is not None:
246
- parts.append("~%d tok/s" % round(rate))
247
- parts.append(_uptime(max(0.0, now - self._session_at)))
248
- return " ".join(parts)
249
-
250
- def completion(self, elapsed: float, output_tokens=None) -> str:
251
- """The line written under a finished answer.
252
-
253
- `output_tokens` is the provider's own count for the turn, or None
254
- where the provider reports none. NO TOKEN CLAIM is made in that
255
- case -- not a zero, which would say the model wrote nothing on
256
- sixteen of the nineteen configured providers.
257
-
258
- The rate here carries no tilde. It is not the same instrument as
259
- the live figure: that one divides characters by a constant, this
260
- one divides the provider's count by the measured time.
261
- """
262
- text = "took %s" % _duration(elapsed)
263
- if not output_tokens:
264
- return text
265
- text += " · %s tokens out" % format(int(output_tokens), ",")
266
- if elapsed >= RATE_FLOOR_S:
267
- text += " · %d tok/s" % round(output_tokens / elapsed)
268
- return text
1
+ """
2
+ tui/meters.py
3
+
4
+ What a turn is costing, while it is being spent (batch 61).
5
+
6
+ THE PROBLEM IS SILENCE, and it is a silence this project built on purpose.
7
+ `markdown.commit_span` holds a table from its header row until a line that
8
+ is not a row arrives -- and a table, like an open ``` fence, is EXEMPT from
9
+ HOLD_LIMIT, the ceiling that bounds every other hold. So the gap between
10
+ "the model is writing a table" and "the table appears" has no upper bound.
11
+ Beside that, `tui/app.py` pauses the raven on every token delta, because a
12
+ redraw loop competing with deltas is the one place animation costs
13
+ responsiveness. Both decisions are right and they compose into one wrong
14
+ thing: the screen is most static exactly when the harness is busiest.
15
+
16
+ This module is the state behind three figures that move while that happens
17
+ -- elapsed, throughput, uptime -- and the fourth that lands in the
18
+ transcript when the turn ends, which is the part that says "done".
19
+
20
+ PURE. No I/O, no `core/` import, no harness state, and -- the one that is
21
+ easy to miss -- NO CLOCK. `tui/markdown.py`'s and `tui/diffs.py`'s rule with
22
+ one addition, because nothing in `tui/` or `core/` read a clock before this
23
+ batch and the first one to do it decides how every later one is tested.
24
+ Every method here takes `now` as a parameter. The clock lives in `app.py`,
25
+ which is the only file that has to know what a real second is; a test drives
26
+ this with the numbers it chooses and needs neither a Pilot nor a real timer.
27
+
28
+ WHAT THIS OWNS
29
+
30
+ - `start` / `stop` -- turn boundaries, and the elapsed time between.
31
+ - `set_blocked` -- the pause while a modal is waiting on a human.
32
+ - `set_tool_running` -- the pause while a TOOL is running (rate only).
33
+ - `add_output_chars` -- the live estimate's numerator.
34
+ - `subtitle` -- the three live figures as one string, or None.
35
+ - `completion` -- the line written under the finished answer.
36
+
37
+ TWO CLOCKS, AND THEY ANSWER DIFFERENT QUESTIONS (batch 118). `elapsed` is
38
+ wall clock minus the human wait, because what it answers is "how long did I
39
+ wait for this turn", and a tool taking two minutes is part of that. The RATE
40
+ divides by elapsed minus TOOL time, because what it answers is "how fast is
41
+ the model writing", and a tool running is not the model writing.
42
+
43
+ Until batch 118 there was one clock and the rate used it, so the live figure
44
+ read `~0 tok/s` on exactly the turns it exists for: it needs only fewer than
45
+ two characters per active second to round to zero, and a turn that thinks for
46
+ a minute and then runs a two-minute tool produces a handful of characters
47
+ across three minutes. The numerator was wrong in the same direction --
48
+ thinking and tool-call arguments are generated output and neither was
49
+ counted -- so both sides were fixed together or neither was.
50
+
51
+ TWO INSTRUMENTS, AND THEY ARE NOT THE SAME ONE. The live rate is an
52
+ ESTIMATE from characters, because `StreamToken` carries no incremental
53
+ usage and only three of the fifteen configured providers report usage on
54
+ a streaming call at all (D21: OpenAI-compatible streaming returns none
55
+ unless `stream_options` is sent, and Mistral rejects that parameter
56
+ outright). An exact live rate would therefore read `0 tok/s` forever on
57
+ twelve providers, which is D21's own failure mode -- correct-looking
58
+ output -- one layer up in the UI. The estimate also keeps MOVING during a
59
+ table hold, because the deltas are still arriving; it is the renderer that
60
+ is withholding, not the stream. That is the whole point of the feature, so
61
+ the estimate is not a compromise here, it is the requirement.
62
+
63
+ The exact figure is the completion line's, from the provider's own count,
64
+ and it is marked with no tilde because it is not a guess. Where a provider
65
+ reports nothing the line says the time and MAKES NO TOKEN CLAIM -- it does
66
+ not print a zero, which is the difference between "we did not measure" and
67
+ "the model wrote nothing".
68
+ """
69
+
70
+ #: Characters per token, for the live estimate ONLY. A rough divisor
71
+ #: rather than a tokenizer: the exact count arrives at the end of the
72
+ #: turn from the provider, so anything spent being precise here would be
73
+ #: spent twice and still be wrong for whatever model is answering. The
74
+ #: tilde in front of the rendered figure is this constant, admitted.
75
+ CHARS_PER_TOKEN = 4
76
+
77
+ #: Below this many active seconds no rate is shown. A rate over a tenth of
78
+ #: a second is arithmetic on noise -- the first delta of a turn would
79
+ #: render four thousand tokens a second and then collapse, which reads as a
80
+ #: bug rather than as a measurement settling.
81
+ RATE_FLOOR_S = 0.5
82
+
83
+
84
+ def _duration(seconds: float) -> str:
85
+ """A turn's length, at a granularity that does not flicker.
86
+
87
+ Tenths under a minute, because that is the range a turn is usually in
88
+ and a whole-second figure looks stopped. Whole seconds above it, where
89
+ a tenth is noise the eye has to filter out on every redraw.
90
+ """
91
+ if seconds < 60:
92
+ return "%.1fs" % seconds
93
+ minutes, secs = divmod(int(seconds), 60)
94
+ if minutes < 60:
95
+ return "%dm%02ds" % (minutes, secs)
96
+ hours, minutes = divmod(minutes, 60)
97
+ return "%dh%02dm" % (hours, minutes)
98
+
99
+
100
+ def _uptime(seconds: float) -> str:
101
+ """How long this session has been on screen.
102
+
103
+ COARSER than `_duration` on purpose, and the reason is the change
104
+ guard in `app.py` rather than taste: a figure carrying tenths changes
105
+ on every tick, so it would repaint the border twice a second forever
106
+ to tell the reader something they are not watching. Minutes change a
107
+ minute apart, which is how often this is worth drawing.
108
+ """
109
+ if seconds < 60:
110
+ return "up %ds" % int(seconds)
111
+ minutes = int(seconds) // 60
112
+ if minutes < 60:
113
+ return "up %dm" % minutes
114
+ hours, minutes = divmod(minutes, 60)
115
+ return "up %dh%02dm" % (hours, minutes)
116
+
117
+
118
+ class TurnMeter:
119
+ """Elapsed, throughput and uptime for one shell session.
120
+
121
+ One object holds all three because they share a clock and a turn
122
+ boundary, and two objects agreeing about when a turn started is the
123
+ shape this project keeps removing.
124
+ """
125
+
126
+ def __init__(self):
127
+ # None until the session is on screen. `app.py` begins it in
128
+ # on_mount rather than __init__: "up" means the shell has been
129
+ # drawing, not that an object was constructed.
130
+ self._session_at = None
131
+ # None while idle. This IS the busy flag as far as this object is
132
+ # concerned, which is why `app.py` drives it from `_busy`'s setter
133
+ # -- one funnel, so a turn cannot start without starting a clock.
134
+ self._turn_at = None
135
+ # The modal pause, as a pair: when the current block began, and
136
+ # how much blocked time this turn has already accumulated.
137
+ self._blocked_at = None
138
+ self._blocked_total = 0.0
139
+ # The tool pause, same shape as the modal one, plus a DEPTH --
140
+ # `_dispatch_parallel` can have several tools outstanding at once,
141
+ # so a boolean would un-pause on the first result while two were
142
+ # still running.
143
+ self._tool_at = None
144
+ self._tool_total = 0.0
145
+ self._tool_depth = 0
146
+ self._chars = 0
147
+
148
+ # -- session ------------------------------------------------------------
149
+
150
+ def begin_session(self, now: float) -> None:
151
+ """Idempotent: the first call wins.
152
+
153
+ A second call would restart uptime, and every caller that might
154
+ make one -- a remount, a screen push -- means "the session is
155
+ still going", not "a new one began".
156
+ """
157
+ if self._session_at is None:
158
+ self._session_at = now
159
+
160
+ # -- the turn -----------------------------------------------------------
161
+
162
+ @property
163
+ def running(self) -> bool:
164
+ return self._turn_at is not None
165
+
166
+ def start(self, now: float) -> None:
167
+ """Begin a turn. Idempotent, for `begin_session`'s reason: `_busy`
168
+ is assigned True at four sites and re-assigned inside at least one
169
+ of them, and the SECOND assignment must not reset the clock to
170
+ zero mid-turn."""
171
+ if self._turn_at is not None:
172
+ return
173
+ self._turn_at = now
174
+ self._blocked_at = None
175
+ self._blocked_total = 0.0
176
+ self._tool_at = None
177
+ self._tool_total = 0.0
178
+ self._tool_depth = 0
179
+ self._chars = 0
180
+
181
+ def stop(self, now: float):
182
+ """End a turn; the active seconds it took, or None if none was
183
+ running.
184
+
185
+ None rather than 0.0 is load-bearing: `_busy` is cleared on paths
186
+ where it was never set (a starter's early-return error branch runs
187
+ `self._busy = False` after its own `= True`, but `on_turn_finished`
188
+ can also arrive for a turn this object never saw), and a caller
189
+ must be able to tell "nothing was running" from "it took no time".
190
+ """
191
+ if self._turn_at is None:
192
+ return None
193
+ elapsed = self.elapsed(now)
194
+ self._turn_at = None
195
+ self._blocked_at = None
196
+ self._tool_at = None
197
+ self._tool_depth = 0
198
+ return elapsed
199
+
200
+ def set_blocked(self, blocked: bool, now: float) -> None:
201
+ """A modal is up (or is no longer up).
202
+
203
+ IDEMPOTENT, and that is what lets two routes drive it without
204
+ being two mechanisms. The tick reads `len(screen_stack) > 1` on
205
+ every refresh, which covers every modal including ones added
206
+ later; the permission path calls this directly, because with
207
+ `tui.animations: false` there is no tick to notice the
208
+ transition. Both land on one piece of state, so they cannot
209
+ disagree about whether the clock is paused -- only about how
210
+ promptly they noticed, and the earlier of the two wins.
211
+ """
212
+ if blocked:
213
+ if self._blocked_at is None:
214
+ self._blocked_at = now
215
+ # The two pauses MUST NOT OVERLAP, and this is the half
216
+ # that keeps them apart. Approval is asked for from inside
217
+ # a tool call, so a human wait sits inside a tool window;
218
+ # `elapsed` already removes the human wait, so letting the
219
+ # tool clock keep running across it would subtract the same
220
+ # seconds twice and could drive the rate's denominator
221
+ # negative. The tool clock is closed here and reopened when
222
+ # the modal goes away, which is `set_blocked(False)` below.
223
+ self._close_tool_window(now)
224
+ return
225
+ if self._blocked_at is not None:
226
+ self._blocked_total += max(0.0, now - self._blocked_at)
227
+ self._blocked_at = None
228
+ if self._tool_depth > 0:
229
+ self._tool_at = now
230
+
231
+ def set_tool_running(self, delta: int, now: float) -> None:
232
+ """A tool started (+1) or finished (-1).
233
+
234
+ DEPTH, NOT A BOOLEAN: `core/loop.py`'s `_dispatch_parallel` runs a
235
+ response's tool calls together, so several `tool_call_start` events
236
+ can be outstanding before the first `tool_result` arrives. The clock
237
+ is paused while the depth is above zero.
238
+
239
+ This leaves `elapsed` alone, deliberately. A tool taking two minutes
240
+ IS part of how long the turn took, and the transcript line says
241
+ `took`. It is not part of how fast the model writes, which is what
242
+ the rate claims to be -- so only the rate subtracts it.
243
+ """
244
+ if self._turn_at is None:
245
+ return
246
+ previous = self._tool_depth
247
+ self._tool_depth = max(0, previous + int(delta))
248
+ if self._tool_depth and previous == 0:
249
+ # Not while a modal is up: see set_blocked.
250
+ if self._blocked_at is None:
251
+ self._tool_at = now
252
+ elif not self._tool_depth and previous:
253
+ self._close_tool_window(now)
254
+
255
+ def _close_tool_window(self, now: float) -> None:
256
+ """Bank an open tool window, if there is one. Idempotent."""
257
+ if self._tool_at is not None:
258
+ self._tool_total += max(0.0, now - self._tool_at)
259
+ self._tool_at = None
260
+
261
+ def add_output_chars(self, count: int) -> None:
262
+ """Characters the MODEL GENERATED. The live rate's numerator.
263
+
264
+ Called per token delta, INCLUDING the ones being withheld by the
265
+ commit cap -- which is the point. The deltas arrive whether or not
266
+ the renderer is drawing them, so this is what keeps a figure moving
267
+ through a table hold.
268
+
269
+ AND INCLUDING THINKING, AND TOOL-CALL ARGUMENTS (batch 118). Both
270
+ are output the provider counts and bills, and neither reached here
271
+ before: thinking arrives as its own `LoopEvent` field, and tool-call
272
+ arguments never stream as a delta at all -- `StreamToken` carries
273
+ text, thinking, or the final response, so the arguments land whole
274
+ in the last one. Counting only the visible answer made the live
275
+ figure read `~0 tok/s` on a turn that was thinking and calling tools,
276
+ which is the turn it was built to describe.
277
+ """
278
+ if self._turn_at is not None:
279
+ self._chars += max(0, int(count or 0))
280
+
281
+ # -- reading it ---------------------------------------------------------
282
+
283
+ def elapsed(self, now: float) -> float:
284
+ """Active seconds in the current turn: wall clock minus the time a
285
+ modal spent waiting on a human.
286
+
287
+ Clamped at zero. `now` comes from a monotonic clock so it should
288
+ not go backwards, but a meter is not the thing that should raise
289
+ if it ever does.
290
+ """
291
+ if self._turn_at is None:
292
+ return 0.0
293
+ blocked = self._blocked_total
294
+ if self._blocked_at is not None:
295
+ blocked += max(0.0, now - self._blocked_at)
296
+ return max(0.0, (now - self._turn_at) - blocked)
297
+
298
+ def generating(self, now: float) -> float:
299
+ """Active seconds with a tool NOT running: the rate's denominator.
300
+
301
+ `elapsed` minus tool time. See the module docstring for why these
302
+ are two numbers rather than one -- briefly, a tool running is part
303
+ of how long the turn took and no part of how fast the model writes.
304
+
305
+ Clamped, and the clamp is doing real work rather than being
306
+ defensive: the two pauses are kept disjoint by `set_blocked`, and
307
+ if that ever stopped being true this would go negative rather than
308
+ merely wrong.
309
+ """
310
+ if self._turn_at is None:
311
+ return 0.0
312
+ tool = self._tool_total
313
+ if self._tool_at is not None:
314
+ tool += max(0.0, now - self._tool_at)
315
+ return max(0.0, self.elapsed(now) - tool)
316
+
317
+ def rate(self, now: float):
318
+ """Estimated tokens per second, or None when it would be noise."""
319
+ if self._turn_at is None or not self._chars:
320
+ return None
321
+ active = self.generating(now)
322
+ if active < RATE_FLOOR_S:
323
+ return None
324
+ return (self._chars / CHARS_PER_TOKEN) / active
325
+
326
+ def subtitle(self, now: float):
327
+ """The three live figures as one string, or None when there is
328
+ nothing to say yet.
329
+
330
+ None before the session has begun, so a bare-built app renders
331
+ the border it always rendered. Otherwise uptime is always there
332
+ -- it is the half that says the shell is alive when no turn is --
333
+ and the turn figures join it while one is running.
334
+ """
335
+ if self._session_at is None:
336
+ return None
337
+ parts = []
338
+ if self._turn_at is not None:
339
+ parts.append(_duration(self.elapsed(now)))
340
+ rate = self.rate(now)
341
+ if rate is not None:
342
+ parts.append("~%d tok/s" % round(rate))
343
+ parts.append(_uptime(max(0.0, now - self._session_at)))
344
+ return " ".join(parts)
345
+
346
+ def completion(self, elapsed: float, output_tokens=None) -> str:
347
+ """The line written under a finished answer.
348
+
349
+ `output_tokens` is the provider's own count for the turn, or None
350
+ where the provider reports none. NO TOKEN CLAIM is made in that
351
+ case -- not a zero, which would say the model wrote nothing on
352
+ twelve of the fifteen configured providers.
353
+
354
+ The rate here carries no tilde. It is not the same instrument as
355
+ the live figure: that one divides characters by a constant, this
356
+ one divides the provider's count by the measured time.
357
+ """
358
+ text = "took %s" % _duration(elapsed)
359
+ if not output_tokens:
360
+ return text
361
+ text += " · %s tokens out" % format(int(output_tokens), ",")
362
+ if elapsed >= RATE_FLOOR_S:
363
+ text += " · %d tok/s" % round(output_tokens / elapsed)
364
+ return text