@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,314 @@
1
+ """
2
+ tools/isolation.py
3
+
4
+ ROADMAP_v2 §31 (H2, H3). A wall clock for tool calls that can actually
5
+ stop the work.
6
+
7
+ WHY A PROCESS AND NOT A THREAD, WHICH IS THE WHOLE DECISION.
8
+
9
+ #57 was deferred once on the grounds that `signal.alarm` is main-thread
10
+ only and the TUI runs tools in a worker, so a thread-based watchdog was
11
+ the shape -- and "abandoning a thread mid-sympy is not clean". That is
12
+ true, and it is an argument against the thread rather than against the
13
+ bound. A thread cannot be cancelled in CPython: there is no interruption
14
+ point inside `sympy.binomial` for anything to check, so a watchdog that
15
+ times out returns an error while the core stays busy until the process
16
+ exits. The harness would then report a timeout that did not happen, which
17
+ is the class of mechanism this project keeps deciding against -- the same
18
+ reason `with_catalogs` suppresses a catalog rather than showing one whose
19
+ tool cannot be called.
20
+
21
+ A subprocess has the interruption point the thread lacks: the OS. Killing
22
+ it reclaims the CPU, which
23
+ `test_a_timed_out_call_is_STOPPED_not_merely_abandoned` measures directly
24
+ -- by evidence the child leaves on disk, not by os.times(), whose
25
+ children_user field is always 0.0 on Windows and would make the
26
+ assertion vacuous on the platform it usually runs on. That measurement is
27
+ the difference between the two designs rather than a detail of this one.
28
+
29
+ WHAT IT COSTS. A fresh interpreter plus sympy plus the tool module is
30
+ ~0.34s measured, against a harness where every step is a multi-second
31
+ model call. No warm pool: a pool holds interpreters that a killed call
32
+ would have to replace anyway, and the state a pooled worker accumulates
33
+ is exactly what a bound is supposed to discard.
34
+
35
+ MODELLED ON mcp_client.client.call_tool, which had this shape first and
36
+ wrote down why: an inner bound that stops the work (there,
37
+ `read_timeout_seconds`; here, RLIMIT_CPU) with an outer wall clock as the
38
+ backstop "for the case the answer is never coming at all". On Windows
39
+ there is no rlimit and no cheap equivalent, so the clock runs alone --
40
+ H3 records that asymmetry rather than papering over it.
41
+
42
+ WHAT CROSSES THE BOUNDARY. Params in as JSON, the result dict out as
43
+ JSON, and nothing else. That is not a limitation to work around: it is
44
+ the check that a BUDGET_COMPUTE tool really is a pure function of its
45
+ params, which `assert_budget_declared` enforces from the other side by
46
+ refusing a compute tool that declares an injection.
47
+ """
48
+
49
+ from __future__ import annotations
50
+
51
+ import json
52
+ import logging
53
+ import math
54
+ import os
55
+ import platform
56
+ import subprocess
57
+ import sys
58
+
59
+ import config
60
+
61
+ logger = logging.getLogger(__name__)
62
+
63
+ # The child prints one JSON object on this marker line. A marker rather
64
+ # than "parse the whole of stdout" because an imported module is entitled
65
+ # to write to stdout -- a deprecation notice from a pinned SymPy would
66
+ # otherwise be indistinguishable from a malformed result.
67
+ MARKER = "@@VENASTINE_RESULT@@"
68
+
69
+ # Bounded on the CHILD side, where the size is known before anything is
70
+ # written, and re-checked here. #55's own rule -- bound the read, do not
71
+ # slice afterwards -- applied to the mechanism that fixes #55. The value
72
+ # is generous next to what a math tool can actually return: CPython caps
73
+ # int->str at 4300 digits, so the realistic ceiling is far below this and
74
+ # the check is for the pathological case rather than the ordinary one.
75
+ MAX_CHILD_OUTPUT_BYTES = 4_000_000
76
+
77
+ # How much of the child's stderr reaches the error message. Enough to name
78
+ # a real failure, bounded because it is unbounded text from a process that
79
+ # just misbehaved.
80
+ _STDERR_EXCERPT = 400
81
+
82
+
83
+ def _package_root() -> str:
84
+ """The directory holding the `tools` package.
85
+
86
+ Derived from __file__, never from the working directory: dispatch has
87
+ no guarantee about cwd -- the TUI runs from wherever it was launched
88
+ and a subagent inherits nothing -- and a child that cannot import its
89
+ own tool would fail as a transport error on every call.
90
+ """
91
+ return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
92
+
93
+
94
+ def _child_env() -> dict:
95
+ """A minimal environment for the child.
96
+
97
+ A math tool needs no credentials, so it is handed none. This is
98
+ security/sandbox._scrubbed_env's argument applied to the other
99
+ subprocess this project spawns, with one difference: the sandbox
100
+ scrubs a shell's inherited environment, while there is nothing to
101
+ scrub here -- the child's environment is built rather than filtered,
102
+ which is the stronger direction.
103
+
104
+ PYTHONPATH is built from the PARENT's resolved sys.path rather than
105
+ from the package root alone. Guessing which variables reconstruct an
106
+ import surface is a losing game -- on Windows the user site-packages
107
+ is derived from APPDATA, a virtualenv needs its own prefix, conda
108
+ needs another -- and getting it wrong presents as ModuleNotFoundError
109
+ for sympy on every math call. Handing the child the paths the parent
110
+ actually resolved is deterministic and gives it exactly the parent's
111
+ imports and no more.
112
+
113
+ SYSTEMROOT is not optional on Windows: without it the interpreter
114
+ cannot initialise its socket/crypto machinery and exits before
115
+ reaching any tool.
116
+ """
117
+ root = _package_root()
118
+ path = [root] + [p for p in sys.path
119
+ if p and p != root and os.path.isdir(p)]
120
+ env = {"PYTHONPATH": os.pathsep.join(path),
121
+ # No .pyc writes from a process that exists for one call, and
122
+ # no first-call penalty for the directory scan.
123
+ "PYTHONDONTWRITEBYTECODE": "1",
124
+ # Deterministic, and it keeps a child's traceback readable.
125
+ "PYTHONIOENCODING": "utf-8"}
126
+ for name in ("SYSTEMROOT", "SystemRoot", "WINDIR", "PATH", "TEMP", "TMP",
127
+ "LD_LIBRARY_PATH"):
128
+ value = os.environ.get(name)
129
+ if value:
130
+ env[name] = value
131
+ return env
132
+
133
+
134
+ def _resource_limits():
135
+ """H3's inner layer: a preexec_fn setting RLIMIT_CPU and RLIMIT_AS, or
136
+ None where the platform has no rlimit.
137
+
138
+ Deliberately NOT security.sandbox._unix_resource_limits, though it is
139
+ the same three lines and the same idea. That one spends
140
+ SANDBOX_CPU_SECONDS (30), which is ABOVE this budget -- reusing it
141
+ would install a limit that can never fire and read, to anyone
142
+ checking, as though the inner layer were present. The CPU ceiling has
143
+ to be the compute budget or it is decoration.
144
+
145
+ The MEMORY ceiling IS shared with the sandbox, because that number is
146
+ about what one contained subprocess of this harness may hold and
147
+ nothing here argues for a different answer.
148
+ """
149
+ if platform.system() == "Windows":
150
+ return None
151
+
152
+ import resource
153
+
154
+ cpu_seconds = max(1, int(math.ceil(config.TOOL_COMPUTE_TIMEOUT_S)))
155
+ mem_bytes = config.SANDBOX_MEMORY_MB * 1024 * 1024
156
+
157
+ def _set_limits():
158
+ resource.setrlimit(resource.RLIMIT_CPU, (cpu_seconds, cpu_seconds))
159
+ resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))
160
+
161
+ return _set_limits
162
+
163
+
164
+ def _limit_message(tool_name: str, timeout: float) -> str:
165
+ """What the model is told when a bound stopped the call.
166
+
167
+ ONE wording, because H3 gives the child two bounds on Unix and one
168
+ on Windows and they do not fail the same way. The wall clock raises
169
+ TimeoutExpired in the parent; RLIMIT_CPU kills the child, so
170
+ subprocess.run RETURNS -- normally, with a negative returncode --
171
+ and the parent never sees a timeout at all.
172
+
173
+ They are the same event to the only reader that matters: a model
174
+ deciding whether to ask for something smaller. Two wordings would
175
+ make the better-protected platform give the worse answer, which is
176
+ what CI caught on the first Linux run of this section.
177
+ """
178
+ return (f"{tool_name} exceeded its {timeout:g}s limit and was stopped. "
179
+ f"The inputs given are too large for this operation -- try "
180
+ f"smaller values.")
181
+
182
+
183
+ def _interpret(tool_name: str, stdout: str, stderr: str, returncode: int,
184
+ timeout: float) -> dict:
185
+ """Turn what the child said into the dict dispatch expects.
186
+
187
+ Every branch returns rather than raises. dispatch's own containment
188
+ would convert an exception into an error dict anyway, but it would log
189
+ a traceback with it -- and an oversized factorial is an ordinary thing
190
+ for a model to ask for, not a bug in this harness.
191
+ """
192
+ if len(stdout) > MAX_CHILD_OUTPUT_BYTES:
193
+ return {"error": f"{tool_name} produced more output than can be "
194
+ f"returned ({len(stdout)} bytes). Ask for a smaller "
195
+ f"result."}
196
+
197
+ for line in stdout.splitlines():
198
+ if line.startswith(MARKER):
199
+ try:
200
+ return json.loads(line[len(MARKER):])
201
+ except ValueError:
202
+ break
203
+
204
+ # A NEGATIVE returncode means the child was killed by a signal, and
205
+ # for a child this module launched that means a bound fired --
206
+ # RLIMIT_CPU raises SIGXCPU and then SIGKILL at the hard limit
207
+ # (H3's inner layer), which is the ONLY way a compute child dies
208
+ # without either answering or timing out in the parent.
209
+ #
210
+ # Checked before the generic branch, not after, and reported with
211
+ # the same sentence the wall clock uses. Windows has no rlimit and
212
+ # signals a killed process differently, so this is unreachable
213
+ # there -- which is exactly why it went unnoticed until CI ran the
214
+ # suite on Linux.
215
+ if returncode is not None and returncode < 0:
216
+ logger.info("%s was stopped by its resource limit (signal %d).",
217
+ tool_name, -returncode)
218
+ return {"error": _limit_message(tool_name, timeout)}
219
+
220
+ excerpt = (stderr or "").strip().replace("\n", " ")[-_STDERR_EXCERPT:]
221
+ # logger.warning, not exception: there is no traceback here to keep,
222
+ # and this path is reachable by ordinary input.
223
+ logger.warning("%s produced no readable result (exit %s): %s",
224
+ tool_name, returncode, excerpt)
225
+ return {"error": f"{tool_name} did not return a usable result "
226
+ f"(exit {returncode}). {excerpt}".strip()}
227
+
228
+
229
+ def run_isolated(handler, params: dict, timeout: float,
230
+ tool_name: str = "") -> dict:
231
+ """Run `handler` in a killable child and return its result dict.
232
+
233
+ `handler` is resolved by module and qualified name in the child rather
234
+ than pickled: the registry's handlers are plain module-level functions
235
+ and naming them keeps the child's import surface to the one tool.
236
+ Both names come from the registry, never from a model.
237
+ """
238
+ tool_name = tool_name or getattr(handler, "__name__", "tool")
239
+ module = getattr(handler, "__module__", None)
240
+ function = getattr(handler, "__name__", None)
241
+ if not module or not function:
242
+ # A handler that is not a named module-level function cannot be
243
+ # reached from a fresh interpreter. Refuse rather than fall back to
244
+ # an in-process call, which would silently drop the bound this
245
+ # whole module exists to apply.
246
+ return {"error": f"{tool_name} cannot be isolated: its handler is "
247
+ f"not a named module-level function."}
248
+
249
+ request = json.dumps({"module": module, "function": function,
250
+ "params": params, "max_bytes":
251
+ MAX_CHILD_OUTPUT_BYTES})
252
+
253
+ popen_kwargs = {}
254
+ if platform.system() != "Windows":
255
+ popen_kwargs["preexec_fn"] = _resource_limits()
256
+
257
+ try:
258
+ child = subprocess.run(
259
+ [sys.executable, "-m", "tools.isolation"],
260
+ input=request,
261
+ capture_output=True,
262
+ text=True,
263
+ encoding="utf-8",
264
+ errors="replace",
265
+ timeout=timeout,
266
+ cwd=_package_root(),
267
+ env=_child_env(),
268
+ **popen_kwargs,
269
+ )
270
+ except subprocess.TimeoutExpired:
271
+ # subprocess.run has already killed the child and reaped it, which
272
+ # is the property that makes this a bound rather than a report.
273
+ #
274
+ # On Unix the CPU limit usually gets there first and this branch
275
+ # never runs -- see _interpret's negative-returncode case, which
276
+ # shares this wording rather than repeating it.
277
+ return {"error": _limit_message(tool_name, timeout)}
278
+ except OSError as e:
279
+ logger.warning("Could not start an isolated child for %s: %s",
280
+ tool_name, e)
281
+ return {"error": f"{tool_name} could not be run: {e}"}
282
+
283
+ return _interpret(tool_name, child.stdout, child.stderr,
284
+ child.returncode, timeout)
285
+
286
+
287
+ def _child_main() -> int:
288
+ """The child. Reads one request from stdin, prints one marked result.
289
+
290
+ Kept deliberately small: everything it does before the handler runs is
291
+ time the wall clock is already counting.
292
+ """
293
+ request = json.loads(sys.stdin.read())
294
+ import importlib
295
+
296
+ module = importlib.import_module(request["module"])
297
+ handler = getattr(module, request["function"])
298
+ result = handler(request["params"])
299
+
300
+ payload = json.dumps(result, default=str)
301
+ limit = request.get("max_bytes", MAX_CHILD_OUTPUT_BYTES)
302
+ if len(payload) > limit:
303
+ # Refused HERE, where the size is known before anything is
304
+ # written. The parent checks too, but this is the producer and
305
+ # #55's whole point is that the producer is where a bound belongs.
306
+ payload = json.dumps({
307
+ "error": "the result is too large to return "
308
+ f"({len(payload)} bytes). Ask for a smaller result."})
309
+ sys.stdout.write(MARKER + payload + "\n")
310
+ return 0
311
+
312
+
313
+ if __name__ == "__main__":
314
+ sys.exit(_child_main())