@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/tools/base.py CHANGED
@@ -1,6 +1,8 @@
1
+ from collections.abc import Callable, Iterable
1
2
  from dataclasses import dataclass
2
- from typing import Callable, Iterable, Optional
3
+ from typing import Optional
3
4
 
5
+ from pydantic import ValidationError
4
6
 
5
7
  # ROADMAP_v2 §25 (R13). How far approving a tool BY NAME goes -- the
6
8
  # question asked before any call exists, by the §18 subagent sign-off and
@@ -17,6 +19,26 @@ GRANT_NEVER = "never"
17
19
  GRANT_POLICIES = frozenset({GRANT_ANYWHERE, GRANT_SIGNOFF_ONLY, GRANT_NEVER})
18
20
 
19
21
 
22
+ # ROADMAP_v2 §47, extended by ROADMAP_v3 §49 (SS14) and again by §55
23
+ # (TR7). What a tool call's line in the transcript OPENS, as
24
+ # `registry.opens()` answers it.
25
+ #
26
+ # Named here beside the flags they are derived from, so the two consumers
27
+ # that carry the answer -- core/replay.py into a stored line, tui/ into a
28
+ # live one -- compare against a constant rather than against a literal
29
+ # each spelled in its own file.
30
+ #
31
+ # OPENS_CALL IS THE FALLBACK AND IS NOT DERIVED FROM A FLAG (§55, TR7).
32
+ # The other two are declared per tool because only some tools start a run
33
+ # or a session; EVERY call has itself, so there is nothing for a ToolSpec
34
+ # to declare and no tool that can decline. That is why `registry.opens()`
35
+ # no longer has an empty answer -- see its docstring for what replaced the
36
+ # falsy-tuple contract.
37
+ OPENS_THREAD = "thread"
38
+ OPENS_SESSION = "session"
39
+ OPENS_CALL = "call"
40
+
41
+
20
42
  # ROADMAP_v2 §31 (H1). What a call to this tool is allowed to COST, and
21
43
  # therefore which mechanism bounds it. Asked once, at registration, for
22
44
  # the same reason grant_policy is: the answer is a property of the tool,
@@ -47,6 +69,89 @@ BUDGET_HUMAN = "human"
47
69
  BUDGETS = frozenset({BUDGET_COMPUTE, BUDGET_IO, BUDGET_HUMAN})
48
70
 
49
71
 
