@yahyahammad/venastine 0.1.0 → 0.3.8
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.
- package/.env.example +19 -14
- package/CONFIG_ARCHITECTURE.md +2002 -0
- package/NOTICE +1 -1
- package/README.md +249 -93
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/plan.md +23 -5
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +261 -195
- package/agents/subagent_tool.py +280 -23
- package/agents/tui_commands.py +31 -21
- package/bin/venastine.mjs +528 -382
- package/bin/venastine.py +71 -0
- package/cli_commands.py +835 -0
- package/config.py +95 -1198
- package/config.yaml +1090 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +966 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +256 -0
- package/core/ansi.py +452 -0
- package/core/approval.py +27 -5
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +1249 -82
- package/core/commands.py +454 -0
- package/core/compaction.py +1735 -959
- package/core/config_loader.py +516 -97
- package/core/connect.py +686 -0
- package/core/events.py +68 -6
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +87 -4
- package/core/line_pattern.py +128 -0
- package/core/loop.py +2566 -1353
- package/core/memory.py +482 -370
- package/core/pipeline_models.py +23 -9
- package/core/provider_errors.py +234 -0
- package/core/reasoning/confidence_scoring.py +70 -54
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +232 -53
- package/core/reasoning/output_writer.py +90 -31
- package/core/reasoning/payload_validation.py +133 -7
- package/core/reasoning/pipeline_storage.py +427 -361
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +38 -14
- package/core/reasoning/source_corpus.py +110 -4
- package/core/replay.py +315 -167
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +308 -180
- package/database.py +82 -1
- package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +118 -77
- package/json_store.py +236 -16
- package/logging_setup.py +121 -11
- package/main.py +1672 -198
- package/mcp_client/client.py +257 -23
- package/mcp_client/config.py +484 -379
- package/mcp_client/registration.py +163 -2
- package/memories/manager.py +15 -0
- package/memories/tui_commands.py +21 -14
- package/package.json +303 -73
- package/project_init/config_files.py +4 -0
- package/project_init/generator.py +201 -37
- package/project_init/manifest.py +418 -406
- package/project_init/tui_commands.py +7 -4
- package/prompts/revalidate.md +1 -1
- package/prompts/revise.md +17 -15
- package/prompts/system_prompts.py +64 -10
- package/providers.json.example +94 -92
- package/pyproject.toml +149 -100
- package/requirements.txt +252 -29
- package/safety/policy_enforcement.py +1082 -682
- package/security/askpass.py +419 -0
- package/security/capability.py +37 -7
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +54 -7
- package/security/posture.py +124 -12
- package/security/protected_paths.py +198 -6
- package/security/sandbox.py +3262 -139
- package/security/secrets.py +855 -0
- package/skills/tui_commands.py +3 -4
- package/storage.py +1338 -1005
- package/tools/base.py +465 -305
- package/tools/builtin/_math_common.py +306 -16
- package/tools/builtin/_net_common.py +267 -61
- package/tools/builtin/arxiv.py +681 -223
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +239 -21
- package/tools/builtin/file_ops.py +341 -33
- package/tools/builtin/geometry.py +184 -148
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +10 -0
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +46 -12
- package/tools/builtin/probability_stats.py +224 -228
- package/tools/builtin/project_docs.py +80 -21
- package/tools/builtin/remember.py +21 -4
- package/tools/builtin/shell.py +586 -67
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +5 -3
- package/tools/builtin/web_search.py +329 -151
- package/tools/context.py +23 -0
- package/tools/isolation.py +387 -314
- package/tools/registry.py +374 -29
- package/tui/app.py +5281 -397
- package/tui/app.tcss +290 -9
- package/tui/commands.py +26 -61
- package/tui/diffs.py +286 -265
- package/tui/history.py +128 -0
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +1329 -0
- package/tui/meters.py +364 -0
- package/tui/screens.py +346 -92
- package/tui/themes.py +599 -366
- package/tui/widgets.py +2673 -116
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
package/tools/base.py
CHANGED
|
@@ -1,305 +1,465 @@
|
|
|
1
|
-
from
|
|
2
|
-
from
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
#
|
|
8
|
-
#
|
|
9
|
-
#
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
-
#
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
#
|
|
35
|
-
#
|
|
36
|
-
#
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
#
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
#
|
|
158
|
-
#
|
|
159
|
-
#
|
|
160
|
-
|
|
161
|
-
#
|
|
162
|
-
#
|
|
163
|
-
#
|
|
164
|
-
#
|
|
165
|
-
#
|
|
166
|
-
#
|
|
167
|
-
#
|
|
168
|
-
#
|
|
169
|
-
#
|
|
170
|
-
#
|
|
171
|
-
#
|
|
172
|
-
#
|
|
173
|
-
#
|
|
174
|
-
#
|
|
175
|
-
|
|
176
|
-
#
|
|
177
|
-
#
|
|
178
|
-
#
|
|
179
|
-
#
|
|
180
|
-
#
|
|
181
|
-
#
|
|
182
|
-
#
|
|
183
|
-
|
|
184
|
-
#
|
|
185
|
-
#
|
|
186
|
-
#
|
|
187
|
-
#
|
|
188
|
-
#
|
|
189
|
-
#
|
|
190
|
-
#
|
|
191
|
-
#
|
|
192
|
-
|
|
193
|
-
#
|
|
194
|
-
#
|
|
195
|
-
#
|
|
196
|
-
#
|
|
197
|
-
#
|
|
198
|
-
#
|
|
199
|
-
#
|
|
200
|
-
#
|
|
201
|
-
#
|
|
202
|
-
|
|
203
|
-
#
|
|
204
|
-
#
|
|
205
|
-
#
|
|
206
|
-
#
|
|
207
|
-
#
|
|
208
|
-
|
|
209
|
-
#
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
to
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
#
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
1
|
+
from collections.abc import Callable, Iterable
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
from typing import Optional
|
|
4
|
+
|
|
5
|
+
from pydantic import ValidationError
|
|
6
|
+
|
|
7
|
+
# ROADMAP_v2 §25 (R13). How far approving a tool BY NAME goes -- the
|
|
8
|
+
# question asked before any call exists, by the §18 subagent sign-off and
|
|
9
|
+
# by the §25 pipeline grant.
|
|
10
|
+
#
|
|
11
|
+
# Three values rather than two booleans. Booleans can express "an
|
|
12
|
+
# unattended pipeline run may pre-grant this, but a human answering in the
|
|
13
|
+
# moment may not", which is incoherent -- the pipeline is strictly
|
|
14
|
+
# stricter than the sign-off, so the answers form an order.
|
|
15
|
+
GRANT_ANYWHERE = "anywhere"
|
|
16
|
+
GRANT_SIGNOFF_ONLY = "signoff_only"
|
|
17
|
+
GRANT_NEVER = "never"
|
|
18
|
+
|
|
19
|
+
GRANT_POLICIES = frozenset({GRANT_ANYWHERE, GRANT_SIGNOFF_ONLY, GRANT_NEVER})
|
|
20
|
+
|
|
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
|
+
|
|
42
|
+
# ROADMAP_v2 §31 (H1). What a call to this tool is allowed to COST, and
|
|
43
|
+
# therefore which mechanism bounds it. Asked once, at registration, for
|
|
44
|
+
# the same reason grant_policy is: the answer is a property of the tool,
|
|
45
|
+
# and a layer that infers it from a name or a module is a second source
|
|
46
|
+
# of truth that drifts the moment a tool is added.
|
|
47
|
+
#
|
|
48
|
+
# BUDGET_COMPUTE A pure function of its params. Nothing bounds it from
|
|
49
|
+
# the INSIDE -- sympy has no interruption points -- so
|
|
50
|
+
# dispatch runs it in a killable subprocess under
|
|
51
|
+
# config.TOOL_COMPUTE_TIMEOUT_S (H2).
|
|
52
|
+
# BUDGET_IO Carries its own bound already: a request timeout, a
|
|
53
|
+
# size check before opening, a sandbox, or an operation
|
|
54
|
+
# bounded by construction. NOT wrapped by dispatch,
|
|
55
|
+
# because an outer clock over a blocking read can only
|
|
56
|
+
# stop WAITING -- mcp_client says so about its own
|
|
57
|
+
# backstop, and a mechanism that reports a timeout while
|
|
58
|
+
# the work continues is worse than none (H7).
|
|
59
|
+
# BUDGET_HUMAN Blocks on a person, or on a sub-run metered
|
|
60
|
+
# separately. ask_user waits up to
|
|
61
|
+
# ATTENDED_APPROVAL_TIMEOUT_S; spawn_subagent is bounded
|
|
62
|
+
# by the child's max_steps and the token budget. A
|
|
63
|
+
# compute clock over either would be a bug, not a
|
|
64
|
+
# tightening (H8).
|
|
65
|
+
BUDGET_COMPUTE = "compute"
|
|
66
|
+
BUDGET_IO = "io"
|
|
67
|
+
BUDGET_HUMAN = "human"
|
|
68
|
+
|
|
69
|
+
BUDGETS = frozenset({BUDGET_COMPUTE, BUDGET_IO, BUDGET_HUMAN})
|
|
70
|
+
|
|
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
|
+
|
|
155
|
+
@dataclass
|
|
156
|
+
class ToolSpec:
|
|
157
|
+
name: str # Tool name
|
|
158
|
+
schema: dict # Tool schema
|
|
159
|
+
handler: Callable[[dict], dict] # The actual function the tool runs
|
|
160
|
+
# Optional path-dependent approval policy. When present, its result is
|
|
161
|
+
# OR'd with the generic requires_approval() lookup by
|
|
162
|
+
# registry.approval_needed(). Signature: (tool_name, params) -> bool.
|
|
163
|
+
# Used by file_ops to auto-approve within WORKSPACE_DIR and require
|
|
164
|
+
# user approval outside it, and by shell for Docker-availability.
|
|
165
|
+
#
|
|
166
|
+
# ROADMAP_v2 §15 changed this from a REPLACEMENT for requires_approval
|
|
167
|
+
# to one term of an OR. Before, defining an approval_check made a tool
|
|
168
|
+
# invisible to config/context-level approval settings entirely, which
|
|
169
|
+
# would have silently voided agent approval_overrides for read/write/
|
|
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.
|
|
175
|
+
approval_check: Optional[Callable[[str, dict], bool]] = None
|
|
176
|
+
# Optional "is this tool meaningful right now?" predicate, consulted by
|
|
177
|
+
# registry.schemas() when deciding what to advertise to the model.
|
|
178
|
+
# Signature: () -> bool. Distinct from permissions: the tool is allowed,
|
|
179
|
+
# it just has nothing to act on yet (load_skill with an empty catalog).
|
|
180
|
+
# Not consulted by dispatch() -- a tool declaring itself unavailable is
|
|
181
|
+
# expected to return a clean error if called anyway, and a second denial
|
|
182
|
+
# path would only add a worse message.
|
|
183
|
+
available_check: Optional[Callable[[], bool]] = None
|
|
184
|
+
# Optional "once approved in this run, don't ask again" marker. Only
|
|
185
|
+
# "run" is defined; None (the default) means every call is asked about
|
|
186
|
+
# independently, which is the existing behaviour for every builtin.
|
|
187
|
+
#
|
|
188
|
+
# Exists so §18's subagent sign-off is a property of spawn_subagent
|
|
189
|
+
# rather than a tool name hard-coded into core/loop.py -- the loop asks
|
|
190
|
+
# the registry what a tool's grant scope is, the same way it asks
|
|
191
|
+
# whether approval is needed at all. §23's response channel reuses it.
|
|
192
|
+
grant_scope: Optional[str] = None
|
|
193
|
+
# ROADMAP_v2 §23. Which KIND of question approving this tool asks.
|
|
194
|
+
# "approval" (the default) is a yes/no; spawn_subagent sets
|
|
195
|
+
# "subagent_signoff", whose answer is the SUBSET of tools the child may
|
|
196
|
+
# then use without asking again.
|
|
197
|
+
#
|
|
198
|
+
# A property of the tool rather than a name hard-coded into
|
|
199
|
+
# core/loop.py, for exactly the reason grant_scope is: the loop asks
|
|
200
|
+
# the registry what shape of question a tool needs, the same way it
|
|
201
|
+
# asks whether it needs one at all.
|
|
202
|
+
request_kind: str = "approval"
|
|
203
|
+
# Optional extra fields for that question's payload, when the answer
|
|
204
|
+
# depends on something only the tool knows. Signature:
|
|
205
|
+
# (params, context) -> dict. spawn_subagent uses it to carry the
|
|
206
|
+
# candidate tool list, which is agents/manager.py's knowledge and must
|
|
207
|
+
# not become the loop's. Mirrors approval_notice exactly.
|
|
208
|
+
request_payload: Optional[Callable[[dict, object], dict]] = None
|
|
209
|
+
# ROADMAP_v2 §32 (A7). Optional "I would refuse this call anyway"
|
|
210
|
+
# pre-flight. Signature: (params, context) -> Optional[str], the
|
|
211
|
+
# refusal reason or None. Returning a reason does NOT deny the
|
|
212
|
+
# call -- the handler still runs and still refuses; it tells the
|
|
213
|
+
# loop not to ASK first.
|
|
214
|
+
#
|
|
215
|
+
# core/loop.py already establishes this ordering for the case it
|
|
216
|
+
# can see on its own: "a context-excluded tool reports the context
|
|
217
|
+
# denial instead of prompting and then being denied anyway". That
|
|
218
|
+
# reasoning is not specific to contexts, but the loop cannot apply
|
|
219
|
+
# it to a condition only the tool knows -- spawn_subagent's
|
|
220
|
+
# unknown-agent and depth-limit checks live inside run(), so both
|
|
221
|
+
# prompted first and errored second. An unknown name produced a
|
|
222
|
+
# sign-off modal with an EMPTY notice and an EMPTY candidate list:
|
|
223
|
+
# a question with nothing in it.
|
|
224
|
+
#
|
|
225
|
+
# A property of the tool rather than a name hard-coded into the
|
|
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.
|
|
232
|
+
refusal_check: Optional[Callable[[dict, object], Optional[str]]] = None
|
|
233
|
+
# Optional extra text shown in the approval prompt, above the params.
|
|
234
|
+
# Signature: (params, context) -> str. Lets a tool explain what
|
|
235
|
+
# approving actually authorises when the params alone don't say --
|
|
236
|
+
# spawn_subagent uses it to list the tools the subagent would then be
|
|
237
|
+
# able to run without asking again. Keeps that knowledge in the tool
|
|
238
|
+
# instead of teaching the TUI about agents.
|
|
239
|
+
approval_notice: Optional[Callable[[dict, object], str]] = None
|
|
240
|
+
# ROADMAP_v2 §25 (R13). One of GRANT_ANYWHERE / GRANT_SIGNOFF_ONLY /
|
|
241
|
+
# GRANT_NEVER, above.
|
|
242
|
+
#
|
|
243
|
+
# DISTINCT from registry.grantable(), which is mechanical: does this
|
|
244
|
+
# tool decide approval from its PARAMS, in which case a name-level
|
|
245
|
+
# answer was never about the call that happens. This field is policy:
|
|
246
|
+
# given that consent by name is meaningful, is ONE TICK BEFORE ANY
|
|
247
|
+
# CALL EXISTS an acceptable answer, and does that depend on whether a
|
|
248
|
+
# human is present? Both callers check both.
|
|
249
|
+
#
|
|
250
|
+
# None means UNDECLARED, not a default. Omission has to be a
|
|
251
|
+
# detectable mistake rather than an inherited answer -- this field
|
|
252
|
+
# exists because the previous shape was a denylist in ONE consumer's
|
|
253
|
+
# module, so a tool registered after it was written was offered for a
|
|
254
|
+
# grant without anybody being asked. That is what happened to
|
|
255
|
+
# write_project_doc between §24 and #133.
|
|
256
|
+
#
|
|
257
|
+
# assert_grant_policy_declared() below makes omission fatal at import,
|
|
258
|
+
# the same trade D24 made for permissions.
|
|
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
|
|
294
|
+
# ROADMAP_v2 §31 (H1). One of BUDGET_COMPUTE / BUDGET_IO /
|
|
295
|
+
# BUDGET_HUMAN, above.
|
|
296
|
+
#
|
|
297
|
+
# None means UNDECLARED, not a default -- grant_policy's rule one
|
|
298
|
+
# question over, for grant_policy's reason. Before §31 every bound in
|
|
299
|
+
# the tool layer was per-tool and voluntary: three network tools each
|
|
300
|
+
# set their own REQUEST_TIMEOUT_S, `shell` inherited the sandbox's,
|
|
301
|
+
# and MCP tools got a two-layer clock in mcp_client -- while the six
|
|
302
|
+
# math tools, the only ones that can burn a core indefinitely, had
|
|
303
|
+
# none at all (#57). A default here would recreate exactly that, and
|
|
304
|
+
# silently: an unwrapped tool looks identical to a correctly bounded
|
|
305
|
+
# one from every layer above.
|
|
306
|
+
#
|
|
307
|
+
# assert_budget_declared() below makes omission fatal at import.
|
|
308
|
+
budget: Optional[str] = None
|
|
309
|
+
# ROADMAP_v2 §42 (RA2). Which parameter, if any, carries the
|
|
310
|
+
# AGENT'S OWN STATED REASON for making this call. `shell` sets
|
|
311
|
+
# "rationale"; every other tool leaves it None.
|
|
312
|
+
#
|
|
313
|
+
# DISPLAY ONLY, and that is the whole contract. The named param is
|
|
314
|
+
# rendered on the approval prompt and skipped by the transcript
|
|
315
|
+
# digest, and it reaches NOTHING else: not
|
|
316
|
+
# `_shell_approval_check`, not `classify_command`, not
|
|
317
|
+
# `run_sandboxed`. A self-reported reason is unverifiable by
|
|
318
|
+
# construction -- a hijacked agent writes a reassuring one -- so
|
|
319
|
+
# letting it touch a decision would be strictly worse than not
|
|
320
|
+
# having it. Its value is longitudinal: a thread's worth of stated
|
|
321
|
+
# reasons, archived beside the calls, is a drift signal no single
|
|
322
|
+
# prompt can give. test_rationale.py pins the invariance by
|
|
323
|
+
# asserting on the arguments the classifier RECEIVES, not on the
|
|
324
|
+
# decision it returns -- an outcome check would pass for a tool
|
|
325
|
+
# that read the field and happened to agree.
|
|
326
|
+
#
|
|
327
|
+
# NO IMPORT-TIME GUARD, unlike grant_policy and budget. For those,
|
|
328
|
+
# None is an unanswered question and silence is the failure; here
|
|
329
|
+
# None is the correct answer for every tool but one, so a
|
|
330
|
+
# declaration requirement would be noise on twenty-two of them.
|
|
331
|
+
rationale_param: Optional[str] = None
|
|
332
|
+
# ROADMAP_v2 §46 (EP2). Which parameter, if any, is the SUBJECT of
|
|
333
|
+
# the approval question -- the one thing a person must read before
|
|
334
|
+
# answering. `shell` sets "command"; every other tool leaves it
|
|
335
|
+
# None and its modal is unchanged.
|
|
336
|
+
#
|
|
337
|
+
# Mechanism, not policy, in the shape rationale_param established
|
|
338
|
+
# directly above: the consumer asks the registry rather than testing
|
|
339
|
+
# for the literal name `shell`, so no tool name enters core/loop.py
|
|
340
|
+
# or tui/screens.py. Two consumers need it -- the TUI modal, which
|
|
341
|
+
# PINS it outside the scroll region, and the CLI prompt, which
|
|
342
|
+
# leads with it.
|
|
343
|
+
#
|
|
344
|
+
# DISPLAY ONLY, exactly like rationale_param, and for a different
|
|
345
|
+
# reason: this value is ALSO in `params`, which the prompt renders
|
|
346
|
+
# whole. Nothing may read it to decide anything, because the thing
|
|
347
|
+
# that decides is `classify_command`, and a second reader of the
|
|
348
|
+
# same field is how the two came to disagree in #157.
|
|
349
|
+
#
|
|
350
|
+
# Why it is not just `params["command"]` at the render site: a
|
|
351
|
+
# screen that knows a parameter name knows a tool, and the modal is
|
|
352
|
+
# shared by web_search, spawn_subagent, the MCP tools and /init's
|
|
353
|
+
# confirm. EP1 pins the SUBJECT of the question, whatever the tool
|
|
354
|
+
# says that is.
|
|
355
|
+
#
|
|
356
|
+
# NO IMPORT-TIME GUARD, for rationale_param's reason: None is the
|
|
357
|
+
# correct answer for every tool but one.
|
|
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
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
def assert_grant_policy_declared(tools: Iterable[str], specs=None) -> None:
|
|
374
|
+
"""R13: every statically registered tool must declare a grant policy,
|
|
375
|
+
and it must be one of the three defined values.
|
|
376
|
+
|
|
377
|
+
Raises rather than warning, for D24's reason: the failure this guards
|
|
378
|
+
against is invisible at runtime. A tool with no declaration resolves
|
|
379
|
+
to GRANT_NEVER (registry.grant_policy), so forgetting the field would
|
|
380
|
+
silently drop a tool out of both grant paths with nothing logged --
|
|
381
|
+
and a MISSPELLED value would do the same while looking answered,
|
|
382
|
+
which is worse. Both are caught here instead.
|
|
383
|
+
|
|
384
|
+
The precedent is `fetch_url` under D24: registered, documented as
|
|
385
|
+
working, and denied on every call for its entire life because nobody
|
|
386
|
+
added a field. The equivalent mistake here is quieter still, because
|
|
387
|
+
a tool that is never offered for a grant simply prompts per call --
|
|
388
|
+
correct-looking behaviour that hides an unanswered policy question.
|
|
389
|
+
|
|
390
|
+
Dynamically-named `mcp__*` tools are exempt by design; they are named
|
|
391
|
+
at connection time and can never carry a static declaration.
|
|
392
|
+
`mcp_client/registration.py` passes one explicitly anyway, so the
|
|
393
|
+
fallback is documentation rather than the live path.
|
|
394
|
+
"""
|
|
395
|
+
specs = specs if specs is not None else tools
|
|
396
|
+
undeclared, invalid = [], []
|
|
397
|
+
for name in tools:
|
|
398
|
+
if name.startswith("mcp__"):
|
|
399
|
+
continue
|
|
400
|
+
spec = specs.get(name) if hasattr(specs, "get") else None
|
|
401
|
+
policy = getattr(spec, "grant_policy", None)
|
|
402
|
+
if policy is None:
|
|
403
|
+
undeclared.append(name)
|
|
404
|
+
elif policy not in GRANT_POLICIES:
|
|
405
|
+
invalid.append(f"{name}={policy!r}")
|
|
406
|
+
if undeclared or invalid:
|
|
407
|
+
raise RuntimeError(
|
|
408
|
+
"Tools are registered without a usable grant policy, so the "
|
|
409
|
+
"question of whether one tick before any call exists may "
|
|
410
|
+
"authorise them was never answered: "
|
|
411
|
+
f"undeclared={sorted(undeclared)} invalid={sorted(invalid)}. "
|
|
412
|
+
f"Set ToolSpec.grant_policy to one of {sorted(GRANT_POLICIES)} "
|
|
413
|
+
"(ROADMAP_v2 §25, R13)."
|
|
414
|
+
)
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def assert_budget_declared(tools: Iterable[str], specs=None,
|
|
418
|
+
injectable=None) -> None:
|
|
419
|
+
"""H1: every statically registered tool must declare a cost class, it
|
|
420
|
+
must be one of the three defined values, and a BUDGET_COMPUTE tool
|
|
421
|
+
must not also declare an injection.
|
|
422
|
+
|
|
423
|
+
Raises rather than warning, and the argument is the one above it,
|
|
424
|
+
unchanged: the failure is invisible at runtime. An undeclared tool is
|
|
425
|
+
simply not wrapped, which from every layer above looks exactly like a
|
|
426
|
+
tool that is correctly bounded somewhere else -- and that is the state
|
|
427
|
+
#57 found, where dispatch called every handler directly and nothing
|
|
428
|
+
anywhere recorded whether that was intended.
|
|
429
|
+
|
|
430
|
+
The third check is not a style rule. BUDGET_COMPUTE is not merely a
|
|
431
|
+
policy: it routes the call through a PROCESS boundary, and nothing in
|
|
432
|
+
_INJECTABLE_PARAMS survives one. A live ConversationMemory or a
|
|
433
|
+
response_channel cannot be pickled, so a tool declaring both would
|
|
434
|
+
fail at its first call rather than here. The two fields are checked
|
|
435
|
+
together because neither is wrong on its own.
|
|
436
|
+
|
|
437
|
+
Dynamically-named `mcp__*` tools are exempt, as they are for
|
|
438
|
+
grant_policy and for the same reason -- they are named at connection
|
|
439
|
+
time. Their bound is mcp_client's own two-layer clock, and
|
|
440
|
+
registration.py passes BUDGET_IO explicitly to say so.
|
|
441
|
+
"""
|
|
442
|
+
specs = specs if specs is not None else tools
|
|
443
|
+
injectable = injectable or {}
|
|
444
|
+
undeclared, invalid, contradictory = [], [], []
|
|
445
|
+
for name in tools:
|
|
446
|
+
if name.startswith("mcp__"):
|
|
447
|
+
continue
|
|
448
|
+
spec = specs.get(name) if hasattr(specs, "get") else None
|
|
449
|
+
budget = getattr(spec, "budget", None)
|
|
450
|
+
if budget is None:
|
|
451
|
+
undeclared.append(name)
|
|
452
|
+
elif budget not in BUDGETS:
|
|
453
|
+
invalid.append(f"{name}={budget!r}")
|
|
454
|
+
elif budget == BUDGET_COMPUTE and injectable.get(name):
|
|
455
|
+
contradictory.append(
|
|
456
|
+
f"{name} injects {sorted(injectable[name])}")
|
|
457
|
+
if undeclared or invalid or contradictory:
|
|
458
|
+
raise RuntimeError(
|
|
459
|
+
"Tools are registered without a usable cost class, so what a "
|
|
460
|
+
"call to them is allowed to cost was never answered: "
|
|
461
|
+
f"undeclared={sorted(undeclared)} invalid={sorted(invalid)} "
|
|
462
|
+
f"compute-with-injection={sorted(contradictory)}. "
|
|
463
|
+
f"Set ToolSpec.budget to one of {sorted(BUDGETS)} "
|
|
464
|
+
"(ROADMAP_v2 §31, H1)."
|
|
465
|
+
)
|