@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/tools/context.py CHANGED
@@ -1,159 +1,159 @@
1
- """
2
- tools/context.py
3
-
4
- ROADMAP_v2 §15. `ToolContext` is the per-run bundle of tool restrictions
5
- contributed by whatever is currently active above the global policy --
6
- an agent (§18), the skills it has activated (§19), or a subagent's
7
- inherited scope. It is data only: the "stricter wins" composition rule
8
- (D14) lives in security/permissions.py, not here.
9
-
10
- Deliberately a leaf module with no project imports. security/permissions.py
11
- type-hints against it under TYPE_CHECKING only, so the existing
12
- `tools -> security` dependency direction is never inverted at runtime.
13
-
14
- A `None` context means "no layer above global policy has an opinion",
15
- which is the state every current production caller is in until §18 lands.
16
- """
17
-
18
- from dataclasses import dataclass, field
19
- from typing import Optional
20
-
21
-
22
- @dataclass
23
- class ToolContext:
24
- """One active restriction layer.
25
-
26
- allowed_tools: None means this layer expresses NO opinion (not "no
27
- tools"). A set restricts to exactly those names. Composition is
28
- intersection -- a layer can only ever narrow what is available,
29
- never widen it past the global policy (D14).
30
- approval_overrides: name -> bool. Only `True` is meaningful: approval
31
- is OR'd across layers, so an entry can add an approval
32
- requirement but can never remove one. See requires_approval().
33
- subagent_depth: incremented by §18's spawn_subagent each time it
34
- builds a child context; the nesting limit is checked against it.
35
- spawn_targets: None means this layer expresses NO opinion about WHICH
36
- agents may be spawned -- not "none of them", exactly as for
37
- allowed_tools above. A set restricts spawn_subagent to those
38
- agent names, and composes the same way: intersection, so a layer
39
- can only ever narrow the roster it inherited.
40
-
41
- SEPARATE FROM allowed_tools because they answer different
42
- questions. `allowed_tools` decides whether this run may spawn AT
43
- ALL; this decides who it may spawn, and the two failure modes are
44
- not the same one. C6 caps a child's tools by intersecting them
45
- with the parent's, which turns "a parent that should not delegate
46
- this work" into "a child that quietly cannot do it" -- `plan`
47
- spawning `build` returned a build with no `write` or `edit` and
48
- no way for either side to tell. An agent that must not delegate
49
- a kind of work should be refused, not narrowed.
50
- """
51
-
52
- allowed_tools: Optional[set[str]] = None
53
- approval_overrides: dict[str, bool] = field(default_factory=dict)
54
- subagent_depth: int = 0
55
- spawn_targets: Optional[set[str]] = None
56
-
57
-
58
- @dataclass
59
- class RunInfo:
60
- """Identity of the enclosing run, for context-aware tool handlers that
61
- spawn further runs (§18's spawn_subagent inherits model / provider /
62
- effort when the agent definition names none of its own).
63
-
64
- Carries no policy -- deliberately separate from ToolContext so a
65
- handler's signature cannot confuse inheritance with restriction.
66
- """
67
-
68
- model: str
69
- provider_name: str
70
- effort: Optional[str] = None
71
- # Tools already signed off for the rest of THIS run (§18 subagent
72
- # sign-off, S1). A RunInfo is built once per _run() call and _run() is
73
- # called once per turn, so run-scope is turn-scope -- which is the
74
- # granularity the sign-off was specified at: approving a spawn covers
75
- # every subagent in that turn, including nested ones, and nothing
76
- # beyond it.
77
- #
78
- # A GRANT, not a policy override. It records that the user answered
79
- # the approval question early, exactly as an approval_callback
80
- # returning True does; it is deliberately not an approval_overrides
81
- # entry, because those OR and can therefore only ever tighten (D14).
82
- granted_tools: set = field(default_factory=set)
83
- # §25: the ceiling on how many granted calls may proceed without being
84
- # asked about. A core.approval.GrantBudget, or None for no ceiling.
85
- #
86
- # Typed as object so this module stays a leaf with no project imports
87
- # (see the module docstring) -- the same reason ToolContext is
88
- # type-hinted from security/permissions.py under TYPE_CHECKING only.
89
- # One budget instance is SHARED by every pass of a pipeline run; a
90
- # per-pass budget would multiply the ceiling by the pass count while
91
- # reading as if it enforced one.
92
- grant_budget: Optional[object] = None
93
- # ROADMAP_v2 §23 (AC1b). Sign-off answers already given in this run,
94
- # keyed by (tool name, SUBJECT). A subject is whatever the question was
95
- # about -- for spawn_subagent, the agent's name -- and is None for every
96
- # tool whose approval is a plain yes/no.
97
- #
98
- # Separate from granted_tools because the two carry different things: a
99
- # granted TOOL is a name approved with no further detail, while a
100
- # sign-off carries the SUBSET the child may use. Merging them would
101
- # force a set to hold both a name and a name-plus-subset.
102
- signoffs: dict = field(default_factory=dict)
103
- # ROADMAP_v3 §81 (IM6). Whether an image in a tool result can reach the
104
- # model in this run: the provider is marked `accepts_images` and the
105
- # thread is not a research pass. Computed ONCE, by the loop, and read
106
- # twice -- by the schema list, to leave `view_image` out, and by the
107
- # handler, to refuse a call made anyway -- so the two cannot disagree.
108
- # False by default: a RunInfo built anywhere else delivers no images.
109
- images: bool = False
110
-
111
- def remember_signoff(self, tool_name: str, subject, subset) -> None:
112
- """Record an answer so the rest of this run need not re-ask.
113
-
114
- A subset of None means the answer carried no detail -- a plain
115
- approval -- and lands in granted_tools exactly as it did before
116
- §23. Anything else is keyed by subject, because the answer was
117
- about that subject and means nothing for another one.
118
- """
119
- if subset is None:
120
- self.granted_tools.add(tool_name)
121
- else:
122
- self.signoffs[(tool_name, subject)] = set(subset)
123
-
124
- def recall_signoff(self, tool_name: str, subject) -> tuple:
125
- """(remembered, subset) for a call this run may already have
126
- answered.
127
-
128
- The subject-keyed memo is checked FIRST. A tool can appear in both
129
- (a pipeline grant names it, and a sign-off answered about one
130
- subject), and the specific answer is the one the user actually
131
- gave about this subject.
132
-
133
- R14: a grant BY NAME may not answer a question that carries a
134
- SUBJECT. J8 rebuilt the memo around (tool, subject) because
135
- approving a spawn of agent `a` had silently covered a later spawn
136
- of `b`; the grant branch below kept answering both, because it
137
- never looked at the subject at all:
138
-
139
- granted_tools={'spawn_subagent'}
140
- recall_signoff('spawn_subagent', 'agent-a') -> (True, None)
141
- recall_signoff('spawn_subagent', 'agent-b') -> (True, None)
142
- recall_signoff('spawn_subagent', <anything>) -> (True, None)
143
-
144
- -- J8's pre-fix behaviour, reached through the grant rather than
145
- the memo. A name-level answer is about the TOOL; a subject-carrying
146
- question is about one agent, and the two are not the same consent.
147
-
148
- Belt and braces after R13 made spawn_subagent GRANT_NEVER, since
149
- that is the only tool supplying a subject today: this holds for a
150
- hand-built or stale RunInfo, and for any later tool that carries
151
- one. `subject is None` for every other tool, so nothing else
152
- changes behaviour.
153
- """
154
- key = (tool_name, subject)
155
- if key in self.signoffs:
156
- return True, self.signoffs[key]
157
- if subject is None and tool_name in self.granted_tools:
158
- return True, None
159
- return False, None
1
+ """
2
+ tools/context.py
3
+
4
+ ROADMAP_v2 §15. `ToolContext` is the per-run bundle of tool restrictions
5
+ contributed by whatever is currently active above the global policy --
6
+ an agent (§18), the skills it has activated (§19), or a subagent's
7
+ inherited scope. It is data only: the "stricter wins" composition rule
8
+ (D14) lives in security/permissions.py, not here.
9
+
10
+ Deliberately a leaf module with no project imports. security/permissions.py
11
+ type-hints against it under TYPE_CHECKING only, so the existing
12
+ `tools -> security` dependency direction is never inverted at runtime.
13
+
14
+ A `None` context means "no layer above global policy has an opinion",
15
+ which is the state every current production caller is in until §18 lands.
16
+ """
17
+
18
+ from dataclasses import dataclass, field
19
+ from typing import Optional
20
+
21
+
22
+ @dataclass
23
+ class ToolContext:
24
+ """One active restriction layer.
25
+
26
+ allowed_tools: None means this layer expresses NO opinion (not "no
27
+ tools"). A set restricts to exactly those names. Composition is
28
+ intersection -- a layer can only ever narrow what is available,
29
+ never widen it past the global policy (D14).
30
+ approval_overrides: name -> bool. Only `True` is meaningful: approval
31
+ is OR'd across layers, so an entry can add an approval
32
+ requirement but can never remove one. See requires_approval().
33
+ subagent_depth: incremented by §18's spawn_subagent each time it
34
+ builds a child context; the nesting limit is checked against it.
35
+ spawn_targets: None means this layer expresses NO opinion about WHICH
36
+ agents may be spawned -- not "none of them", exactly as for
37
+ allowed_tools above. A set restricts spawn_subagent to those
38
+ agent names, and composes the same way: intersection, so a layer
39
+ can only ever narrow the roster it inherited.
40
+
41
+ SEPARATE FROM allowed_tools because they answer different
42
+ questions. `allowed_tools` decides whether this run may spawn AT
43
+ ALL; this decides who it may spawn, and the two failure modes are
44
+ not the same one. C6 caps a child's tools by intersecting them
45
+ with the parent's, which turns "a parent that should not delegate
46
+ this work" into "a child that quietly cannot do it" -- `plan`
47
+ spawning `build` returned a build with no `write` or `edit` and
48
+ no way for either side to tell. An agent that must not delegate
49
+ a kind of work should be refused, not narrowed.
50
+ """
51
+
52
+ allowed_tools: Optional[set[str]] = None
53
+ approval_overrides: dict[str, bool] = field(default_factory=dict)
54
+ subagent_depth: int = 0
55
+ spawn_targets: Optional[set[str]] = None
56
+
57
+
58
+ @dataclass
59
+ class RunInfo:
60
+ """Identity of the enclosing run, for context-aware tool handlers that
61
+ spawn further runs (§18's spawn_subagent inherits model / provider /
62
+ effort when the agent definition names none of its own).
63
+
64
+ Carries no policy -- deliberately separate from ToolContext so a
65
+ handler's signature cannot confuse inheritance with restriction.
66
+ """
67
+
68
+ model: str
69
+ provider_name: str
70
+ effort: Optional[str] = None
71
+ # Tools already signed off for the rest of THIS run (§18 subagent
72
+ # sign-off, S1). A RunInfo is built once per _run() call and _run() is
73
+ # called once per turn, so run-scope is turn-scope -- which is the
74
+ # granularity the sign-off was specified at: approving a spawn covers
75
+ # every subagent in that turn, including nested ones, and nothing
76
+ # beyond it.
77
+ #
78
+ # A GRANT, not a policy override. It records that the user answered
79
+ # the approval question early, exactly as an approval_callback
80
+ # returning True does; it is deliberately not an approval_overrides
81
+ # entry, because those OR and can therefore only ever tighten (D14).
82
+ granted_tools: set = field(default_factory=set)
83
+ # §25: the ceiling on how many granted calls may proceed without being
84
+ # asked about. A core.approval.GrantBudget, or None for no ceiling.
85
+ #
86
+ # Typed as object so this module stays a leaf with no project imports
87
+ # (see the module docstring) -- the same reason ToolContext is
88
+ # type-hinted from security/permissions.py under TYPE_CHECKING only.
89
+ # One budget instance is SHARED by every pass of a pipeline run; a
90
+ # per-pass budget would multiply the ceiling by the pass count while
91
+ # reading as if it enforced one.
92
+ grant_budget: Optional[object] = None
93
+ # ROADMAP_v2 §23 (AC1b). Sign-off answers already given in this run,
94
+ # keyed by (tool name, SUBJECT). A subject is whatever the question was
95
+ # about -- for spawn_subagent, the agent's name -- and is None for every
96
+ # tool whose approval is a plain yes/no.
97
+ #
98
+ # Separate from granted_tools because the two carry different things: a
99
+ # granted TOOL is a name approved with no further detail, while a
100
+ # sign-off carries the SUBSET the child may use. Merging them would
101
+ # force a set to hold both a name and a name-plus-subset.
102
+ signoffs: dict = field(default_factory=dict)
103
+ # ROADMAP_v3 §81 (IM6). Whether an image in a tool result can reach the
104
+ # model in this run: the provider is marked `accepts_images` and the
105
+ # thread is not a research pass. Computed ONCE, by the loop, and read
106
+ # twice -- by the schema list, to leave `view_image` out, and by the
107
+ # handler, to refuse a call made anyway -- so the two cannot disagree.
108
+ # False by default: a RunInfo built anywhere else delivers no images.
109
+ images: bool = False
110
+
111
+ def remember_signoff(self, tool_name: str, subject, subset) -> None:
112
+ """Record an answer so the rest of this run need not re-ask.
113
+
114
+ A subset of None means the answer carried no detail -- a plain
115
+ approval -- and lands in granted_tools exactly as it did before
116
+ §23. Anything else is keyed by subject, because the answer was
117
+ about that subject and means nothing for another one.
118
+ """
119
+ if subset is None:
120
+ self.granted_tools.add(tool_name)
121
+ else:
122
+ self.signoffs[(tool_name, subject)] = set(subset)
123
+
124
+ def recall_signoff(self, tool_name: str, subject) -> tuple:
125
+ """(remembered, subset) for a call this run may already have
126
+ answered.
127
+
128
+ The subject-keyed memo is checked FIRST. A tool can appear in both
129
+ (a pipeline grant names it, and a sign-off answered about one
130
+ subject), and the specific answer is the one the user actually
131
+ gave about this subject.
132
+
133
+ R14: a grant BY NAME may not answer a question that carries a
134
+ SUBJECT. J8 rebuilt the memo around (tool, subject) because
135
+ approving a spawn of agent `a` had silently covered a later spawn
136
+ of `b`; the grant branch below kept answering both, because it
137
+ never looked at the subject at all:
138
+
139
+ granted_tools={'spawn_subagent'}
140
+ recall_signoff('spawn_subagent', 'agent-a') -> (True, None)
141
+ recall_signoff('spawn_subagent', 'agent-b') -> (True, None)
142
+ recall_signoff('spawn_subagent', <anything>) -> (True, None)
143
+
144
+ -- J8's pre-fix behaviour, reached through the grant rather than
145
+ the memo. A name-level answer is about the TOOL; a subject-carrying
146
+ question is about one agent, and the two are not the same consent.
147
+
148
+ Belt and braces after R13 made spawn_subagent GRANT_NEVER, since
149
+ that is the only tool supplying a subject today: this holds for a
150
+ hand-built or stale RunInfo, and for any later tool that carries
151
+ one. `subject is None` for every other tool, so nothing else
152
+ changes behaviour.
153
+ """
154
+ key = (tool_name, subject)
155
+ if key in self.signoffs:
156
+ return True, self.signoffs[key]
157
+ if subject is None and tool_name in self.granted_tools:
158
+ return True, None
159
+ return False, None