@yahyahammad/venastine 0.1.0
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 +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- package/tui/widgets.py +1239 -0
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/todo.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §23 slice 2: the todo list. "A model-maintained checklist,
|
|
5
|
+
persisted per thread."
|
|
6
|
+
|
|
7
|
+
WHOLE-LIST WRITE, NOT GRANULAR OPERATIONS (J13). One call replaces the list,
|
|
8
|
+
so it is always internally consistent, reordering is free, and no item is
|
|
9
|
+
ever addressed by name or index. Granular add/complete/remove would each need
|
|
10
|
+
a stable way to name one item -- which is the problem `clear_refs` refused to
|
|
11
|
+
solve ("a per-reference removal needs a stable way for a person to name one")
|
|
12
|
+
and the problem §21b's "removal is by id, never by substring" rule exists to
|
|
13
|
+
prevent. A model naming the wrong id silently mutates the wrong entry; a model
|
|
14
|
+
rewriting the list cannot.
|
|
15
|
+
|
|
16
|
+
STORED IN extra_data (J14), under its own key beside §18's goal and §21c's
|
|
17
|
+
refs. storage.py's `get_thread_extra` docstring has said "goal mode §18, todo
|
|
18
|
+
list §23" since §18, and §27's column-versus-extra_data argument was about
|
|
19
|
+
keeping `list_threads()` cheap -- a todo list is only ever read for the
|
|
20
|
+
current thread, so queryability buys nothing.
|
|
21
|
+
|
|
22
|
+
WORKS HEADLESS (J9). §23 AC2 says "both tools deny cleanly with no way to ask",
|
|
23
|
+
but that was written before this tool's shape was settled: the deny rule
|
|
24
|
+
exists because a blocking prompt nobody answers turns into a hang, and this
|
|
25
|
+
tool never blocks and never asks anyone anything. A ten-pass research run
|
|
26
|
+
keeping its own checklist is arguably where one helps most. It needs a
|
|
27
|
+
conversation, not a person.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
import config
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
TOOL_SCHEMA = {
|
|
34
|
+
"name": "todo_write",
|
|
35
|
+
"description": (
|
|
36
|
+
"Record or update your checklist for this conversation. Pass the "
|
|
37
|
+
"WHOLE list every time -- it replaces what was there, so include "
|
|
38
|
+
"the items that have not changed. Use it for multi-step work the "
|
|
39
|
+
"user can then see the shape of: plan the steps up front, mark one "
|
|
40
|
+
"in_progress while you do it, and mark it completed before starting "
|
|
41
|
+
"the next. Do not use it for single-step requests, where the list "
|
|
42
|
+
"is noise."
|
|
43
|
+
),
|
|
44
|
+
"input_schema": {
|
|
45
|
+
"type": "object",
|
|
46
|
+
"properties": {
|
|
47
|
+
"items": {
|
|
48
|
+
"type": "array",
|
|
49
|
+
"description": f"The complete list, in order, at most "
|
|
50
|
+
f"{config.MAX_TODO_ITEMS} items. An empty "
|
|
51
|
+
f"list clears it.",
|
|
52
|
+
"items": {
|
|
53
|
+
"type": "object",
|
|
54
|
+
"properties": {
|
|
55
|
+
"content": {
|
|
56
|
+
"type": "string",
|
|
57
|
+
"description": "What the step is, imperative and "
|
|
58
|
+
"short.",
|
|
59
|
+
},
|
|
60
|
+
"status": {
|
|
61
|
+
"type": "string",
|
|
62
|
+
"enum": list(config.TODO_STATUSES),
|
|
63
|
+
"description": "Defaults to pending.",
|
|
64
|
+
},
|
|
65
|
+
},
|
|
66
|
+
"required": ["content"],
|
|
67
|
+
},
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
"required": ["items"],
|
|
71
|
+
},
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _normalise(raw) -> tuple:
|
|
76
|
+
"""Validate one list. Returns (items, error) -- exactly one is truthy.
|
|
77
|
+
|
|
78
|
+
Every failure is an error result the model can correct, never an
|
|
79
|
+
exception: a bare KeyError or TypeError here escapes the loop's
|
|
80
|
+
ToolCallDenied handler and takes down the whole turn. pin.py's rule.
|
|
81
|
+
"""
|
|
82
|
+
if not isinstance(raw, (list, tuple)):
|
|
83
|
+
return None, ("todo_write requires 'items' to be a list of "
|
|
84
|
+
"{content, status} objects.")
|
|
85
|
+
if len(raw) > config.MAX_TODO_ITEMS:
|
|
86
|
+
# REFUSED, not truncated. A list silently cut would leave the model
|
|
87
|
+
# believing it had recorded work it can no longer see.
|
|
88
|
+
return None, (f"todo_write allows at most {config.MAX_TODO_ITEMS} "
|
|
89
|
+
f"items; {len(raw)} were given. Keep the list to the "
|
|
90
|
+
f"work actually in hand.")
|
|
91
|
+
|
|
92
|
+
items = []
|
|
93
|
+
for index, entry in enumerate(raw, start=1):
|
|
94
|
+
if not isinstance(entry, dict):
|
|
95
|
+
return None, (f"todo_write item {index} is not an object with a "
|
|
96
|
+
f"'content' field.")
|
|
97
|
+
content = entry.get("content")
|
|
98
|
+
if not content or not isinstance(content, str):
|
|
99
|
+
return None, (f"todo_write item {index} needs a non-empty "
|
|
100
|
+
f"'content' string.")
|
|
101
|
+
status = entry.get("status") or "pending"
|
|
102
|
+
if status not in config.TODO_STATUSES:
|
|
103
|
+
# Names the offender and the vocabulary. A silent coercion to
|
|
104
|
+
# pending would report success while losing the state the model
|
|
105
|
+
# meant to record.
|
|
106
|
+
return None, (
|
|
107
|
+
f"todo_write item {index} has status {status!r}; expected one "
|
|
108
|
+
f"of {', '.join(config.TODO_STATUSES)}.")
|
|
109
|
+
items.append({"content": content.strip(), "status": status})
|
|
110
|
+
return items, None
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _summary(items: list) -> str:
|
|
114
|
+
"""One line, for the transcript and for the CLI, which has no panel."""
|
|
115
|
+
if not items:
|
|
116
|
+
return "todo list cleared"
|
|
117
|
+
done = sum(1 for i in items if i["status"] == "completed")
|
|
118
|
+
active = next((i["content"] for i in items
|
|
119
|
+
if i["status"] == "in_progress"), None)
|
|
120
|
+
head = f"todo {done}/{len(items)}"
|
|
121
|
+
return f"{head} — {active}" if active else head
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def run(params: dict, memory=None) -> dict:
|
|
125
|
+
items, error = _normalise(params.get("items"))
|
|
126
|
+
if error:
|
|
127
|
+
return {"error": error}
|
|
128
|
+
if memory is None:
|
|
129
|
+
# Reachable only if dispatched outside a run. An explained error
|
|
130
|
+
# rather than a silent no-op reported as success: the model would
|
|
131
|
+
# otherwise believe a plan is recorded when nothing is, which is
|
|
132
|
+
# worse than not having the tool. pin.py's reasoning.
|
|
133
|
+
return {"error": "todo_write is only available inside a conversation."}
|
|
134
|
+
|
|
135
|
+
# THE WHOLE LIST, through set_extra, which persists write-through. Not
|
|
136
|
+
# `memory.extra[...] = ...`: `extra` is a COPY (core/memory.py), so
|
|
137
|
+
# mutating it changes nothing and reports success.
|
|
138
|
+
memory.set_extra("todos", items)
|
|
139
|
+
|
|
140
|
+
return {
|
|
141
|
+
"result": {"items": items},
|
|
142
|
+
# §23 slice 2's event route (J10). The loop forwards any `notice` on
|
|
143
|
+
# a tool result as a LoopEvent and strips it, so this reaches the TUI
|
|
144
|
+
# panel without a tool name appearing in core/loop.py. The panel
|
|
145
|
+
# re-reads the list from thread state -- this only says WHEN.
|
|
146
|
+
"notice": {"kind": "todo_changed", "text": _summary(items)},
|
|
147
|
+
}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Web search tool for the agent harness, using DuckDuckGo exclusively via the
|
|
3
|
+
`ddgs` package.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import logging
|
|
9
|
+
from typing import Optional
|
|
10
|
+
|
|
11
|
+
from pydantic import BaseModel, Field, field_validator
|
|
12
|
+
from ddgs import DDGS
|
|
13
|
+
|
|
14
|
+
from safety.policy_enforcement import is_url_permitted
|
|
15
|
+
from tools.builtin._net_common import TTLCache
|
|
16
|
+
|
|
17
|
+
logger = logging.getLogger(__name__)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
# ---- Schema exposed to the LLM -------------------------------------------
|
|
21
|
+
|
|
22
|
+
class WebSearchParams(BaseModel):
|
|
23
|
+
query: str = Field(..., description="Search query", min_length=1, max_length=400)
|
|
24
|
+
num_results: int = Field(5, ge=1, le=10, description="Number of results to return")
|
|
25
|
+
|
|
26
|
+
@field_validator("query")
|
|
27
|
+
@classmethod
|
|
28
|
+
def strip_query(cls, value: str) -> str:
|
|
29
|
+
value = value.strip()
|
|
30
|
+
if not value:
|
|
31
|
+
raise ValueError("query cannot be empty")
|
|
32
|
+
return value
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
TOOL_SCHEMA = {
|
|
36
|
+
"name": "web_search",
|
|
37
|
+
"description": (
|
|
38
|
+
"Search the web for current information. Use this for facts that may "
|
|
39
|
+
"have changed recently, current events, or anything you're not "
|
|
40
|
+
"fully confident about."
|
|
41
|
+
),
|
|
42
|
+
"input_schema": WebSearchParams.model_json_schema(),
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
# ---- Normalized result shape ---------------------------------------------
|
|
47
|
+
|
|
48
|
+
class SearchResult(BaseModel):
|
|
49
|
+
title: str
|
|
50
|
+
url: str
|
|
51
|
+
snippet: str
|
|
52
|
+
published: Optional[str] = None # ddgs's text search doesn't return a
|
|
53
|
+
# publish date, so this stays None here
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class WebSearchError(Exception):
|
|
57
|
+
"""No longer raised by this module -- exhausted retries return an
|
|
58
|
+
error dict instead, so a transient search outage cannot fail a
|
|
59
|
+
ten-pass research run. Kept as part of this module's public surface."""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
# ---- Policy / tuning knobs -------------------------------------------------
|
|
63
|
+
|
|
64
|
+
MAX_SNIPPET_CHARS = 300
|
|
65
|
+
REQUEST_TIMEOUT_S = 8.0
|
|
66
|
+
MAX_RETRIES = 2
|
|
67
|
+
CACHE_TTL_S = 300
|
|
68
|
+
|
|
69
|
+
# One instance per tool, never shared: an equal key string from an
|
|
70
|
+
# arXiv query and a web query would otherwise collide.
|
|
71
|
+
_cache = TTLCache(CACHE_TTL_S)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
# ---- Provider call ----------------------------------------------------------
|
|
75
|
+
|
|
76
|
+
def _call_ddgs(query: str, num_results: int) -> list[dict]:
|
|
77
|
+
"""
|
|
78
|
+
The one function that actually talks to DuckDuckGo. DDGS() is
|
|
79
|
+
instantiated fresh per call (cheap) and used as a context manager so
|
|
80
|
+
its underlying HTTP session gets cleaned up automatically afterward.
|
|
81
|
+
"""
|
|
82
|
+
with DDGS(timeout=REQUEST_TIMEOUT_S) as ddgs_client:
|
|
83
|
+
return ddgs_client.text(query, max_results=num_results)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def _normalize(raw: list[dict]) -> list[SearchResult]:
|
|
87
|
+
out: list[SearchResult] = []
|
|
88
|
+
for r in raw:
|
|
89
|
+
url = r.get("href", "")
|
|
90
|
+
# `resolve=False` on purpose. This filters results; it does not
|
|
91
|
+
# fetch them, and a DNS lookup per hit is real latency for a check
|
|
92
|
+
# whose only failure mode is showing the model a URL that fetch_url
|
|
93
|
+
# will refuse anyway. An IP LITERAL is still checked -- a result
|
|
94
|
+
# pointing straight at 169.254.169.254 is dropped here rather than
|
|
95
|
+
# offered and then denied (#54).
|
|
96
|
+
if is_url_permitted(url, resolve=False):
|
|
97
|
+
continue
|
|
98
|
+
|
|
99
|
+
snippet = (r.get("body") or "")[:MAX_SNIPPET_CHARS]
|
|
100
|
+
|
|
101
|
+
out.append(
|
|
102
|
+
SearchResult(
|
|
103
|
+
title=r.get("title", "(untitled)"),
|
|
104
|
+
url=url,
|
|
105
|
+
snippet=snippet,
|
|
106
|
+
published=None,
|
|
107
|
+
)
|
|
108
|
+
)
|
|
109
|
+
return out
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def run(params: dict) -> dict:
|
|
113
|
+
parsed = WebSearchParams(**params)
|
|
114
|
+
cache_key = f"{parsed.query}|{parsed.num_results}"
|
|
115
|
+
|
|
116
|
+
results = _cache.get(cache_key)
|
|
117
|
+
if results is not None:
|
|
118
|
+
logger.info("web_search cache hit for %r", parsed.query)
|
|
119
|
+
else:
|
|
120
|
+
last_exc: Optional[Exception] = None
|
|
121
|
+
results = []
|
|
122
|
+
for attempt in range(MAX_RETRIES + 1):
|
|
123
|
+
try:
|
|
124
|
+
raw = _call_ddgs(parsed.query, parsed.num_results)
|
|
125
|
+
results = _normalize(raw)
|
|
126
|
+
_cache.set(cache_key, results)
|
|
127
|
+
break
|
|
128
|
+
except Exception as e: # Simpler to try again then elaborate on every error type
|
|
129
|
+
last_exc = e
|
|
130
|
+
logger.warning(
|
|
131
|
+
"web_search attempt %s/%s failed for %r: %s",
|
|
132
|
+
attempt + 1, MAX_RETRIES + 1, parsed.query, e)
|
|
133
|
+
else:
|
|
134
|
+
# RETURNED, not raised -- same change and same reason as
|
|
135
|
+
# arxiv_search. A search provider being unreachable is a
|
|
136
|
+
# result the model can work around; raising made one
|
|
137
|
+
# transient failure in one pass fail a whole ten-pass
|
|
138
|
+
# research run. fetch_url was already the odd one out for
|
|
139
|
+
# doing this correctly.
|
|
140
|
+
return {
|
|
141
|
+
"error": f"search failed after {MAX_RETRIES + 1} "
|
|
142
|
+
f"attempts: {last_exc}"
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
if not results:
|
|
146
|
+
return {"results": [], "result_count": 0, "message": "No results found."}
|
|
147
|
+
|
|
148
|
+
return {
|
|
149
|
+
"results": [r.model_dump() for r in results],
|
|
150
|
+
"result_count": len(results),
|
|
151
|
+
}
|
package/tools/context.py
ADDED
|
@@ -0,0 +1,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
|
+
"""
|
|
36
|
+
|
|
37
|
+
allowed_tools: Optional[set[str]] = None
|
|
38
|
+
approval_overrides: dict[str, bool] = field(default_factory=dict)
|
|
39
|
+
subagent_depth: int = 0
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@dataclass
|
|
43
|
+
class RunInfo:
|
|
44
|
+
"""Identity of the enclosing run, for context-aware tool handlers that
|
|
45
|
+
spawn further runs (§18's spawn_subagent inherits model / provider /
|
|
46
|
+
effort when the agent definition names none of its own).
|
|
47
|
+
|
|
48
|
+
Carries no policy -- deliberately separate from ToolContext so a
|
|
49
|
+
handler's signature cannot confuse inheritance with restriction.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
model: str
|
|
53
|
+
provider_name: str
|
|
54
|
+
effort: Optional[str] = None
|
|
55
|
+
# Tools already signed off for the rest of THIS run (§18 subagent
|
|
56
|
+
# sign-off, S1). A RunInfo is built once per _run() call and _run() is
|
|
57
|
+
# called once per turn, so run-scope is turn-scope -- which is the
|
|
58
|
+
# granularity the sign-off was specified at: approving a spawn covers
|
|
59
|
+
# every subagent in that turn, including nested ones, and nothing
|
|
60
|
+
# beyond it.
|
|
61
|
+
#
|
|
62
|
+
# A GRANT, not a policy override. It records that the user answered
|
|
63
|
+
# the approval question early, exactly as an approval_callback
|
|
64
|
+
# returning True does; it is deliberately not an approval_overrides
|
|
65
|
+
# entry, because those OR and can therefore only ever tighten (D14).
|
|
66
|
+
granted_tools: set = field(default_factory=set)
|
|
67
|
+
# §25: the ceiling on how many granted calls may proceed without being
|
|
68
|
+
# asked about. A core.approval.GrantBudget, or None for no ceiling.
|
|
69
|
+
#
|
|
70
|
+
# Typed as object so this module stays a leaf with no project imports
|
|
71
|
+
# (see the module docstring) -- the same reason ToolContext is
|
|
72
|
+
# type-hinted from security/permissions.py under TYPE_CHECKING only.
|
|
73
|
+
# One budget instance is SHARED by every pass of a pipeline run; a
|
|
74
|
+
# per-pass budget would multiply the ceiling by the pass count while
|
|
75
|
+
# reading as if it enforced one.
|
|
76
|
+
grant_budget: Optional[object] = None
|
|
77
|
+
# ROADMAP_v2 §23 (AC1b). Sign-off answers already given in this run,
|
|
78
|
+
# keyed by (tool name, SUBJECT). A subject is whatever the question was
|
|
79
|
+
# about -- for spawn_subagent, the agent's name -- and is None for every
|
|
80
|
+
# tool whose approval is a plain yes/no.
|
|
81
|
+
#
|
|
82
|
+
# Separate from granted_tools because the two carry different things: a
|
|
83
|
+
# granted TOOL is a name approved with no further detail, while a
|
|
84
|
+
# sign-off carries the SUBSET the child may use. Merging them would
|
|
85
|
+
# force a set to hold both a name and a name-plus-subset.
|
|
86
|
+
signoffs: dict = field(default_factory=dict)
|
|
87
|
+
|
|
88
|
+
def remember_signoff(self, tool_name: str, subject, subset) -> None:
|
|
89
|
+
"""Record an answer so the rest of this run need not re-ask.
|
|
90
|
+
|
|
91
|
+
A subset of None means the answer carried no detail -- a plain
|
|
92
|
+
approval -- and lands in granted_tools exactly as it did before
|
|
93
|
+
§23. Anything else is keyed by subject, because the answer was
|
|
94
|
+
about that subject and means nothing for another one.
|
|
95
|
+
"""
|
|
96
|
+
if subset is None:
|
|
97
|
+
self.granted_tools.add(tool_name)
|
|
98
|
+
else:
|
|
99
|
+
self.signoffs[(tool_name, subject)] = set(subset)
|
|
100
|
+
|
|
101
|
+
def recall_signoff(self, tool_name: str, subject) -> tuple:
|
|
102
|
+
"""(remembered, subset) for a call this run may already have
|
|
103
|
+
answered.
|
|
104
|
+
|
|
105
|
+
The subject-keyed memo is checked FIRST. A tool can appear in both
|
|
106
|
+
(a pipeline grant names it, and a sign-off answered about one
|
|
107
|
+
subject), and the specific answer is the one the user actually
|
|
108
|
+
gave about this subject.
|
|
109
|
+
|
|
110
|
+
R14: a grant BY NAME may not answer a question that carries a
|
|
111
|
+
SUBJECT. J8 rebuilt the memo around (tool, subject) because
|
|
112
|
+
approving a spawn of agent `a` had silently covered a later spawn
|
|
113
|
+
of `b`; the grant branch below kept answering both, because it
|
|
114
|
+
never looked at the subject at all:
|
|
115
|
+
|
|
116
|
+
granted_tools={'spawn_subagent'}
|
|
117
|
+
recall_signoff('spawn_subagent', 'agent-a') -> (True, None)
|
|
118
|
+
recall_signoff('spawn_subagent', 'agent-b') -> (True, None)
|
|
119
|
+
recall_signoff('spawn_subagent', <anything>) -> (True, None)
|
|
120
|
+
|
|
121
|
+
-- J8's pre-fix behaviour, reached through the grant rather than
|
|
122
|
+
the memo. A name-level answer is about the TOOL; a subject-carrying
|
|
123
|
+
question is about one agent, and the two are not the same consent.
|
|
124
|
+
|
|
125
|
+
Belt and braces after R13 made spawn_subagent GRANT_NEVER, since
|
|
126
|
+
that is the only tool supplying a subject today: this holds for a
|
|
127
|
+
hand-built or stale RunInfo, and for any later tool that carries
|
|
128
|
+
one. `subject is None` for every other tool, so nothing else
|
|
129
|
+
changes behaviour.
|
|
130
|
+
"""
|
|
131
|
+
key = (tool_name, subject)
|
|
132
|
+
if key in self.signoffs:
|
|
133
|
+
return True, self.signoffs[key]
|
|
134
|
+
if subject is None and tool_name in self.granted_tools:
|
|
135
|
+
return True, None
|
|
136
|
+
return False, None
|