72
+ # ===========================================================================
73
+ # WHAT A CALLABLE REGISTERED BELOW MAY RAISE -- stated ONCE, here, because it
74
+ # was stated six times elsewhere and all six copies were wrong (batch 146).
75
+ #
76
+ # NO PROVIDER VALIDATES TOOL INPUTS AGAINST THE SCHEMA. `params` is whatever
77
+ # the model emitted: a key may be missing, misspelled, or present with a
78
+ # value of the wrong type. `{"path": null}` is a well-formed JSON object, so
79
+ # the arguments layer passes it and `params.get("path", "")` returns None
80
+ # rather than the default -- the key IS there.
81
+ #
82
+ # A HANDLER'S exception is contained. tools/registry.py wraps the handler
83
+ # call "on purpose", under a comment naming the failure that bought it ("a
84
+ # raising tool used to take the whole run down with it"), and returns
85
+ # `{"error": "<tool> failed: ..."}`. So a bare KeyError in a `run()` has not
86
+ # ended a turn since that landed, and six comments in tools/builtin/ saying
87
+ # it "escapes the loop's ToolCallDenied handler and aborts the whole turn"
88
+ # were describing a tree that no longer existed. The practice they defend is
89
+ # still right, for a reason that survives the containment: an error dict the
90
+ # model can READ beats a generic wrapper it cannot act on, which is what the
91
+ # unknown-name branch in load_skill already does two lines from its comment.
92
+ #
93
+ # A GATE'S exception is NOT contained, and that is the half nobody wrote
94
+ # down. `approval_check` and `refusal_check` run ABOVE the handler boundary;
95
+ # core/loop.py calls `approval_needed` and `refusal_reason` with no `try`,
96
+ # and the `try` around `dispatch()` catches only ToolCallDenied. Sequentially
97
+ # the exception leaves `_run` and ends the turn; in a research pass it
98
+ # propagates into the pipeline handler that records a durable
99
+ # `status='failed'`; in a PARALLEL batch the identical input becomes one
100
+ # call's error result. So the same malformed argument kills a turn alone and
101
+ # is recoverable beside siblings.
102
+ #
103
+ # THEREFORE: a gate must be TOTAL over any JSON object. shell.py has said so
104
+ # at its own gate for a long time -- "Total, like everything else the gate
105
+ # calls: `params['command']` is whatever the model emitted" -- and batch 146
106
+ # found file_ops' two gates were the one exception in the tree, reaching
107
+ # `os.path.join(WORKSPACE_ROOT, None)` before any prompt and any handler.
108
+ #
109
+ # AND A REFUSAL MUST NOT ECHO A VALUE. `invalid_params` below renders the
110
+ # field and the problem and never the value, which is the shape
111
+ # shell_sessions chose first.
112
+ #
113
+ # THE REASON CHANGED IN BATCH 156 AND THE RULE DID NOT. As first written
114
+ # this said the refusal path "is the one result path that does NOT pass
115
+ # through the output redactor", which was true and is the hole batch 156
116
+ # closed in tools/registry.py -- measured, a `ghp_` token the model put in
117
+ # an `agent_name` came back whole. So the sentence that made this rule
118
+ # load-bearing is gone, and the rule stays, because the redactor it now
119
+ # passes through is a PATTERN GUESS rather than a decision procedure:
120
+ # register item 52 measured sixteen of twenty-two credential shapes
121
+ # surviving it, and batch 156 re-confirmed five of those (`github_pat_`,
122
+ # `gho_`, `sk-proj-`, `npm_`, a `Bearer` header) against a `ghp_` control
123
+ # it does catch. A refusal that does not echo cannot leak what no pattern
124
+ # knows; one that echoes is covered only for the shapes somebody thought
125
+ # of. That is defence in depth rather than a belt the registry made
126
+ # redundant -- and it is cheaper here than anywhere else, because the field
127
+ # name is what makes a refusal actionable and the value never was.
128
+ # ===========================================================================
129
+
130
+ def invalid_params(tool_name: str, model, params) -> Optional[str]:
131
+ """Why `params` would not validate against `model`, in one line, or None.
132
+
133
+ For a `refusal_check`, which is what makes a mistyped argument a refusal
134
+ the model can correct instead of an exception above the containment. The
135
+ handler's own `model(**params)` stays where it is: this is the
136
+ pre-approval answer, and base.py's rule for the segment guards applies
137
+ here too -- the check above is not the enforcement.
138
+
139
+ `err['loc']` and `err['msg']` only. `str(e)` would carry `input_value`,
140
+ and the block above says why that matters: this string becomes the tool
141
+ result without passing the redactor.
142
+ """
143
+ if not isinstance(params, dict):
144
+ return f"Invalid arguments for {tool_name}: expected an object."
145
+ try:
146
+ model(**params)
147
+ except ValidationError as e:
148
+ problems = "; ".join(
149
+ f"{'.'.join(str(part) for part in err['loc']) or 'arguments'}: "
150
+ f"{err['msg']}" for err in e.errors())
151
+ return f"Invalid arguments for {tool_name}: {problems}."
152
+ return None
153
+
154
+
50
155
  @dataclass
51
156
  class ToolSpec:
52
157
  name: str # Tool name
@@ -63,6 +168,10 @@ class ToolSpec:
63
168
  # invisible to config/context-level approval settings entirely, which
64
169
  # would have silently voided agent approval_overrides for read/write/
65
170
  # edit/shell -- the four tools where per-agent tightening matters most.
171
+ #
172
+ # TOTAL over any JSON object -- see "WHAT A CALLABLE REGISTERED BELOW MAY
173
+ # RAISE" at the top of this file. A predicate that cannot answer should
174
+ # answer True: ASKING is the fail-closed direction for this one.
66
175
  approval_check: Optional[Callable[[str, dict], bool]] = None
67
176
  # Optional "is this tool meaningful right now?" predicate, consulted by
68
177
  # registry.schemas() when deciding what to advertise to the model.
@@ -115,6 +224,11 @@ class ToolSpec:
115
224
  #
