@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/tui/meters.py CHANGED
@@ -1,364 +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
- - `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
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