@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.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,61 @@
1
+ """
2
+ tools/builtin/_net_common.py
3
+
4
+ What the two network-backed search tools share. `_math_common.py`'s
5
+ precedent, one directory over: a private module the built-in tools import
6
+ from, never registered and never advertised.
7
+
8
+ TODAY THAT IS ONE THING: the in-process response cache. `web_search.py` and
9
+ `arxiv.py` each carried a `_cache_get` / `_cache_set` pair that was
10
+ identical apart from the type of the value being stored, plus a
11
+ `CACHE_TTL_S = 300` each, plus a bare dict each. Three copies of an expiry
12
+ rule is how one of them comes to be measured in minutes.
13
+
14
+ WHAT IS DELIBERATELY *NOT* SHARED. Each tool keeps its OWN instance, so the
15
+ two key spaces stay separate -- a `TTLCache` shared between them would let
16
+ an arXiv query and a web query collide on an equal key string, which is a
17
+ correctness bug rather than a tidiness one. Their `@field_validator`s
18
+ (`strip_keywords`, `strip_query`) are also left alone: they are three lines
19
+ each, they differ in the message the model is shown, and folding them into
20
+ a factory would make the params class harder to read to save two lines.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import time
26
+ from typing import Any, Optional
27
+
28
+
29
+ class TTLCache:
30
+ """A tiny time-boxed cache, keyed by whatever string a caller builds.
31
+
32
+ Expiry is checked on READ rather than swept: these caches hold a
33
+ handful of entries for the length of a research run, so a sweep would
34
+ be machinery for a problem neither tool has.
35
+
36
+ A stale entry is dropped as it is read, which is what makes a repeated
37
+ query after the TTL a real request again rather than a permanent miss
38
+ against a growing dict.
39
+ """
40
+
41
+ def __init__(self, ttl_s: float) -> None:
42
+ self.ttl_s = ttl_s
43
+ self._entries: dict[str, tuple[float, Any]] = {}
44
+
45
+ def get(self, key: str) -> Optional[Any]:
46
+ entry = self._entries.get(key)
47
+ if not entry:
48
+ return None
49
+ stored_at, value = entry
50
+ if time.time() - stored_at > self.ttl_s:
51
+ self._entries.pop(key, None)
52
+ return None
53
+ return value
54
+
55
+ def set(self, key: str, value: Any) -> None:
56
+ self._entries[key] = (time.time(), value)
57
+
58
+ def clear(self) -> None:
59
+ """Drop everything. For tests, which must not inherit a previous
60
+ test's answers -- the same reason conftest isolates the stores."""
61
+ self._entries.clear()
@@ -0,0 +1,223 @@
1
+ """
2
+ tools/builtin/arxiv.py
3
+
4
+ Searches arXiv for academic papers by keyword and optional subject
5
+ category, using arXiv's public query API. No API key needed. Useful
6
+ alongside web_search/fetch_url for grounding claims in published research
7
+ during the source_grounding pass.
8
+
9
+ The arXiv API returns Atom 1.0 XML (not JSON) -- this file's job is
10
+ largely translating that into the same normalized result shape the other
11
+ tools use.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import logging
17
+ import xml.etree.ElementTree as ET
18
+ from typing import Optional
19
+
20
+ import httpx
21
+ from pydantic import BaseModel, Field, field_validator
22
+
23
+ from tools.builtin._net_common import TTLCache
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+ # HTTPS, and it is load-bearing. arXiv 301-redirects the http:// form, and
28
+ # three things then combine into a hard failure that looks nothing like a
29
+ # redirect: httpx does NOT follow redirects by default (unlike requests),
30
+ # raise_for_status() only raises on >= 400 so a 301 sails through, and the
31
+ # redirect body is empty -- so ET.fromstring("") raises ParseError, the
32
+ # retry loop runs three identical attempts, and the tool reports "arXiv
33
+ # search failed after 3 attempts". Verified against the live API.
34
+ ARXIV_API_URL = "https://export.arxiv.org/api/query"
35
+ ATOM_NS = {"atom": "http://www.w3.org/2005/Atom"}
36
+
37
+ _VALID_SORT_BY = {"relevance", "lastUpdatedDate", "submittedDate"}
38
+
39
+ MAX_SUMMARY_CHARS = 600
40
+ REQUEST_TIMEOUT_S = 10.0
41
+ MAX_RETRIES = 2
42
+ CACHE_TTL_S = 300
43
+
44
+ # One instance per tool, never shared: an equal key string from an
45
+ # arXiv query and a web query would otherwise collide.
46
+ _cache = TTLCache(CACHE_TTL_S)
47
+
48
+
49
+ # ---- Schema exposed to the LLM -------------------------------------------
50
+
51
+ class ArxivSearchParams(BaseModel):
52
+ keywords: str = Field(..., description="Search keywords", min_length=1, max_length=400)
53
+ category: Optional[str] = Field(
54
+ None,
55
+ description=(
56
+ "Optional arXiv category code to restrict the search, e.g. "
57
+ "'cs.AI', 'cs.LG', 'physics.gen-ph', 'q-bio.NC'. Omit to search "
58
+ "all categories."
59
+ ),
60
+ )
61
+ max_results: int = Field(5, ge=1, le=20, description="Number of results to return")
62
+ sort_by: str = Field(
63
+ "relevance",
64
+ description="How to sort results: 'relevance', 'lastUpdatedDate', or 'submittedDate'",
65
+ )
66
+
67
+ @field_validator("keywords")
68
+ @classmethod
69
+ def strip_keywords(cls, value: str) -> str:
70
+ value = value.strip()
71
+ if not value:
72
+ raise ValueError("keywords cannot be empty")
73
+ return value
74
+
75
+ @field_validator("sort_by")
76
+ @classmethod
77
+ def validate_sort_by(cls, value: str) -> str:
78
+ if value not in _VALID_SORT_BY:
79
+ raise ValueError(f"sort_by must be one of {_VALID_SORT_BY}")
80
+ return value
81
+
82
+
83
+ TOOL_SCHEMA = {
84
+ "name": "arxiv_search",
85
+ "description": (
86
+ "Search arXiv for academic papers by keyword and optional subject "
87
+ "category. Returns titles, authors, abstracts, publish dates, and "
88
+ "PDF links -- use this to ground claims in published research."
89
+ ),
90
+ "input_schema": ArxivSearchParams.model_json_schema(),
91
+ }
92
+
93
+
94
+ class ArxivSearchError(Exception):
95
+ """No longer raised by this module -- exhausted retries return an
96
+ error dict instead, so a transient network failure cannot fail a
97
+ ten-pass research run. Kept because it is part of this module's
98
+ public surface and something outside the repo may catch it."""
99
+
100
+
101
+ # ---- Query construction -----------------------------------------------------
102
+
103
+ def _build_search_query(keywords: str, category: Optional[str]) -> str:
104
+ """
105
+ arXiv's query syntax uses field prefixes (ti:, abs:, au:, cat:, all:)
106
+ combined with AND/OR/ANDNOT. `all:` searches title, abstract, and
107
+ author. httpx handles URL-encoding the spaces/quotes once this string
108
+ is passed as a params value, so no manual encoding is needed here.
109
+ """
110
+ if category:
111
+ return f"cat:{category} AND all:{keywords}"
112
+ return f"all:{keywords}"
113
+
114
+
115
+ # ---- Provider call ----------------------------------------------------------
116
+
117
+ def _call_arxiv_api(search_query: str, max_results: int, sort_by: str) -> str:
118
+ response = httpx.get(
119
+ ARXIV_API_URL,
120
+ params={
121
+ "search_query": search_query,
122
+ "start": 0,
123
+ "max_results": max_results,
124
+ "sortBy": sort_by,
125
+ "sortOrder": "descending",
126
+ },
127
+ headers={"User-Agent": "agent-harness-arxiv-tool/1.0 (research pipeline)"},
128
+ timeout=REQUEST_TIMEOUT_S,
129
+ # Belt and braces beside the https:// above. If arXiv moves the
130
+ # endpoint again, following the redirect keeps this working
131
+ # instead of failing as an unparseable empty body.
132
+ follow_redirects=True,
133
+ )
134
+ response.raise_for_status()
135
+ return response.text # raw Atom XML
136
+
137
+
138
+ # ---- Atom XML parsing --------------------------------------------------
139
+
140
+ def _parse_atom_feed(xml_text: str) -> list[dict]:
141
+ root = ET.fromstring(xml_text)
142
+ entries = root.findall("atom:entry", ATOM_NS)
143
+
144
+ results = []
145
+ for entry in entries:
146
+ raw_id = entry.find("atom:id", ATOM_NS).text.strip()
147
+ arxiv_id = raw_id.split("/abs/")[-1] if "/abs/" in raw_id else raw_id
148
+
149
+ title = entry.find("atom:title", ATOM_NS).text.strip().replace("\n", " ")
150
+ summary_el = entry.find("atom:summary", ATOM_NS)
151
+ summary = (summary_el.text or "").strip().replace("\n", " ")[:MAX_SUMMARY_CHARS]
152
+
153
+ published_el = entry.find("atom:published", ATOM_NS)
154
+ published = published_el.text[:10] if published_el is not None else None
155
+
156
+ authors = [
157
+ a.find("atom:name", ATOM_NS).text
158
+ for a in entry.findall("atom:author", ATOM_NS)
159
+ ]
160
+ categories = [c.get("term") for c in entry.findall("atom:category", ATOM_NS)]
161
+
162
+ pdf_url = None
163
+ for link in entry.findall("atom:link", ATOM_NS):
164
+ if link.get("title") == "pdf":
165
+ pdf_url = link.get("href")
166
+
167
+ results.append({
168
+ "arxiv_id": arxiv_id,
169
+ "title": title,
170
+ "authors": authors,
171
+ "summary": summary,
172
+ "published": published,
173
+ "categories": categories,
174
+ "pdf_url": pdf_url,
175
+ })
176
+
177
+ return results
178
+
179
+
180
+ # ---- Entry point called by the tool dispatcher -----------------------------
181
+
182
+ def run(params: dict) -> dict:
183
+ parsed = ArxivSearchParams(**params)
184
+ cache_key = f"{parsed.keywords}|{parsed.category}|{parsed.max_results}|{parsed.sort_by}"
185
+
186
+ results = _cache.get(cache_key)
187
+ if results is not None:
188
+ logger.info("arxiv_search cache hit for %r", parsed.keywords)
189
+ else:
190
+ search_query = _build_search_query(parsed.keywords, parsed.category)
191
+ last_exc: Optional[Exception] = None
192
+ results = []
193
+ for attempt in range(MAX_RETRIES + 1):
194
+ try:
195
+ xml_text = _call_arxiv_api(search_query, parsed.max_results, parsed.sort_by)
196
+ results = _parse_atom_feed(xml_text)
197
+ _cache.set(cache_key, results)
198
+ break
199
+ except (httpx.HTTPError, ET.ParseError) as e:
200
+ last_exc = e
201
+ logger.warning(
202
+ "arxiv_search attempt %s/%s failed for %r: %s",
203
+ attempt + 1, MAX_RETRIES + 1, parsed.keywords, e)
204
+ else:
205
+ # RETURNED, not raised. A search tool that cannot reach its
206
+ # provider is a result the model can work around -- try
207
+ # web_search, or say the claim could not be grounded. Raising
208
+ # made one transient network failure, in one pass, fail an
209
+ # entire ten-pass research run; fetch_url has always returned
210
+ # an error dict here and arxiv_search was the outlier.
211
+ #
212
+ # dispatch() now contains a raise from any tool as well, so
213
+ # this is the message rather than the mechanism: the model
214
+ # gets something specific instead of a generic wrapper.
215
+ return {
216
+ "error": f"arXiv search failed after {MAX_RETRIES + 1} "
217
+ f"attempts: {last_exc}"
218
+ }
219
+
220
+ if not results:
221
+ return {"results": [], "result_count": 0, "message": "No papers found."}
222
+
223
+ return {"results": results, "result_count": len(results)}
@@ -0,0 +1,213 @@
1
+ """
2
+ tools/builtin/ask_user.py
3
+
4
+ ROADMAP_v2 §23 slice 2: the question tool. "Up to 4 options, multi-select, a
5
+ write-your-own answer, and a 'chat about this' escape that returns control to
6
+ the conversation instead of forcing a choice."
7
+
8
+ IT ASKS THROUGH THE INJECTED CHANNEL, NOT THROUGH THE APPROVAL BRIDGE. The
9
+ loop's `_obtain_approval` fires only under `if needs_approval:`, builds a
10
+ payload of {"tool_name", "params"}, and coerces the answer to (bool, grant) --
11
+ a free-text or multi-select answer has nowhere to go in it. It does not need
12
+ one: `response_channel` is already an injectable parameter, handed to every
13
+ handler that names it on BOTH dispatch branches, which is what
14
+ tools/registry.py's `_INJECTABLE_PARAMS` comment anticipated -- "generalised
15
+ so §23's response-channel tools add a third injectable name without reopening
16
+ dispatch()". So core/loop.py is untouched by this tool.
17
+
18
+ UNGATED, DELIBERATELY (J12). Requiring approval to ask a question would mean
19
+ approving a prompt in order to be shown a prompt -- and worse, §13 does not
20
+ merely deny a gated tool where nothing can ask, it stops ADVERTISING it. A
21
+ gated question tool would be invisible in every headless run rather than
22
+ denied with a reason, and §23 AC2 wants the opposite: the model must see the tool,
23
+ call it, and receive "there is nobody to ask" as something it can work around.
24
+ Same shape as `pin`'s ungating (D26), for the same reason.
25
+
26
+ NO CHANNEL MEANS DENIED, AND THE DENIAL EXPLAINS ITSELF (§23 AC2). An unattended
27
+ ten-pass pipeline is exactly where a blocking prompt nobody will answer turns
28
+ into a hang, and where a question injected by fetched web content would be
29
+ least noticed. An attended run carries a channel and can ask -- that is §25's
30
+ amendment, and it is why the condition tested here is "is there a channel"
31
+ rather than "is this the pipeline".
32
+ """
33
+
34
+ import logging
35
+
36
+ from core import interaction
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+ # The spec's cap, enforced rather than advisory. See run() for why a fifth
41
+ # option is an error and not a truncation.
42
+ MAX_OPTIONS = 4
43
+
44
+ #: Longest option the modal can show whole (batch 49). QuestionScreen is a
45
+ #: fixed 66 columns and an option button 58 of them, so 100 characters is
46
+ #: two wrapped lines for every shape measured -- prose, twenty-character
47
+ #: words, and an unbroken run -- and 105 is three for two of them. It is a
48
+ #: BUDGET, not a guess: the options region scrolls, so exceeding it costs
49
+ #: legibility rather than correctness, and the number is re-derivable by
50
+ #: the test that measures the drawn rows rather than trusting this
51
+ #: comment.
52
+ MAX_OPTION_CHARS = 100
53
+
54
+ TOOL_SCHEMA = {
55
+ "name": "ask_user",
56
+ "description": (
57
+ "Ask the user a question and wait for their answer. Use this when a "
58
+ "decision is genuinely theirs to make and getting it wrong would "
59
+ "waste work -- an ambiguous requirement, a choice between "
60
+ "approaches with different tradeoffs, a missing fact only they "
61
+ "have. Do NOT use it for things you can determine yourself, or to "
62
+ "confirm work you have already been asked to do. The user can pick "
63
+ "one or more of your options, write their own answer, or ask to "
64
+ "discuss it instead of choosing."
65
+ ),
66
+ "input_schema": {
67
+ "type": "object",
68
+ "properties": {
69
+ "question": {
70
+ "type": "string",
71
+ "description": "The question, in one or two sentences. State "
72
+ "what you need and why it changes what you "
73
+ "will do.",
74
+ },
75
+ "options": {
76
+ "type": "array",
77
+ "items": {"type": "string"},
78
+ "description": f"Up to {MAX_OPTIONS} concrete answers to "
79
+ f"choose from. Optional -- omit it to ask an "
80
+ f"open question. Each must be at most "
81
+ f"{MAX_OPTION_CHARS} characters, so it can be "
82
+ f"shown whole -- put the reasoning in the "
83
+ f"question, not in the options.",
84
+ },
85
+ "multi_select": {
86
+ "type": "boolean",
87
+ "description": "True if several options can be chosen "
88
+ "together. Defaults to false.",
89
+ },
90
+ "allow_text": {
91
+ "type": "boolean",
92
+ "description": "Whether the user may write their own answer "
93
+ "instead of picking. Defaults to true.",
94
+ },
95
+ },
96
+ "required": ["question"],
97
+ },
98
+ }
99
+
100
+
101
+ def run(params: dict, response_channel=None) -> dict:
102
+ # params.get throughout, never params[]: no provider validates tool
103
+ # inputs against the schema, and a bare KeyError escapes the loop's
104
+ # ToolCallDenied handler and takes down the whole turn. pin.py's rule.
105
+ question = params.get("question")
106
+ if not question or not isinstance(question, str):
107
+ return {"error": "ask_user requires a 'question' string."}
108
+
109
+ options = params.get("options") or []
110
+ if not isinstance(options, (list, tuple)):
111
+ return {"error": "ask_user requires 'options' to be a list of strings."}
112
+ options = [str(o) for o in options]
113
+
114
+ if len(options) > MAX_OPTIONS:
115
+ # AN ERROR, NOT A TRUNCATION. Silently dropping the fifth option
116
+ # would show the user a different question from the one the model
117
+ # asked, and the model would then read the answer as a response to
118
+ # the full list. M15's rule -- never silently drop something
119
+ # somebody named -- with the model in the naming role. An error it
120
+ # can correct costs one step; a mis-answered question costs the
121
+ # decision.
122
+ return {
123
+ "error": f"ask_user allows at most {MAX_OPTIONS} options; "
124
+ f"{len(options)} were given. Ask a narrower question, "
125
+ f"or drop the options and ask it openly.",
126
+ }
127
+
128
+ too_long = [o for o in options if len(o) > MAX_OPTION_CHARS]
129
+ if too_long:
130
+ # AN ERROR, NOT A TRUNCATION, for the reason directly above: an
131
+ # option shortened here is not the option the model offered, and
132
+ # the answer would come back as though it were. The modal used to
133
+ # truncate this way by accident -- an option wider than the dialog
134
+ # was CUT at its edge, so a user chose between two options whose
135
+ # visible halves were identical -- which is the failure this
136
+ # refusal exists to make impossible rather than merely unlikely.
137
+ longest = max(too_long, key=len)
138
+ return {
139
+ "error": f"ask_user allows at most {MAX_OPTION_CHARS} characters "
140
+ f"per option so it can be read whole; one is "
141
+ f"{len(longest)}. Shorten it to the choice itself and "
142
+ f"put the reasoning in the question: "
143
+ f"{longest[:60]!r}...",
144
+ }
145
+
146
+ if not options and params.get("allow_text", True) is False:
147
+ # #114, same family as the two refusals above: a question with no
148
+ # options and no text box renders as a modal whose only button is
149
+ # "Discuss instead", so a defer means "that was my only button"
150
+ # rather than "let's talk about it" -- collapsing exactly the
151
+ # distinction QuestionScreen's escape/defer pair exists to keep.
152
+ return {
153
+ "error": "ask_user needs something to answer with: give "
154
+ "options, or leave allow_text true so the user can "
155
+ "write a reply.",
156
+ }
157
+
158
+ if response_channel is None:
159
+ # §23 AC2. Not an exception: dispatch would convert one to an error dict
160
+ # anyway, and this way the message is written for the reader who
161
+ # needs it -- a model mid-run that must now decide something itself.
162
+ return {
163
+ "error": "ask_user cannot reach anyone in this run -- there is "
164
+ "nobody to answer. Decide it yourself, state the "
165
+ "assumption you are proceeding on, and carry on.",
166
+ }
167
+
168
+ answer = interaction.ask(response_channel, interaction.Request(
169
+ kind=interaction.QUESTION,
170
+ payload={
171
+ "question": question,
172
+ "options": options,
173
+ "multi_select": bool(params.get("multi_select")),
174
+ # Defaults TRUE: the spec lists a write-your-own answer as one of
175
+ # the four affordances, so absence of the key is not absence of
176
+ # the affordance.
177
+ "allow_text": params.get("allow_text", True) is not False,
178
+ },
179
+ ))
180
+
181
+ if answer is None:
182
+ # Nobody answered -- dismissed, timed out, or a shell returning
183
+ # something decode could not read. Distinct from a deferral below,
184
+ # and reported as such: "they declined to answer" and "they want to
185
+ # discuss it" call for different next moves.
186
+ return {
187
+ "error": "The user did not answer the question. Proceed on your "
188
+ "best judgement and say which assumption you made.",
189
+ }
190
+
191
+ if answer.get("defer"):
192
+ # The spec's escape, "returns control to the conversation instead of
193
+ # forcing a choice". A result rather than any change of control
194
+ # flow: the loop has one shape, and a tool that could abort a turn
195
+ # would be a second one. The model simply talks next.
196
+ return {
197
+ "result": "The user would rather discuss this than pick an "
198
+ "answer. Raise it in conversation -- do not call "
199
+ "ask_user again for the same question.",
200
+ }
201
+
202
+ chosen, text = answer.get("options") or [], answer.get("text") or ""
203
+ if not chosen and not text:
204
+ # A blank submission. They were present and said nothing, which is
205
+ # not the same as never being asked -- so this is not the no-channel
206
+ # error, and the wording does not tell the model to assume anything.
207
+ return {
208
+ "result": "The user answered without choosing an option or "
209
+ "writing anything. Ask again more specifically, or "
210
+ "raise it in conversation.",
211
+ }
212
+
213
+ return {"result": {"chosen": chosen, "text": text}}
@@ -0,0 +1,134 @@
1
+ """
2
+ tools/builtin/discrete_math.py
3
+
4
+ Number theory and combinatorics: gcd/lcm, primality, factorization,
5
+ factorial, permutations, combinations, and modular arithmetic.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Literal, Optional
11
+
12
+ import sympy
13
+ from pydantic import BaseModel, Field
14
+
15
+ _OPERATIONS = Literal[
16
+ "gcd", "lcm", "is_prime", "prime_factors", "next_prime",
17
+ "factorial", "permutations", "combinations",
18
+ "modular_exponent", "mod_inverse",
19
+ ]
20
+
21
+
22
+ class DiscreteMathParams(BaseModel):
23
+ operation: _OPERATIONS = Field(..., description="Which operation to perform")
24
+ a: Optional[int] = Field(None, description="First integer, for gcd/lcm")
25
+ b: Optional[int] = Field(None, description="Second integer, for gcd/lcm")
26
+ n: Optional[int] = Field(None, description="n, for is_prime/prime_factors/next_prime/factorial/permutations/combinations")
27
+ r: Optional[int] = Field(None, description="r, for permutations (nPr) / combinations (nCr)")
28
+ base: Optional[int] = Field(None, description="base, for modular_exponent/mod_inverse")
29
+ exponent: Optional[int] = Field(None, description="exponent, for modular_exponent")
30
+ modulus: Optional[int] = Field(None, description="modulus, for modular_exponent/mod_inverse")
31
+
32
+
33
+ TOOL_SCHEMA = {
34
+ "name": "discrete_math",
35
+ "description": (
36
+ "Number theory and combinatorics: gcd, lcm, primality testing, "
37
+ "prime factorization, next prime, factorial, permutations (nPr), "
38
+ "combinations (nCr), modular exponentiation, and modular inverse."
39
+ ),
40
+ "input_schema": DiscreteMathParams.model_json_schema(),
41
+ }
42
+
43
+
44
+ def run(params: dict) -> dict:
45
+ parsed = DiscreteMathParams(**params)
46
+
47
+ try:
48
+ op = parsed.operation
49
+
50
+ if op == "gcd":
51
+ if parsed.a is None or parsed.b is None:
52
+ return {"error": "gcd requires 'a' and 'b' (both integers)."}
53
+ result = sympy.gcd(parsed.a, parsed.b)
54
+ elif op == "lcm":
55
+ if parsed.a is None or parsed.b is None:
56
+ return {"error": "lcm requires 'a' and 'b' (both integers)."}
57
+ result = sympy.lcm(parsed.a, parsed.b)
58
+ elif op == "is_prime":
59
+ if parsed.n is None:
60
+ return {"error": "is_prime requires 'n' (integer)."}
61
+ result = sympy.isprime(parsed.n)
62
+ elif op == "prime_factors":
63
+ if parsed.n is None:
64
+ return {"error": "prime_factors requires 'n' (integer)."}
65
+ result = sympy.factorint(parsed.n) # {prime: exponent}
66
+ elif op == "next_prime":
67
+ if parsed.n is None:
68
+ return {"error": "next_prime requires 'n' (integer)."}
69
+ result = sympy.nextprime(parsed.n)
70
+ elif op == "factorial":
71
+ if parsed.n is None:
72
+ return {"error": "factorial requires 'n' (integer)."}
73
+ result = sympy.factorial(parsed.n)
74
+ elif op == "permutations":
75
+ # nPr = n! / (n-r)! -- computed directly rather than relying
76
+ # on a less-common sympy function name.
77
+ if parsed.n is None or parsed.r is None:
78
+ return {"error": "permutations requires 'n' and 'r' (integers)."}
79
+ result = sympy.factorial(parsed.n) / sympy.factorial(parsed.n - parsed.r)
80
+ elif op == "combinations":
81
+ if parsed.n is None or parsed.r is None:
82
+ return {"error": "combinations requires 'n' and 'r' (integers)."}
83
+ result = sympy.binomial(parsed.n, parsed.r)
84
+ elif op == "modular_exponent":
85
+ # H5. `pow(b, e, None)` is PLAIN exponentiation, and modulus
86
+ # is Optional -- so omitting one field silently turned this
87
+ # into a different operation with a different complexity
88
+ # class. Measured: exponent=10**9 with a modulus is 0.000s;
89
+ # without one it is 3.3s and a 125 MB integer, and the model
90
+ # chooses the arguments.
91
+ #
92
+ # An ERROR naming the field, not a silent plain power and not
93
+ # a separate `power` operation -- the second would advertise
94
+ # the unbounded path rather than close it. The tool's name is
95
+ # its contract, and H2's clock is a backstop for the runaway
96
+ # rather than a licence to keep offering it.
97
+ if parsed.base is None or parsed.exponent is None:
98
+ return {"error": "modular_exponent requires 'base', 'exponent' and 'modulus' (all integers)."}
99
+ if parsed.modulus is None:
100
+ return {"error": "modular_exponent requires a modulus. Without one this is plain exponentiation, which can produce a number too large to compute or return. Supply modulus, or ask for a smaller exponent."}
101
+ if parsed.modulus == 0:
102
+ return {"error": "modular_exponent requires a non-zero modulus (modulus cannot be 0)."}
103
+ result = pow(parsed.base, parsed.exponent, parsed.modulus)
104
+ elif op == "mod_inverse":
105
+ if parsed.base is None or parsed.modulus is None:
106
+ return {"error": "mod_inverse requires 'base' and 'modulus' (integers)."}
107
+ if parsed.modulus == 0:
108
+ return {"error": "mod_inverse requires a non-zero modulus (modulus cannot be 0)."}
109
+ result = sympy.mod_inverse(parsed.base, parsed.modulus)
110
+ else:
111
+ return {"error": f"Unknown operation: {op}"}
112
+
113
+ except Exception as e:
114
+ return {"error": f"Computation failed: {e}"}
115
+
116
+ # H6. The str() below is the SECOND place this function can fail, and
117
+ # it used to sit outside the try above -- so a correct answer that
118
+ # was merely too large to print left the handler as a bare
119
+ # ValueError, reached dispatch's containment, and was logged with a
120
+ # full traceback as though it were a bug in the harness. CPython caps
121
+ # int->str at 4300 digits, so `factorial n=100000` reaches this on
122
+ # ordinary input.
123
+ #
124
+ # Contained here rather than left to dispatch because dispatch's
125
+ # backstop exists for real bugs, and filling it with routine outcomes
126
+ # is how a real one stops being noticed. The message also has to tell
127
+ # the model something it can act on; the generic wrapper does not.
128
+ try:
129
+ if isinstance(result, dict):
130
+ return {"result": {str(k): v for k, v in result.items()},
131
+ "operation": op}
132
+ return {"result": str(result), "operation": op}
133
+ except ValueError as e:
134
+ return {"error": f"The {op} result was computed but is too large to return ({e}). Ask for the same operation with smaller inputs."}