116
225
  # A property of the tool rather than a name hard-coded into the
117
226
  # loop, for exactly the reason grant_scope and request_kind are.
227
+ #
228
+ # TOTAL over any JSON object, like approval_check above it -- see "WHAT A
229
+ # CALLABLE REGISTERED BELOW MAY RAISE" at the top of this file, which is
230
+ # the one copy of why, and `invalid_params` beside it, which is the one
231
+ # copy of how.
118
232
  refusal_check: Optional[Callable[[dict, object], Optional[str]]] = None
119
233
  # Optional extra text shown in the approval prompt, above the params.
120
234
  # Signature: (params, context) -> str. Lets a tool explain what
@@ -143,6 +257,40 @@ class ToolSpec:
143
257
  # assert_grant_policy_declared() below makes omission fatal at import,
144
258
  # the same trade D24 made for permissions.
145
259
  grant_policy: Optional[str] = None
260
+ # ROADMAP_v2 §47. Whether a call to this tool creates a conversation
261
+ # thread of its own, which is what makes the line that called it
262
+ # something a reader can OPEN.
263
+ #
264
+ # DECLARED HERE rather than by naming `spawn_subagent` at each reader,
265
+ # for grant_policy's reason (R13): two consumers ask this -- core/replay.py
266
+ # and the TUI -- and a string in two places is how they come to
267
+ # disagree about which lines are openable. Defaulted to False, unlike
268
+ # grant_policy, because the safe answer here is "this line opens
269
+ # nothing" and a tool that forgot to say so simply is not clickable.
270
+ opens_thread: bool = False
271
+ # ROADMAP_v3 §49 (SS14). Whether a call to this tool starts a background
272
+ # SESSION, which is the other thing a tool-call line can open.
273
+ #
274
+ # A SECOND FLAG rather than a widened `opens_thread`, because the two
275
+ # answer different questions at press time: a thread is replayed from
276
+ # the archive and a session is read from the manager or rebuilt from
277
+ # the wake rows it wrote. `registry.opens()` is what consumers ask --
278
+ # one question, one answer, so no reader has to know that two flags
279
+ # exist. Defaulted False for `opens_thread`'s reason.
280
+ opens_session: bool = False
281
+ # ROADMAP_v2 §47 slice 8 (NA9). Whether several calls to this tool in
282
+ # ONE model response may run at the same time.
283
+ #
284
+ # DECLARED HERE for `opens_thread`'s reason, one question over: the
285
+ # loop partitions a response by asking, so no tool name appears in
286
+ # core/loop.py -- the same argument grant_scope and request_kind
287
+ # already make. Defaulted to False because the safe answer is "run
288
+ # this one at a time": a tool that has not been examined for thread
289
+ # safety must not be made concurrent by having forgotten to say so.
290
+ #
291
+ # `spawn_subagent` is the only tool that sets it, and NA9's partition
292
+ # keeps every other call strictly sequential in its original position.
293
+ parallel: bool = False
146
294
  # ROADMAP_v2 §31 (H1). One of BUDGET_COMPUTE / BUDGET_IO /
147
295
  # BUDGET_HUMAN, above.
148
296
  #
@@ -208,6 +356,18 @@ class ToolSpec:
208
356
  # NO IMPORT-TIME GUARD, for rationale_param's reason: None is the
209
357
  # correct answer for every tool but one.
210
358
  headline_param: Optional[str] = None
359
+ # ROADMAP_v3 §81 (IM6). Whether this tool's result carries an IMAGE --
360
+ # which reaches the model only from a provider marked `accepts_images`,
361
+ # and never in a research pass. registry.schemas() drops such a tool
362
+ # unless its caller says images can be delivered in this run.
363
+ #
364
+ # NOT an available_check: that predicate takes no arguments, and this
365
+ # answer depends on the RUN -- its provider and what its thread is --
366
+ # which only the loop holds. DECLARED HERE for `opens_thread`'s reason:
367
+ # the loop asks the registry, so no tool name appears in core/loop.py.
368
+ # Defaulted False, because a tool that returns text is offered wherever
369
+ # it always was.
370
+ returns_images: bool = False
211
371
 
212
372
 
213
373
  def assert_grant_policy_declared(tools: Iterable[str], specs=None) -> None: