@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.
- package/.env.example +9 -4
- package/CONFIG_ARCHITECTURE.md +2030 -0
- package/LICENSE +201 -201
- package/NOTICE +1 -1
- package/README.md +1034 -895
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -88
- package/agents/builtin/review.md +74 -74
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +68 -2
- package/agents/subagent_tool.py +472 -238
- package/agents/tui_commands.py +238 -151
- package/bin/venastine.mjs +150 -4
- package/bin/venastine.py +71 -0
- package/cli_commands.py +838 -0
- package/config.py +95 -1198
- package/config.yaml +1103 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +971 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +256 -118
- package/core/ansi.py +452 -0
- package/core/approval.py +137 -115
- 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 +2715 -1559
- package/core/commands.py +460 -0
- package/core/compaction.py +1735 -971
- package/core/config_loader.py +1982 -1563
- package/core/connect.py +686 -0
- package/core/events.py +123 -61
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +411 -328
- package/core/line_pattern.py +128 -0
- package/core/loop.py +2566 -1490
- package/core/memory.py +482 -370
- package/core/pipeline_models.py +190 -176
- package/core/provider_errors.py +234 -0
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -468
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +1561 -1382
- package/core/reasoning/output_writer.py +345 -286
- package/core/reasoning/payload_validation.py +524 -398
- package/core/reasoning/pipeline_storage.py +88 -22
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +458 -434
- package/core/reasoning/source_corpus.py +433 -327
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -183
- 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 +148 -20
- package/database.py +333 -252
- package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +50 -9
- package/json_store.py +343 -123
- package/logging_setup.py +295 -185
- package/main.py +3433 -1961
- package/mcp_client/client.py +733 -499
- package/mcp_client/config.py +126 -21
- package/mcp_client/registration.py +343 -182
- package/memories/manager.py +147 -132
- package/memories/tui_commands.py +319 -244
- package/package.json +303 -73
- package/project_init/config_files.py +282 -278
- package/project_init/generator.py +728 -564
- package/project_init/manifest.py +18 -6
- package/project_init/tui_commands.py +147 -144
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +2 -0
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -262
- package/providers.json.example +4 -2
- package/pyproject.toml +149 -100
- package/requirements.txt +295 -72
- package/safety/policy_enforcement.py +1082 -746
- package/security/askpass.py +419 -0
- package/security/capability.py +207 -177
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +237 -190
- package/security/posture.py +124 -12
- package/security/protected_paths.py +501 -309
- package/security/sandbox.py +4108 -985
- package/security/secrets.py +855 -0
- package/skills/builtin/math/formal-specification.md +67 -67
- package/skills/builtin/math/numerical-methods.md +66 -66
- package/skills/builtin/research/experiment-design.md +62 -62
- package/skills/builtin/research/reproducibility.md +55 -55
- package/skills/builtin/research/source-evaluation.md +70 -70
- package/skills/builtin/research/statistical-inference.md +63 -63
- package/skills/builtin/research/technical-writing.md +59 -59
- package/skills/builtin/software/code-review.md +61 -61
- package/skills/builtin/software/debugging.md +61 -61
- package/skills/builtin/software/test-design.md +67 -67
- package/skills/tui_commands.py +110 -111
- package/storage.py +1338 -1005
- package/tools/base.py +161 -1
- package/tools/builtin/_math_common.py +667 -377
- package/tools/builtin/_net_common.py +225 -19
- package/tools/builtin/arxiv.py +497 -39
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +371 -153
- package/tools/builtin/file_ops.py +720 -412
- package/tools/builtin/geometry.py +48 -12
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +76 -66
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +227 -193
- package/tools/builtin/probability_stats.py +12 -16
- package/tools/builtin/project_docs.py +464 -405
- package/tools/builtin/remember.py +175 -158
- package/tools/builtin/shell.py +980 -461
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +149 -147
- package/tools/builtin/web_search.py +191 -13
- package/tools/context.py +159 -136
- package/tools/isolation.py +107 -34
- package/tools/registry.py +1242 -925
- package/tui/app.py +8318 -4100
- package/tui/app.tcss +747 -556
- package/tui/commands.py +26 -170
- package/tui/diffs.py +34 -13
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +1329 -1279
- package/tui/meters.py +364 -268
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -943
- package/tui/themes.py +599 -559
- package/tui/widgets.py +3813 -2332
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
|
@@ -8,11 +8,11 @@ from __future__ import annotations
|
|
|
8
8
|
import logging
|
|
9
9
|
from typing import Optional
|
|
10
10
|
|
|
11
|
-
from pydantic import BaseModel, Field, field_validator
|
|
12
11
|
from ddgs import DDGS
|
|
12
|
+
from pydantic import BaseModel, Field, field_validator
|
|
13
13
|
|
|
14
14
|
from safety.policy_enforcement import is_url_permitted
|
|
15
|
-
from tools.builtin._net_common import TTLCache
|
|
15
|
+
from tools.builtin._net_common import MAX_URL_CHARS, ThirdPartyText, TTLCache
|
|
16
16
|
|
|
17
17
|
logger = logging.getLogger(__name__)
|
|
18
18
|
|
|
@@ -22,6 +22,15 @@ logger = logging.getLogger(__name__)
|
|
|
22
22
|
class WebSearchParams(BaseModel):
|
|
23
23
|
query: str = Field(..., description="Search query", min_length=1, max_length=400)
|
|
24
24
|
num_results: int = Field(5, ge=1, le=10, description="Number of results to return")
|
|
25
|
+
page: int = Field(
|
|
26
|
+
1,
|
|
27
|
+
ge=1,
|
|
28
|
+
description=(
|
|
29
|
+
"Which page of results to return (1-based). Use the page named "
|
|
30
|
+
"in a result's message to see further results for the same "
|
|
31
|
+
"query."
|
|
32
|
+
),
|
|
33
|
+
)
|
|
25
34
|
|
|
26
35
|
@field_validator("query")
|
|
27
36
|
@classmethod
|
|
@@ -51,6 +60,19 @@ class SearchResult(BaseModel):
|
|
|
51
60
|
snippet: str
|
|
52
61
|
published: Optional[str] = None # ddgs's text search doesn't return a
|
|
53
62
|
# publish date, so this stays None here
|
|
63
|
+
# ROADMAP_v3 §51 (PG8). Whether MAX_SNIPPET_CHARS cut this one, and
|
|
64
|
+
# where the rest is. Before §51 a cut snippet and a short one were
|
|
65
|
+
# indistinguishable, so "the source does not mention X" and "the first
|
|
66
|
+
# 300 characters do not mention X" read the same to the model.
|
|
67
|
+
snippet_truncated: bool = False
|
|
68
|
+
# Batch 156 (PG8's shape, one field over). The snippet had a cap and a
|
|
69
|
+
# flag and the title beside it had neither, so a 5,000-character title
|
|
70
|
+
# went to the model whole while the snippet under it was cut to 300 --
|
|
71
|
+
# measured, in the same result. FLAG AND NO ROUTE, which is the
|
|
72
|
+
# asymmetry `arxiv.py` already argues for the same field: a title past
|
|
73
|
+
# the cap is a malformed result rather than a long one, and the route
|
|
74
|
+
# to the page is the `url` sitting next to it either way.
|
|
75
|
+
title_truncated: bool = False
|
|
54
76
|
|
|
55
77
|
|
|
56
78
|
class WebSearchError(Exception):
|
|
@@ -62,6 +84,20 @@ class WebSearchError(Exception):
|
|
|
62
84
|
# ---- Policy / tuning knobs -------------------------------------------------
|
|
63
85
|
|
|
64
86
|
MAX_SNIPPET_CHARS = 300
|
|
87
|
+
|
|
88
|
+
# Batch 156. 300 is the number `arxiv.py` settled for the same kind of
|
|
89
|
+
# value, measured there over sixty real entries whose longest title was
|
|
90
|
+
# 188 characters. NOT imported from it: two constants with one reason each
|
|
91
|
+
# is the choice `_MAX_AUTHORS` already argues for one file over, and these
|
|
92
|
+
# two bound titles from two different providers.
|
|
93
|
+
#
|
|
94
|
+
# No equivalent measurement was taken for web titles in this batch, and
|
|
95
|
+
# saying so is the honest version. What justifies the number here is that
|
|
96
|
+
# it is the one already settled for a title, and a title is the same kind
|
|
97
|
+
# of value whichever provider hands it over; the HTML spec puts no bound on
|
|
98
|
+
# `<title>` at all.
|
|
99
|
+
MAX_TITLE_CHARS = 300
|
|
100
|
+
|
|
65
101
|
REQUEST_TIMEOUT_S = 8.0
|
|
66
102
|
MAX_RETRIES = 2
|
|
67
103
|
CACHE_TTL_S = 300
|
|
@@ -73,45 +109,168 @@ _cache = TTLCache(CACHE_TTL_S)
|
|
|
73
109
|
|
|
74
110
|
# ---- Provider call ----------------------------------------------------------
|
|
75
111
|
|
|
76
|
-
def _call_ddgs(query: str, num_results: int) -> list[dict]:
|
|
112
|
+
def _call_ddgs(query: str, num_results: int, page: int = 1) -> list[dict]:
|
|
77
113
|
"""
|
|
78
114
|
The one function that actually talks to DuckDuckGo. DDGS() is
|
|
79
115
|
instantiated fresh per call (cheap) and used as a context manager so
|
|
80
116
|
its underlying HTTP session gets cleaned up automatically afterward.
|
|
117
|
+
|
|
118
|
+
`page` is ROADMAP_v3 §51 (PG3's sibling). The record assumed this tool
|
|
119
|
+
had no paging to expose and only a snippet cap to fix; MEASURED (batch
|
|
120
|
+
105), `ddgs 9.14.4` takes `page: int = 1` on its search path and
|
|
121
|
+
accepted it live. So the provider implemented paging here too, and this
|
|
122
|
+
tool was spending the parameter on a default.
|
|
123
|
+
|
|
124
|
+
ALSO MEASURED, and the reason the message this feeds is worded the way
|
|
125
|
+
it is: page 2 of a live query OVERLAPPED page 1 by one result. DuckDuckGo's
|
|
126
|
+
paging is not a clean partition the way arXiv's `start` is (measured the
|
|
127
|
+
same day: zero overlap), so a page here is "more results", not "the next
|
|
128
|
+
five distinct results", and nothing downstream may assume otherwise.
|
|
81
129
|
"""
|
|
82
130
|
with DDGS(timeout=REQUEST_TIMEOUT_S) as ddgs_client:
|
|
83
|
-
return ddgs_client.text(query, max_results=num_results)
|
|
131
|
+
return ddgs_client.text(query, max_results=num_results, page=page)
|
|
84
132
|
|
|
85
133
|
|
|
86
134
|
def _normalize(raw: list[dict]) -> list[SearchResult]:
|
|
135
|
+
"""DDGS's rows as `SearchResult`s, redacted and bounded (§73).
|
|
136
|
+
|
|
137
|
+
EVERY STRING IN HERE WAS WRITTEN BY SOMEBODY ELSE, which is the rule
|
|
138
|
+
PG8/#131 states and the reason all of it goes through one helper now.
|
|
139
|
+
Two things were wrong at once and they interact, so fixing either alone
|
|
140
|
+
would have been worse than fixing neither:
|
|
141
|
+
|
|
142
|
+
REDACT ABOVE THE CUT (RB1, A59). The snippet was cut to 300 characters
|
|
143
|
+
and `registry.dispatch` redacted the piece that was kept. Measured
|
|
144
|
+
(batch 156), a `ghp_` token straddling that cut survived post-hoc
|
|
145
|
+
redaction at 36 of the 39 offsets it could straddle -- the kept prefix
|
|
146
|
+
is not the token, the dropped suffix is gone, and `param_digest`'s
|
|
147
|
+
docstring had already written down why ("truncating first cuts a
|
|
148
|
+
credential below the 20 characters its pattern needs").
|
|
149
|
+
|
|
150
|
+
AND THE CUTS THAT DID NOT EXIST YET. The title had no bound at all, so
|
|
151
|
+
adding one without the ordering above would have MANUFACTURED a second
|
|
152
|
+
straddle site in the field being repaired. Every new cap here is a new
|
|
153
|
+
cut, and every cut needs the redaction above it.
|
|
154
|
+
|
|
155
|
+
TOTAL OVER WHATEVER DDGS RETURNED (A61), which is the half no report
|
|
156
|
+
named. `r.get("title", "(untitled)")` substitutes only for an ABSENT
|
|
157
|
+
key, and `{"title": null}` is a present one -- the lesson
|
|
158
|
+
`tools/base.py` states for tool arguments, arriving from the provider
|
|
159
|
+
end. Measured, a single row with `title: null` raised `ValidationError`
|
|
160
|
+
out of here, which `run` caught as a failed attempt, RETRIED TWICE,
|
|
161
|
+
and then reported as "search failed after 3 attempts" -- ten good
|
|
162
|
+
results lost to one malformed one, plus two pointless re-queries.
|
|
163
|
+
`arxiv._parse_atom_feed` had the identical defect and fixed it in batch
|
|
164
|
+
117 ("SKIPPED, NOT RAISED ... Raising here aborted the whole search
|
|
165
|
+
over one malformed entry"); the cure was one file over the whole time.
|
|
166
|
+
"""
|
|
167
|
+
third = ThirdPartyText("web_search")
|
|
87
168
|
out: list[SearchResult] = []
|
|
88
169
|
for r in raw:
|
|
89
|
-
|
|
170
|
+
if not isinstance(r, dict):
|
|
171
|
+
logger.warning(
|
|
172
|
+
"web_search skipped a result: the provider returned a %s "
|
|
173
|
+
"where a row was expected.", type(r).__name__)
|
|
174
|
+
continue
|
|
175
|
+
|
|
176
|
+
url, withheld = third.url(r.get("href"))
|
|
177
|
+
if withheld:
|
|
178
|
+
# NOT SILENT (#49). The length is the fact; the URL is not
|
|
179
|
+
# echoed, because a URL is one of the things the redactor is
|
|
180
|
+
# looking for userinfo inside.
|
|
181
|
+
logger.warning(
|
|
182
|
+
"web_search dropped a result: its URL is longer than the "
|
|
183
|
+
"%d characters fetch_url accepts, so it is a route this "
|
|
184
|
+
"harness would refuse to take.", MAX_URL_CHARS)
|
|
185
|
+
if url is None:
|
|
186
|
+
# A result is a (title, url, snippet) triple whose url is how
|
|
187
|
+
# the model reaches it. With the url gone there is nothing to
|
|
188
|
+
# cite and nothing to fetch, so this is the same call the
|
|
189
|
+
# policy filter below already makes -- and it is the call
|
|
190
|
+
# `_parse_atom_feed` makes for an entry with no id.
|
|
191
|
+
continue
|
|
192
|
+
|
|
90
193
|
# `resolve=False` on purpose. This filters results; it does not
|
|
91
194
|
# fetch them, and a DNS lookup per hit is real latency for a check
|
|
92
195
|
# whose only failure mode is showing the model a URL that fetch_url
|
|
93
|
-
# will refuse anyway. An IP LITERAL is still checked
|
|
196
|
+
# will refuse anyway. An IP LITERAL is still checked, in every
|
|
197
|
+
# spelling the platform's resolver reads as a number -- a result
|
|
94
198
|
# pointing straight at 169.254.169.254 is dropped here rather than
|
|
95
199
|
# offered and then denied (#54).
|
|
200
|
+
#
|
|
201
|
+
# "EVERY SPELLING" SINCE BATCH 213 (#207, register item 53). Batch
|
|
202
|
+
# 156 narrowed this comment to dotted and bracketed literals,
|
|
203
|
+
# because `http://2130706433/`, `http://0x7f.0.0.1/` and
|
|
204
|
+
# `http://0x7F000001/` -- all 127.0.0.1 -- passed: `ipaddress`
|
|
205
|
+
# parses none of them. is_url_permitted now asks the resolver with
|
|
206
|
+
# AI_NUMERICHOST, which reads numbers and looks nothing up, so they
|
|
207
|
+
# are dropped here as fetch_url would refuse them.
|
|
208
|
+
#
|
|
209
|
+
# ABOVE THE POLICY CHECK AND BELOW THE BOUND, deliberately: the
|
|
210
|
+
# string checked here is the string the model is offered, so a
|
|
211
|
+
# redaction that rewrote the host cannot slip past the check that
|
|
212
|
+
# was run on the host before it.
|
|
96
213
|
if is_url_permitted(url, resolve=False):
|
|
97
214
|
continue
|
|
98
215
|
|
|
99
|
-
|
|
216
|
+
title, title_truncated = third.text(r.get("title"), MAX_TITLE_CHARS)
|
|
217
|
+
if title is None:
|
|
218
|
+
title = "(untitled)"
|
|
219
|
+
snippet, snippet_truncated = third.text(
|
|
220
|
+
r.get("body"), MAX_SNIPPET_CHARS)
|
|
221
|
+
if snippet is None:
|
|
222
|
+
snippet = ""
|
|
100
223
|
|
|
101
224
|
out.append(
|
|
102
225
|
SearchResult(
|
|
103
|
-
title=
|
|
226
|
+
title=title,
|
|
104
227
|
url=url,
|
|
105
228
|
snippet=snippet,
|
|
106
229
|
published=None,
|
|
230
|
+
snippet_truncated=snippet_truncated,
|
|
231
|
+
title_truncated=title_truncated,
|
|
107
232
|
)
|
|
108
233
|
)
|
|
234
|
+
third.report()
|
|
109
235
|
return out
|
|
110
236
|
|
|
111
237
|
|
|
238
|
+
def _kept(results: list, asked: int) -> list:
|
|
239
|
+
"""`results`, cut to the number the caller asked for (A62).
|
|
240
|
+
|
|
241
|
+
THE SCHEMA ALREADY PROMISED THIS and nothing enforced it.
|
|
242
|
+
`num_results` is advertised `le=10` and passed to the provider as
|
|
243
|
+
`max_results`, and a provider is free to ignore it -- measured (batch
|
|
244
|
+
156), a call asking for 5 returned every one of 5,000 rows it was
|
|
245
|
+
handed. So this is a documented bound being kept rather than a new
|
|
246
|
+
policy, and it is the LIST axis of the same question batch 156 asked
|
|
247
|
+
of each value: per-value caps multiplied by an unbounded row count are
|
|
248
|
+
not a bound.
|
|
249
|
+
|
|
250
|
+
`_call_ddgs` is where the finding wanted a byte ceiling, and it cannot
|
|
251
|
+
have one: the library buffers the response and owns the socket, so
|
|
252
|
+
nothing above it sees bytes. What this layer CAN bound is what it
|
|
253
|
+
keeps, which is the quantity that reaches the model.
|
|
254
|
+
|
|
255
|
+
NO FLAG, deliberately, where every other cut in this batch gets one.
|
|
256
|
+
Nothing is being withheld from the caller: it asked for `asked`
|
|
257
|
+
results and it is getting `asked` results. The over-delivery is a
|
|
258
|
+
provider fact rather than a truncation, so it goes to the log, where
|
|
259
|
+
the person debugging a provider can see it.
|
|
260
|
+
"""
|
|
261
|
+
if len(results) > asked:
|
|
262
|
+
logger.warning(
|
|
263
|
+
"web_search kept %d of %d results: the provider returned more "
|
|
264
|
+
"than the %d asked for.", asked, len(results), asked)
|
|
265
|
+
return results[:asked]
|
|
266
|
+
|
|
267
|
+
|
|
112
268
|
def run(params: dict) -> dict:
|
|
113
269
|
parsed = WebSearchParams(**params)
|
|
114
|
-
|
|
270
|
+
# §51 (PG9). `page` is part of the key for the reason `start` is on the
|
|
271
|
+
# arXiv side: it changes the response, so a key without it serves page 1
|
|
272
|
+
# to every request for page 2 and does it silently.
|
|
273
|
+
cache_key = f"{parsed.query}|{parsed.num_results}|{parsed.page}"
|
|
115
274
|
|
|
116
275
|
results = _cache.get(cache_key)
|
|
117
276
|
if results is not None:
|
|
@@ -121,8 +280,8 @@ def run(params: dict) -> dict:
|
|
|
121
280
|
results = []
|
|
122
281
|
for attempt in range(MAX_RETRIES + 1):
|
|
123
282
|
try:
|
|
124
|
-
raw = _call_ddgs(parsed.query, parsed.num_results)
|
|
125
|
-
results = _normalize(raw)
|
|
283
|
+
raw = _call_ddgs(parsed.query, parsed.num_results, parsed.page)
|
|
284
|
+
results = _kept(_normalize(raw), parsed.num_results)
|
|
126
285
|
_cache.set(cache_key, results)
|
|
127
286
|
break
|
|
128
287
|
except Exception as e: # Simpler to try again then elaborate on every error type
|
|
@@ -143,9 +302,28 @@ def run(params: dict) -> dict:
|
|
|
143
302
|
}
|
|
144
303
|
|
|
145
304
|
if not results:
|
|
305
|
+
if parsed.page > 1:
|
|
306
|
+
return {
|
|
307
|
+
"results": [], "result_count": 0, "page": parsed.page,
|
|
308
|
+
"message": (
|
|
309
|
+
f"No results on page {parsed.page}. The provider "
|
|
310
|
+
f"returned nothing further for this query."
|
|
311
|
+
),
|
|
312
|
+
}
|
|
146
313
|
return {"results": [], "result_count": 0, "message": "No results found."}
|
|
147
314
|
|
|
148
|
-
|
|
315
|
+
out = {
|
|
149
316
|
"results": [r.model_dump() for r in results],
|
|
150
317
|
"result_count": len(results),
|
|
151
|
-
|
|
318
|
+
"page": parsed.page,
|
|
319
|
+
}
|
|
320
|
+
# PG4. DuckDuckGo reports no total, so the honest message names the next
|
|
321
|
+
# page without claiming how many there are -- and says the pages overlap,
|
|
322
|
+
# because measured they do. A full page is the only signal that more may
|
|
323
|
+
# exist; a short one is where the provider stopped.
|
|
324
|
+
if len(results) >= parsed.num_results:
|
|
325
|
+
out["message"] = (
|
|
326
|
+
f"Page {parsed.page}. Use page={parsed.page + 1} for more "
|
|
327
|
+
f"results; pages may overlap by a result or two."
|
|
328
|
+
)
|
|
329
|
+
return out
|
package/tools/context.py
CHANGED
|
@@ -1,136 +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
|
-
|
|
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
|
-
|
|
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
|