@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,309 @@
1
+ """
2
+ security/protected_paths.py
3
+
4
+ The trees a sandboxed command must never be able to WRITE: the harness's
5
+ own source, and the user-tier state that decides what the harness trusts
6
+ and what it spawns.
7
+
8
+ WHY THIS EXISTS. security/sandbox.py's Docker backend binds
9
+ config.WORKSPACE_DIR read-write at /workspace and never asked what was on
10
+ the other side of that mount. A SANDBOXED command under CONTAINED with no
11
+ network is AUTO-APPROVED (security/capability.auto_approved), so nothing
12
+ prompts -- which meant a workspace pointed at the harness's own directory
13
+ handed every run unattended read-write access to the code it was about to
14
+ execute next, and a workspace pointed at a home directory did the same to
15
+ `~/.config/venastine/`. That directory holds `trusted_projects.json` (the
16
+ D17 gate: a write there marks arbitrary projects trusted) and `mcp.json`
17
+ (which NAMES COMMANDS the harness spawns at startup). Neither is a file
18
+ the model should be able to edit through a tool it did not have to ask
19
+ about.
20
+
21
+ The agent cannot cause this by itself -- WORKSPACE_DIR is bound once at
22
+ import (config.py) and a child shell's `export` dies with the subprocess,
23
+ which was measured rather than assumed. This is a MISCONFIGURATION
24
+ boundary: it makes a workspace that overlaps the harness a startup error
25
+ instead of a silent grant.
26
+
27
+ TWO CLASSES, and the split is the design rather than tidiness:
28
+
29
+ CRITICAL the harness install tree and the user config dir. A
30
+ workspace that IS one of these, or sits inside one, is
31
+ refused outright -- there is no mount arrangement that
32
+ rescues it, and nobody has such a layout on purpose.
33
+
34
+ SENSITIVE providers.json, the database, the log directory. These are
35
+ ro-mounted when they fall inside the workspace but NEVER
36
+ refuse it, because each is user-configurable to anywhere:
37
+ AGENT_LOG_FILE can legitimately point at a file in $HOME,
38
+ and letting that refuse a $HOME workspace would turn a
39
+ logging preference into a launch failure.
40
+
41
+ This generalises security/sandbox._venastine_readonly_mount, which does
42
+ the same job for a `.venastine/` nested in the workspace and whose
43
+ docstring already named this gap: "does not cover ... the harness's own
44
+ `agents/builtin` when the workspace is the harness repo."
45
+
46
+ THE PROTECTED SEGMENT at the bottom of this file is the module's second
47
+ job, added because everything above answered only half the question. The
48
+ trees and ro-mounts stop a SANDBOXED command from writing what it should
49
+ not; nothing stopped the agent's own read/write/edit tools from reaching
50
+ the same material once AGENT_WORKSPACE was pointed at the project --
51
+ workspace membership is the only rule those tools apply, so `.venastine/`
52
+ was an auto-approved path the moment it sat inside one. PROTECTED_SEGMENTS
53
+ is the one list every consumer reads (the file tools' refusal_check and
54
+ handlers, and shell.py's approval check), so the segment cannot drift
55
+ between them.
56
+
57
+ KNOWN LIMITS, stated because a half-understood control is worse than
58
+ none. This covers WRITES on the DOCKER path. It does not cover reads, and
59
+ it does not cover the subprocess fallback, which mounts nothing and has
60
+ no filesystem isolation at all -- see SECURITY.md, where that combination
61
+ is recorded as a documented risk rather than a defect.
62
+ """
63
+
64
+ from __future__ import annotations
65
+
66
+ import logging
67
+ import os
68
+ import re
69
+
70
+ import config
71
+ import credentials
72
+
73
+ logger = logging.getLogger(__name__)
74
+
75
+ # The directories inside the install tree that the harness itself writes
76
+ # artifacts to, and which therefore stay usable as a workspace. This is
77
+ # an ALLOWLIST and that direction is load-bearing: a module added in a
78
+ # later batch is protected the day it lands, whereas a denylist of source
79
+ # directories would leave it mounted read-write until somebody remembered
80
+ # to extend the list. `./workspace` is also the shipped default, so this
81
+ # is the branch that keeps the ordinary layout working.
82
+ WRITABLE_INSIDE_HARNESS = ("workspace", "output")
83
+
84
+
85
+ def harness_root() -> str:
86
+ """The install tree of the harness that is RUNNING, not any copy.
87
+
88
+ Derived from this file rather than from the cwd, so it is correct
89
+ under every launch route: `python main.py` from a clone, and
90
+ bin/venastine.mjs spawning `python <ROOT>/main.py` from a global npm
91
+ install while the user's cwd is somewhere else entirely.
92
+
93
+ That it names the running install is deliberate and is what keeps
94
+ development workable. An npm-installed harness aimed at a separate
95
+ clone of its own source sees two disjoint trees and allows it: writing
96
+ to a clone you are not executing cannot escalate the privileges of the
97
+ process doing the writing. Only pointing the workspace at the tree
98
+ currently being executed is refused.
99
+ """
100
+ return os.path.realpath(os.path.dirname(os.path.dirname(
101
+ os.path.abspath(__file__))))
102
+
103
+
104
+ def user_config_dir() -> str:
105
+ """`~/.config/venastine`, resolved at CALL time.
106
+
107
+ Mirrors core.config_loader._user_config_dir rather than importing it.
108
+ security/ imports config, credentials and the stdlib; reaching into
109
+ core/ from here would invert the layering the sandbox module's
110
+ `_within` docstring sets out. The duplication is pinned by
111
+ `TestTheMirroredResolversMatchTheirOwners` in tests/test_shell.py, so
112
+ drift is a test failure rather than a silent hole.
113
+
114
+ That sentence named a private function without its underscore and a
115
+ test that has never existed under the name given, for two batches --
116
+ the guard was real and the citation was not, which is the worse half
117
+ of the pair to get wrong: a reader who greps the name finds nothing
118
+ and concludes the duplication is unguarded.
119
+ """
120
+ return os.path.realpath(os.path.expanduser("~/.config/venastine"))
121
+
122
+
123
+ def _log_dir() -> str:
124
+ """The directory the rotating log handler writes into.
125
+
126
+ Mirrors logging_setup's resolution -- AGENT_LOG_FILE, else
127
+ `logs/app.log` -- rather than importing it, and here the reason is
128
+ concrete rather than stylistic: logging_setup imports
129
+ safety.policy_enforcement, so an import would be the first
130
+ `security/ -> safety/` edge in the project.
131
+
132
+ The DIRECTORY, not the file: RotatingFileHandler writes `app.log.1`,
133
+ `.2` and so on beside it, and protecting only the live file would
134
+ leave every rotated copy writable -- which is the half that matters
135
+ if what you are worried about is a run editing its own trail.
136
+ """
137
+ log_file = os.environ.get("AGENT_LOG_FILE", "logs/app.log")
138
+ return os.path.realpath(os.path.dirname(log_file) or ".")
139
+
140
+
141
+ def critical_paths() -> list[tuple[str, str]]:
142
+ """(realpath, label) for the trees that also REFUSE a workspace."""
143
+ return [
144
+ (harness_root(), "the harness's own install tree"),
145
+ (user_config_dir(), "the user config directory"),
146
+ ]
147
+
148
+
149
+ def sensitive_paths() -> list[tuple[str, str]]:
150
+ """(realpath, label) for the paths that are only ever ro-mounted."""
151
+ return [
152
+ (os.path.realpath(credentials.LLM_PROVIDERS_FILE),
153
+ "the provider credentials file"),
154
+ (os.path.realpath(config.DB_PATH), "the conversation database"),
155
+ (_log_dir(), "the log directory"),
156
+ ]
157
+
158
+
159
+ def _relation(candidate: str, other: str) -> str:
160
+ """How *candidate* sits against *other*: equal, inside, contains, or
161
+ disjoint. Both are realpath'd by the callers already.
162
+
163
+ `+ os.sep` on both comparisons for the reason test_file_ops.py:314
164
+ records about `_is_within_workspace`: a bare startswith makes
165
+ `/workspace-evil` look like it is inside `/workspace`.
166
+ """
167
+ if candidate == other:
168
+ return "equal"
169
+ if candidate.startswith(other + os.sep):
170
+ return "inside"
171
+ if other.startswith(candidate + os.sep):
172
+ return "contains"
173
+ return "disjoint"
174
+
175
+
176
+ def _exempt_from_harness_refusal(workspace_real: str) -> bool:
177
+ """Whether a workspace inside the install tree is one of the harness's
178
+ own artifact directories (or something under one)."""
179
+ root = harness_root()
180
+ for name in WRITABLE_INSIDE_HARNESS:
181
+ allowed = os.path.realpath(os.path.join(root, name))
182
+ if _relation(workspace_real, allowed) in ("equal", "inside"):
183
+ return True
184
+ return False
185
+
186
+
187
+ def check_workspace(workspace_dir: str) -> str | None:
188
+ """Why *workspace_dir* may not be used as a sandbox workspace, or None.
189
+
190
+ Returns a REASON STRING rather than raising, so the two callers can
191
+ fail in the shape each needs -- main.py prints it and exits, and
192
+ security/sandbox.py raises SandboxUnavailable. Raising a sandbox
193
+ exception from here would mean importing sandbox.py, which imports
194
+ this module.
195
+
196
+ The message is written for the person who has to fix it, and names
197
+ both what overlaps and what to do instead: a workspace refusal is
198
+ always a configuration error, never something the model did.
199
+ """
200
+ workspace_real = os.path.realpath(workspace_dir)
201
+
202
+ for protected, label in critical_paths():
203
+ relation = _relation(workspace_real, protected)
204
+ if relation not in ("equal", "inside"):
205
+ continue
206
+ if protected == harness_root() and _exempt_from_harness_refusal(
207
+ workspace_real):
208
+ continue
209
+ where = (label if relation == "equal"
210
+ else f"inside {label} ({protected})")
211
+ return (
212
+ f"AGENT_WORKSPACE ({workspace_real}) is {where}. The sandbox "
213
+ f"mounts the workspace read-write and non-inert commands are "
214
+ f"auto-approved inside it, so this would let a shell command "
215
+ f"rewrite the harness's own code, or the state that decides "
216
+ f"what it trusts and what it spawns. Point AGENT_WORKSPACE at "
217
+ f"a directory outside it -- the default is ./workspace."
218
+ )
219
+ return None
220
+
221
+
222
+ def readonly_mounts(workspace_real: str) -> list[str]:
223
+ """Docker `-v` arguments binding every protected path NESTED inside
224
+ *workspace_real* read-only, in the order docker expects them.
225
+
226
+ Only what already EXISTS is mounted, copying the `isdir` half of
227
+ _venastine_readonly_mount and for the same reason: docker CREATES a
228
+ missing bind source as a root-owned directory on the host, so an
229
+ unconditional mount would conjure a `.config/venastine/` into the
230
+ user's tree, or an `app.db` that is a DIRECTORY where the harness
231
+ expects a SQLite file.
232
+
233
+ Nested protected paths are collapsed to the outermost -- the database
234
+ and the log directory both live under `~/.config/venastine` on a
235
+ global install -- because a second bind underneath a read-only one
236
+ buys nothing and only makes the command line harder to read.
237
+ """
238
+ candidates = []
239
+ for protected, _label in critical_paths() + sensitive_paths():
240
+ if _relation(protected, workspace_real) != "inside":
241
+ continue
242
+ if not os.path.exists(protected):
243
+ continue
244
+ candidates.append(protected)
245
+
246
+ # Shortest first, so an ancestor is always decided before anything
247
+ # underneath it and the collapse below only ever has to look backwards.
248
+ kept: list[str] = []
249
+ for protected in sorted(set(candidates), key=len):
250
+ if any(_relation(protected, outer) == "inside" for outer in kept):
251
+ continue
252
+ kept.append(protected)
253
+
254
+ args: list[str] = []
255
+ for protected in kept:
256
+ rel = os.path.relpath(protected, workspace_real).replace(os.sep, "/")
257
+ args.extend(["-v", f"{protected}:/workspace/{rel}:ro"])
258
+ return args
259
+
260
+
261
+ # ===========================================================================
262
+ # ---- Protected path segments ----------------------------------------------
263
+ # ===========================================================================
264
+
265
+ # Path components the agent's own tools may never touch, wherever they sit
266
+ # in a RESOLVED path. `.venastine/` holds settings.json and mcp.json --
267
+ # which names commands the harness spawns at startup -- and, under skills/
268
+ # and agents/, content that is injected into system prompts. The trees
269
+ # above answer what a SANDBOXED command may write; this answers what the
270
+ # agent's read/write/edit tools may reach at all, which workspace
271
+ # membership alone does not: with AGENT_WORKSPACE pointed at the project,
272
+ # `.venastine/` is inside the workspace and file_ops'
273
+ # `_file_approval_check` auto-approves it.
274
+ #
275
+ # ONE LIST, THREE CONSUMERS -- the same discipline as the local-secret
276
+ # exclusion lists, which exist because three copies of one fact drift.
277
+ # tools/builtin/file_ops.py refuses any path carrying one of these
278
+ # segments (refusal_check AND the three handlers); tools/builtin/shell.py
279
+ # forces a prompt for any command whose tokens name one; and
280
+ # project_docs.py unions this set into its own wider denylist rather than
281
+ # re-spelling the segment.
282
+ #
283
+ # KNOWN LIMITS, in the house style. The file tools DENY; the shell only
284
+ # ever ASKS, because a token check that learned shell syntax would be a
285
+ # parser whose bugs auto-approve (G2), and an approval prompt leaves the
286
+ # whole command text in front of a human instead. The auto-approved INERT
287
+ # tier executes argv with no shell (§46 EP5), so its tokens ARE its
288
+ # arguments and a token check is sound there; every tier that could
289
+ # expand a glob or a variable into the segment is asked about anyway.
290
+ # MCP servers exposing their own file tools are a separate surface this
291
+ # list does not reach, and the user-tier `~/.config/venastine` stays
292
+ # where it always was -- outside a default workspace it is prompt-gated
293
+ # by the workspace boundary, not denied.
294
+ PROTECTED_SEGMENTS = frozenset({".venastine"})
295
+
296
+
297
+ def protected_segment(resolved_path: str) -> str | None:
298
+ """The protected segment *resolved_path* carries, or None.
299
+
300
+ Callers pass a realpath'd path (file_ops' ``resolve_path``, the
301
+ sandbox's ``_within``), so `..` travel and symlinks are already
302
+ collapsed: a link pointing at `.venastine/settings.json` arrives
303
+ here as the real thing, and on Windows so does a case-spelled one.
304
+ Split on both separators because a raw shell token may carry either.
305
+ """
306
+ for part in re.split(r"[\\/]", resolved_path):
307
+ if part in PROTECTED_SEGMENTS:
308
+ return part
309
+ return None