@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/tui/app.tcss ADDED
@@ -0,0 +1,458 @@
1
+ /* ROADMAP_v2 §16. Colours come from the active theme's variables rather
2
+ than literals, so all eight themes restyle this without edits. */
3
+
4
+ #main {
5
+ width: 1fr;
6
+ }
7
+
8
+ #sidebar {
9
+ width: 22;
10
+ border-left: solid $panel;
11
+ padding: 1;
12
+ }
13
+
14
+ #transcript {
15
+ height: 1fr;
16
+ border: solid $panel;
17
+ padding: 0 1;
18
+ }
19
+
20
+ #prompt {
21
+ dock: bottom;
22
+ border: solid $primary;
23
+ }
24
+
25
+ #raven {
26
+ height: 5;
27
+ color: $accent;
28
+ content-align: center middle;
29
+ }
30
+
31
+ /* §40. Hidden unless a shipped protection is off; auto height so it
32
+ costs nothing in the shipped posture. $error because the one thing it
33
+ must not read as is decoration. */
34
+ #posture-badge {
35
+ height: auto;
36
+ color: $error;
37
+ text-style: bold;
38
+ padding: 1 0 0 0;
39
+ }
40
+
41
+ #effort-raven {
42
+ height: 2;
43
+ color: $secondary;
44
+ content-align: center middle;
45
+ }
46
+
47
+ /* #4 session usage line. Auto height and hidden until the first turn
48
+ gives it figures, like the research panel above. */
49
+ #usage-line {
50
+ height: auto;
51
+ padding-top: 1;
52
+ color: $text-muted;
53
+ }
54
+
55
+ /* §22 live research view. Auto height so it takes no sidebar space
56
+ until a run starts, and scrolls rather than pushing the ravens off
57
+ screen on a long retry loop. */
58
+ #research-progress {
59
+ height: auto;
60
+ max-height: 20;
61
+ overflow-y: auto;
62
+ padding-top: 1;
63
+ color: $text-muted;
64
+ }
65
+
66
+ PermissionScreen {
67
+ align: center middle;
68
+ }
69
+
70
+ /* Every modal screen gets one of these (#112). Nothing checked that a
71
+ screen had both a type selector and an id block for its dialog, and
72
+ five of nine never got the first -- they measured at x=0, y=0, pinned
73
+ to the top-left corner of an 80x24 terminal. The viewport test in
74
+ tests/test_tui.py pushes all nine and would catch a tenth. */
75
+
76
+ GrantPickerScreen {
77
+ align: center middle;
78
+ }
79
+
80
+ SubagentSignoffScreen {
81
+ align: center middle;
82
+ }
83
+
84
+ ConfirmScreen {
85
+ align: center middle;
86
+ }
87
+
88
+ ProjectKindScreen {
89
+ align: center middle;
90
+ }
91
+
92
+ ReviewScreen {
93
+ align: center middle;
94
+ }
95
+
96
+ #permission-dialog {
97
+ /* A VERTICAL, not a grid (batch 49). §46 left this a two-column grid
98
+ in which every child carried `column-span: 2`, so the second column
99
+ held nothing but the Deny button -- and `grid-size` being static is
100
+ the only reason the `with-headline` class existed, to tell the
101
+ stylesheet whether the screen had composed three children or four.
102
+ A Vertical does not need telling, so the template somebody had to
103
+ keep in sync is gone rather than commented.
104
+ The `1fr` row EP1 removed is still not to come back: a fractional
105
+ row inside a `height: auto` container resolves to ZERO, and it is
106
+ what made the payload absent from every permission modal this app
107
+ had ever shown. What bounds a long payload is `max-height` on the
108
+ ScrollBox -- see #permission-params-box for why not a definite
109
+ `height`, which is what EP1 shipped and what took the buttons. */
110
+ padding: 1 2;
111
+ /* 90% with a cap, not a fixed 60 (§46, EP1). Width is what decides
112
+ how many rows the notice and the reason cost, and those rows are
113
+ what the command and the payload have to share -- at 60 the
114
+ notice alone wrapped to three. Same shape as #claims-dialog and
115
+ for the same reason (#112): align cannot centre something wider
116
+ than an 80-column terminal, so the cap has to stay under it. */
117
+ width: 90%;
118
+ max-width: 96;
119
+ height: auto;
120
+ /* 22, which is what the deleted `.with-headline` block used: the
121
+ four rows the pinned command takes are the reason that block
122
+ existed, and with one template the taller shape sets the cap.
123
+ Still inside the 24-row floor #112 pins, and `height: auto` means
124
+ a short approval is nowhere near it -- `web_search` measures 14. */
125
+ max-height: 22;
126
+ border: thick $warning;
127
+ background: $surface;
128
+ }
129
+
130
+ /* The blank row between blocks was `grid-gutter: 1 2` and a Vertical
131
+ has no gutter, so it is a margin now. It is not decoration: §46 pinned
132
+ the command OUTSIDE the payload precisely so the two read as separate
133
+ claims about the call, and flush against each other they do not. */
134
+ #permission-title {
135
+ text-style: bold;
136
+ margin-bottom: 1;
137
+ }
138
+
139
+ /* The pinned subject of the question (§46, EP1), and the split
140
+ favours it deliberately: the payload below repeats the notice, the
141
+ reason and the command itself, so rows spent here buy the one thing
142
+ nothing else on the screen shows in full. Four is what a wrapped
143
+ `docker run ... bash -c "..."` needs at this width, measured; past
144
+ that it scrolls rather than growing, so a pathological command
145
+ cannot eat the modal. Deliberately not $text-muted -- this is the
146
+ one thing on the screen the reader must actually read. */
147
+ #permission-command-box {
148
+ height: auto;
149
+ max-height: 4;
150
+ margin-bottom: 1;
151
+ }
152
+
153
+ #permission-command {
154
+ text-style: bold;
155
+ }
156
+
157
+ /* `auto` WITH a `max-height`, not a definite height (batch 49,
158
+ amending EP3). EP3 got the Static half right -- a Static given
159
+ `max-height` reports no content past the bound, so its hidden rows
160
+ are gone rather than below the fold -- and the ScrollBox half wrong.
161
+ A scrollable container asked for `height: auto` does NOT resolve to
162
+ zero; EP1's `1fr` ROW did, and the box was measured inside one. With
163
+ the row `auto`, a DEFINITE height bounds what the box draws and not
164
+ what its parent reserves, so the row kept growing with the payload
165
+ and pushed the decision bar past the dialog's own `max-height`, where
166
+ it was clipped away -- on nine of fourteen modal shapes, `shell`'s
167
+ among them. `auto` with a `max-height` reports the bound upward, and
168
+ still shrinks to a two-line payload, which a definite height never
169
+ did. Do not "restore" one:
170
+ test_a_bounded_box_reserves_its_bound_not_its_content fails. */
171
+ /* 7 rows, and NO margin below it -- the arithmetic is the point.
172
+ A dialog capped at 22 has 18 rows inside it, and the title, its
173
+ margin, the pinned command, its margin and the decision bar claim 11
174
+ of them whether or not the payload wants more. Leaving the last
175
+ blank row off buys the slack a title that wraps to two lines needs,
176
+ which is the one length here that nothing bounds.
177
+ Everything past row 7 is scrollable, and on the shell modal every
178
+ line of it also appears above. */
179
+ #permission-params-box {
180
+ height: auto;
181
+ max-height: 7;
182
+ }
183
+
184
+ #permission-params {
185
+ height: auto;
186
+ color: $text-muted;
187
+ }
188
+
189
+ /* THE DECISION BAR (batch 49). One rule for every consent surface,
190
+ because the defect it answers was one defect on nine of them: the
191
+ buttons were the LAST children of a dialog whose body could outgrow
192
+ it, so they were what fell off. In a bar they are one child, and the
193
+ bounded bodies above keep the sum inside the dialog.
194
+ Centred rather than stretched: the dialog was always centred and its
195
+ contents were not -- Allow sat flush against the left padding and a
196
+ 16-wide Deny left ~22 dead columns beside it. Filling the columns
197
+ instead would have made the permissive answer a target half the width
198
+ of the modal. `height: auto` so a bar costs exactly its buttons. */
199
+ #permission-buttons,
200
+ #grant-buttons,
201
+ #review-buttons,
202
+ #question-buttons {
203
+ height: auto;
204
+ align: center middle;
205
+ }
206
+
207
+ #permission-buttons Button,
208
+ #grant-buttons Button,
209
+ #review-buttons Button,
210
+ #question-buttons Button {
211
+ margin: 0 1;
212
+ }
213
+
214
+ /* FOCUS WITHOUT `reverse` (batch 49). Textual's Button carries
215
+ `text-style: $button-focus-text-style` when focused and this theme
216
+ resolves that to `reverse`, which inverts the LABEL and nothing else
217
+ -- so a focused green Allow drew its word as green on white and read
218
+ as a highlighted selection rather than as the keyboard's position.
219
+ Bold plus a lifted background tints the whole button instead, which
220
+ is what a person actually looks for, and it composes with all
221
+ fourteen palettes because both values come from the theme rather than
222
+ from a literal (#116). */
223
+ Button:focus {
224
+ text-style: bold;
225
+ background-tint: $foreground 25%;
226
+ }
227
+
228
+ /* The answer box lines up with the options above it (batch 49).
229
+ Textual's Input takes a `tall` border on all four sides and a Button
230
+ takes one on the top and bottom only, so at the same `x` the Input's
231
+ left edge is drawn a column in from the option buttons' -- close
232
+ enough to look like a mistake and far enough to see. Dropping the two
233
+ side edges gives both widgets the same box, rather than giving the
234
+ buttons a border they do not want. */
235
+ #question-text,
236
+ #review-note {
237
+ border-left: none;
238
+ border-right: none;
239
+ }
240
+
241
+ ThreadPickerScreen {
242
+ align: center middle;
243
+ }
244
+
245
+ /* §26 claims view. Wider than the other dialogs because claim text is
246
+ prose rather than a label, and primary-bordered rather than
247
+ warning-bordered: this one only reads, it authorises nothing. */
248
+ ClaimsScreen {
249
+ align: center middle;
250
+ }
251
+
252
+ #claims-dialog {
253
+ /* 90% with a cap, not a fixed width (#112): at 96 the dialog was
254
+ wider than an 80-column terminal, and align: center middle cannot
255
+ centre something wider than its container -- the right ~16
256
+ columns, tail of every score: line included, sat off-screen. */
257
+ width: 90%;
258
+ max-width: 96;
259
+ height: auto;
260
+ max-height: 22;
261
+ padding: 1 2;
262
+ border: thick $primary;
263
+ background: $surface;
264
+ }
265
+
266
+ #claims-title {
267
+ text-style: bold;
268
+ padding-bottom: 1;
269
+ }
270
+
271
+ /* The Static keeps the colour and the box keeps the bound (batch 49);
272
+ `max-height` on the Static itself was EP3's truncation-without-scroll,
273
+ on the one screen that exists to show every claim. */
274
+ #claims-body-box {
275
+ height: auto;
276
+ max-height: 14;
277
+ }
278
+
279
+ /* §25 research grant picker. Warning-bordered like the permission modal
280
+ rather than primary-bordered like the thread picker: both are
281
+ authorization decisions, and looking like the neutral list-of-threads
282
+ dialog would undersell what confirming here does. */
283
+ #grant-dialog {
284
+ width: 76;
285
+ height: auto;
286
+ max-height: 22;
287
+ padding: 1 2;
288
+ border: thick $warning;
289
+ background: $surface;
290
+ }
291
+
292
+ #grant-title {
293
+ text-style: bold;
294
+ }
295
+
296
+ #grant-help {
297
+ padding-bottom: 1;
298
+ color: $text-muted;
299
+ }
300
+
301
+ /* 8, not 14 (batch 49). A dialog has 18 rows inside it on the 24-row
302
+ floor, and the title, the two-sentence help, the bar and this list
303
+ have to share them -- at 14 the confirm button was off the bottom
304
+ with twenty tools offered. */
305
+ #grant-list {
306
+ height: auto;
307
+ max-height: 8;
308
+ margin-bottom: 1;
309
+ }
310
+
311
+ #thread-dialog {
312
+ width: 70;
313
+ height: auto;
314
+ max-height: 24;
315
+ padding: 1 2;
316
+ border: thick $primary;
317
+ background: $surface;
318
+ }
319
+
320
+ #thread-title {
321
+ text-style: bold;
322
+ padding-bottom: 1;
323
+ }
324
+
325
+ #thread-list {
326
+ height: auto;
327
+ max-height: 18;
328
+ }
329
+
330
+ /* §23 slice 2's question modal. Borrows the grant dialog's proportions --
331
+ both are "read this, then choose" rather than "allow or deny" -- but
332
+ takes the primary border rather than the warning one: this authorises
333
+ nothing, it answers something. */
334
+ QuestionScreen {
335
+ align: center middle;
336
+ }
337
+
338
+ #question-dialog {
339
+ width: 66;
340
+ height: auto;
341
+ /* The body is the MODEL's question -- the one length the app does
342
+ not choose (#112). Without a max-height a long question pushed the
343
+ dialog to 45 rows on a 24-row terminal, title off the top and the
344
+ defer button off the bottom. */
345
+ max-height: 22;
346
+ padding: 1 2;
347
+ border: thick $primary;
348
+ background: $surface;
349
+ }
350
+
351
+ #question-title {
352
+ text-style: bold;
353
+ width: 100%;
354
+ }
355
+
356
+ #question-body-box {
357
+ height: auto;
358
+ max-height: 4;
359
+ padding: 1 0;
360
+ width: 100%;
361
+ }
362
+
363
+ #question-body {
364
+ height: auto;
365
+ width: 100%;
366
+ }
367
+
368
+ /* The single-select options. Bounded like the SelectionList the
369
+ multi-select branch uses, and for the same reason -- four options of
370
+ two lines each is 16 rows, and the dialog has 18. */
371
+ #question-options {
372
+ height: auto;
373
+ max-height: 6;
374
+ width: 100%;
375
+ margin-bottom: 1;
376
+ }
377
+
378
+ /* FIXED WIDTH, and it is what stops the truncation (batch 49). At
379
+ Button's default `width: auto` an option is as wide as its label
380
+ unwrapped -- measured at 119 columns inside a 60-column dialog, so a
381
+ long option was CUT at the dialog edge, and three options of
382
+ different lengths gave three different right edges. At `width: 100%`
383
+ the same label WRAPS to two centred lines and every option is the
384
+ same size. Nothing is truncated anywhere: ask_user refuses an option
385
+ too long to render rather than shortening it. */
386
+ #question-options Button {
387
+ width: 100%;
388
+ }
389
+
390
+ #question-help {
391
+ color: $text-muted;
392
+ padding-bottom: 1;
393
+ width: 100%;
394
+ }
395
+
396
+ #question-list {
397
+ height: auto;
398
+ max-height: 6;
399
+ margin-bottom: 1;
400
+ }
401
+
402
+ /* The sign-off's list is capped like the grant list it is modelled on:
403
+ its length is the subagent's gated tool set, and uncapped it pushed
404
+ the decision buttons off-screen (#112). Capped at 14 it still did --
405
+ #112 bounded the list and nothing bounded the SUM, which is the
406
+ defect batch 49 answers. */
407
+ #signoff-list {
408
+ height: auto;
409
+ max-height: 8;
410
+ margin-bottom: 1;
411
+ }
412
+
413
+ /* §20's review consent surface (#112). It had NO rules at all -- full
414
+ screen, top-left, unbordered -- and its body carries reason and
415
+ proposed straight from the reviewer model, so an uncapped body pushed
416
+ the four decision buttons below the fold. Warning-bordered like
417
+ permission/grant rather than primary like claims/question: this one
418
+ AUTHORISES AN EDIT to a finished research run. */
419
+ #review-dialog {
420
+ width: 76;
421
+ height: auto;
422
+ max-height: 22;
423
+ padding: 1 2;
424
+ border: thick $warning;
425
+ background: $surface;
426
+ }
427
+
428
+ #review-title {
429
+ text-style: bold;
430
+ }
431
+
432
+ #review-body-box {
433
+ height: auto;
434
+ max-height: 8;
435
+ }
436
+
437
+ #review-body {
438
+ height: auto;
439
+ }
440
+
441
+ /* §38's collapsed thinking line. `height: auto` and hidden until a span
442
+ starts, so it costs no rows when tui.show_thinking is on -- the same
443
+ arrangement the checklist below uses for its unfilled slots. */
444
+ #thinking-indicator {
445
+ height: auto;
446
+ padding: 0 1;
447
+ }
448
+
449
+ /* §23 slice 2's checklist. `height: auto` so an empty list costs no rows in
450
+ whichever slot tui.todo_position put it in -- the widget hides itself, and
451
+ this is what makes the unused slots free. */
452
+ #todo-panel {
453
+ height: auto;
454
+ max-height: 14;
455
+ overflow-y: auto;
456
+ padding: 0 1;
457
+ color: $text-muted;
458
+ }
@@ -0,0 +1,61 @@
1
+ """
2
+ tui/commands.py
3
+
4
+ ROADMAP_v2 §16 slash-command registry.
5
+
6
+ The registry is §16's; the commands registered into it are not all §16's.
7
+ D7 assigns `/skill <name>` to §19, and §18/§21 add their own -- each
8
+ registers here rather than editing a match statement in the app, which is
9
+ the same mechanism-vs-policy split tools/registry.py already uses for
10
+ tools.
11
+
12
+ A handler takes (app, argument_string) and returns None. It runs on the UI
13
+ thread, so anything slow belongs in a worker.
14
+ """
15
+
16
+ from dataclasses import dataclass
17
+ from typing import Callable, Optional
18
+
19
+
20
+ @dataclass
21
+ class SlashCommand:
22
+ name: str # without the leading slash
23
+ summary: str # one line, shown by /help
24
+ handler: Callable # (app, args: str) -> None
25
+ usage: Optional[str] = None # shown by /help when the shape is not obvious
26
+
27
+
28
+ class CommandRegistry:
29
+ def __init__(self) -> None:
30
+ self._commands: dict[str, SlashCommand] = {}
31
+
32
+ def register(self, command: SlashCommand) -> None:
33
+ self._commands[command.name] = command
34
+
35
+ def get(self, name: str) -> Optional[SlashCommand]:
36
+ return self._commands.get(name)
37
+
38
+ def names(self) -> list[str]:
39
+ return sorted(self._commands)
40
+
41
+ def all(self) -> list[SlashCommand]:
42
+ return [self._commands[n] for n in self.names()]
43
+
44
+ def dispatch(self, app, raw: str) -> bool:
45
+ """Run the command in `raw` (a line starting with '/').
46
+
47
+ Returns True if a command handled the line, False if the name is
48
+ unknown -- the caller decides what to do about it. Unknown names are
49
+ NOT sent to the model: a mistyped slash command should say so, not
50
+ silently become a chat turn that burns a request.
51
+ """
52
+ stripped = raw[1:].strip()
53
+ name, _, args = stripped.partition(" ")
54
+ command = self.get(name.lower())
55
+ if command is None:
56
+ return False
57
+ command.handler(app, args.strip())
58
+ return True
59
+
60
+
61
+ registry = CommandRegistry()