@yahyahammad/venastine 0.3.8 → 0.3.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
package/core/events.py CHANGED
@@ -1,123 +1,123 @@
1
- """
2
- core/events.py
3
-
4
- LoopEvent is the single event type yielded by RunAgentLoop._run() as it
5
- progresses through the call-dispatch-repeat cycle. Exactly one field is
6
- meaningfully populated per event, matching what happened at that point
7
- in the loop.
8
-
9
- Consumers (CLI, TUI, research pipeline) iterate the generator and react
10
- to whichever field is set. run_to_completion() in core/loop.py drains
11
- the generator for callers that only need the final ModelResponse.
12
-
13
- Error handling: there is deliberately no error variant. Exceptions
14
- raised mid-loop propagate naturally out of the generator, unchanged
15
- from the pre-streaming behavior. orchestrator.py's failure-path
16
- persistence (except Exception: update_pipeline_run(..., status="failed");
17
- raise) depends on a real exception propagating -- converting failures
18
- into data-shaped events would require every consumer to know to unpack
19
- and re-raise. Consumers that want graceful error display (the TUI) wrap
20
- their own consumption loop in try/except.
21
-
22
- `retract` is NOT an error variant, and batch 113 added it without
23
- reopening that decision. The rule above is about where a failure is
24
- HANDLED: a failure must stay an exception so that the persistence which
25
- depends on one still fires. A retraction says nothing about whether the
26
- call failed for good -- it says the rows drawn so far are being replaced,
27
- and the exception still propagates, unchanged, when the retries run out.
28
- The two coexist because they answer different questions, and a consumer
29
- that ignores `retract` entirely is still correct about failures.
30
- """
31
-
32
- from dataclasses import dataclass
33
- from typing import Any, Optional
34
-
35
-
36
- @dataclass
37
- class LoopEvent:
38
- """One event yielded by RunAgentLoop._run()."""
39
- token_delta: Optional[str] = None
40
- # ROADMAP_v2 §38 (O4) -- the EIGHTH field, and P1 re-made rather than
41
- # widened by accretion. P1 rejected putting §22's and §23's kinds here
42
- # because those describe a ten-pass RUN and live for the run; a
43
- # thinking delta describes one model call's progress and lives for a
44
- # turn, which is token_delta's family exactly. So this is the case P1's
45
- # rule was never about, and the ninth field still has to argue for
46
- # itself in tests/test_pipeline_events.py.
47
- #
48
- # Reasoning text, streamed as it arrives, for the shells that want to
49
- # show it. Display-only: it is not persisted, not part of
50
- # ModelResponse.text, and never sent back on the wire. Empty on
51
- # providers that return no reasoning (OPENAI, GOOGLE) -- see
52
- # StreamToken's note.
53
- thinking_delta: Optional[str] = None
54
- tool_call_start: Optional[dict] = None # {"id", "name", "input"}
55
- tool_result: Optional[dict] = None # {"id", "result"}
56
- permission_request: Optional[dict] = None # {"tool_name", "params"}
57
- # ROADMAP_v2 §21: {"kind", "text"} -- a compaction that happened, an
58
- # early warning that one is coming, or a compaction that could not
59
- # help. §21's "no silent compaction, ever": both automatic and manual
60
- # compaction show a marker inline.
61
- #
62
- # ALSO carried on the ModelResponse, because run_to_completion()
63
- # discards every non-final event -- so a notice delivered only here
64
- # would be invisible to the pipeline, which drains the generator
65
- # rather than watching it. That is the same defect §20 and §25 each hit
66
- # once; the event is for live display, the response field is for
67
- # everyone else.
68
- #
69
- # The CLI drained too until ROADMAP_v3 §86 (A81). It now hands
70
- # run_to_completion() an observer, prints this event when it arrives,
71
- # and prints from the response only a notice that never arrived. That
72
- # is also how a TOOL's notice (§23 J10) reaches it: those ride only
73
- # this event, never the response.
74
- notice: Optional[dict] = None
75
- # Batch 113 (TECHNICAL_DEBT 25). THE NINTH FIELD, and it argues for
76
- # itself where test_pipeline_events.py says it must. This is not a
77
- # notice ABOUT the run -- it is an instruction to a drawing surface:
78
- # take back everything you have drawn since the last flush, because
79
- # the model call that produced it failed and is being tried again.
80
- # thinking_delta's family exactly, and P1's rule was never about this
81
- # case either: it describes one model call's progress and lives for a
82
- # turn.
83
- #
84
- # {"text", "attempt", "attempts"} -- the sentence to show, and the
85
- # numbers behind it for a consumer that would rather phrase its own.
86
- #
87
- # DISPLAY-ONLY, and unlike `notice` it is deliberately NOT mirrored
88
- # onto ModelResponse. A consumer that drains has drawn nothing and so
89
- # has nothing to retract; handing it a retraction in the response
90
- # would be asking it to undo something that never happened. A
91
- # consumer with no screen correctly ignores this field, which is why
92
- # the research pipeline translates it into nothing at all.
93
- #
94
- # The CLI (ROADMAP_v3 §86, A81) has a screen and still draws nothing
95
- # a retraction could reach: it prints a step only once the step has
96
- # finished, which is after the last moment one can arrive. It honours
97
- # this field by dropping what it was holding.
98
- retract: Optional[dict] = None
99
- final_response: Optional[Any] = None # ModelResponse on terminal event
100
- # "complete" | "max_steps_reached" | "token_budget_exceeded" |
101
- # "cancelled"
102
- #
103
- # ROADMAP_v3 §61 (CN3) added the fourth, and added NO field: this
104
- # comment is the only place the set is written down, so a value
105
- # missing from here is a reader's silent gap -- which is why
106
- # tests/test_cancel.py asserts all four appear in this file.
107
- #
108
- # "cancelled" is NEVER "failed". A failed run is recorded on the
109
- # thread by mark_turn_failed and reads as something broken; a
110
- # cancelled one is a person changing their mind. The loop RETURNS on
111
- # it rather than raising, for the reason the module docstring above
112
- # gives about exceptions -- an exception here would reach _run's
113
- # frame and stamp a failure on a turn nobody saw fail, which is the
114
- # same argument that frame already makes for GeneratorExit.
115
- #
116
- # A CONSUMER THAT TREATS EVERY NON-"complete" VALUE AS TRUNCATION IS
117
- # NOW WRONG, and there is one: core/reasoning/orchestrator.py's
118
- # _check_truncation continues the pipeline on a truncated pass with
119
- # text. No research pass can return "cancelled" today (§61 CN12
120
- # defers the pipeline deliberately), so that reader is correct as it
121
- # stands -- and it has to be taught the difference before the
122
- # deferral is lifted.
123
- stop_reason: Optional[str] = None
1
+ """
2
+ core/events.py
3
+
4
+ LoopEvent is the single event type yielded by RunAgentLoop._run() as it
5
+ progresses through the call-dispatch-repeat cycle. Exactly one field is
6
+ meaningfully populated per event, matching what happened at that point
7
+ in the loop.
8
+
9
+ Consumers (CLI, TUI, research pipeline) iterate the generator and react
10
+ to whichever field is set. run_to_completion() in core/loop.py drains
11
+ the generator for callers that only need the final ModelResponse.
12
+
13
+ Error handling: there is deliberately no error variant. Exceptions
14
+ raised mid-loop propagate naturally out of the generator, unchanged
15
+ from the pre-streaming behavior. orchestrator.py's failure-path
16
+ persistence (except Exception: update_pipeline_run(..., status="failed");
17
+ raise) depends on a real exception propagating -- converting failures
18
+ into data-shaped events would require every consumer to know to unpack
19
+ and re-raise. Consumers that want graceful error display (the TUI) wrap
20
+ their own consumption loop in try/except.
21
+
22
+ `retract` is NOT an error variant, and batch 113 added it without
23
+ reopening that decision. The rule above is about where a failure is
24
+ HANDLED: a failure must stay an exception so that the persistence which
25
+ depends on one still fires. A retraction says nothing about whether the
26
+ call failed for good -- it says the rows drawn so far are being replaced,
27
+ and the exception still propagates, unchanged, when the retries run out.
28
+ The two coexist because they answer different questions, and a consumer
29
+ that ignores `retract` entirely is still correct about failures.
30
+ """
31
+
32
+ from dataclasses import dataclass
33
+ from typing import Any, Optional
34
+
35
+
36
+ @dataclass
37
+ class LoopEvent:
38
+ """One event yielded by RunAgentLoop._run()."""
39
+ token_delta: Optional[str] = None
40
+ # ROADMAP_v2 §38 (O4) -- the EIGHTH field, and P1 re-made rather than
41
+ # widened by accretion. P1 rejected putting §22's and §23's kinds here
42
+ # because those describe a ten-pass RUN and live for the run; a
43
+ # thinking delta describes one model call's progress and lives for a
44
+ # turn, which is token_delta's family exactly. So this is the case P1's
45
+ # rule was never about, and the ninth field still has to argue for
46
+ # itself in tests/test_pipeline_events.py.
47
+ #
48
+ # Reasoning text, streamed as it arrives, for the shells that want to
49
+ # show it. Display-only: it is not persisted, not part of
50
+ # ModelResponse.text, and never sent back on the wire. Empty on
51
+ # providers that return no reasoning (OPENAI, GOOGLE) -- see
52
+ # StreamToken's note.
53
+ thinking_delta: Optional[str] = None
54
+ tool_call_start: Optional[dict] = None # {"id", "name", "input"}
55
+ tool_result: Optional[dict] = None # {"id", "result"}
56
+ permission_request: Optional[dict] = None # {"tool_name", "params"}
57
+ # ROADMAP_v2 §21: {"kind", "text"} -- a compaction that happened, an
58
+ # early warning that one is coming, or a compaction that could not
59
+ # help. §21's "no silent compaction, ever": both automatic and manual
60
+ # compaction show a marker inline.
61
+ #
62
+ # ALSO carried on the ModelResponse, because run_to_completion()
63
+ # discards every non-final event -- so a notice delivered only here
64
+ # would be invisible to the pipeline, which drains the generator
65
+ # rather than watching it. That is the same defect §20 and §25 each hit
66
+ # once; the event is for live display, the response field is for
67
+ # everyone else.
68
+ #
69
+ # The CLI drained too until ROADMAP_v3 §86 (A81). It now hands
70
+ # run_to_completion() an observer, prints this event when it arrives,
71
+ # and prints from the response only a notice that never arrived. That
72
+ # is also how a TOOL's notice (§23 J10) reaches it: those ride only
73
+ # this event, never the response.
74
+ notice: Optional[dict] = None
75
+ # Batch 113 (TECHNICAL_DEBT 25). THE NINTH FIELD, and it argues for
76
+ # itself where test_pipeline_events.py says it must. This is not a
77
+ # notice ABOUT the run -- it is an instruction to a drawing surface:
78
+ # take back everything you have drawn since the last flush, because
79
+ # the model call that produced it failed and is being tried again.
80
+ # thinking_delta's family exactly, and P1's rule was never about this
81
+ # case either: it describes one model call's progress and lives for a
82
+ # turn.
83
+ #
84
+ # {"text", "attempt", "attempts"} -- the sentence to show, and the
85
+ # numbers behind it for a consumer that would rather phrase its own.
86
+ #
87
+ # DISPLAY-ONLY, and unlike `notice` it is deliberately NOT mirrored
88
+ # onto ModelResponse. A consumer that drains has drawn nothing and so
89
+ # has nothing to retract; handing it a retraction in the response
90
+ # would be asking it to undo something that never happened. A
91
+ # consumer with no screen correctly ignores this field, which is why
92
+ # the research pipeline translates it into nothing at all.
93
+ #
94
+ # The CLI (ROADMAP_v3 §86, A81) has a screen and still draws nothing
95
+ # a retraction could reach: it prints a step only once the step has
96
+ # finished, which is after the last moment one can arrive. It honours
97
+ # this field by dropping what it was holding.
98
+ retract: Optional[dict] = None
99
+ final_response: Optional[Any] = None # ModelResponse on terminal event
100
+ # "complete" | "max_steps_reached" | "token_budget_exceeded" |
101
+ # "cancelled"
102
+ #
103
+ # ROADMAP_v3 §61 (CN3) added the fourth, and added NO field: this
104
+ # comment is the only place the set is written down, so a value
105
+ # missing from here is a reader's silent gap -- which is why
106
+ # tests/test_cancel.py asserts all four appear in this file.
107
+ #
108
+ # "cancelled" is NEVER "failed". A failed run is recorded on the
109
+ # thread by mark_turn_failed and reads as something broken; a
110
+ # cancelled one is a person changing their mind. The loop RETURNS on
111
+ # it rather than raising, for the reason the module docstring above
112
+ # gives about exceptions -- an exception here would reach _run's
113
+ # frame and stamp a failure on a turn nobody saw fail, which is the
114
+ # same argument that frame already makes for GeneratorExit.
115
+ #
116
+ # A CONSUMER THAT TREATS EVERY NON-"complete" VALUE AS TRUNCATION IS
117
+ # NOW WRONG, and there is one: core/reasoning/orchestrator.py's
118
+ # _check_truncation continues the pipeline on a truncated pass with
119
+ # text. No research pass can return "cancelled" today (§61 CN12
120
+ # defers the pipeline deliberately), so that reader is correct as it
121
+ # stands -- and it has to be taught the difference before the
122
+ # deferral is lifted.
123
+ stop_reason: Optional[str] = None