@yahyahammad/venastine 0.3.8 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
package/core/approval.py CHANGED
@@ -1,137 +1,137 @@
1
- """
2
- core/approval.py
3
-
4
- ROADMAP_v2 §25. How a run obtains human authorization for a tool call,
5
- as data rather than as a mechanism baked into one shell.
6
-
7
- There are exactly two ways an approval-gated call can proceed, and they
8
- compose:
9
-
10
- * a GRANT -- the user said yes before the run started, naming tools.
11
- * a PROVIDER -- the user is present and can be asked, per call.
12
-
13
- Neither is a policy relaxation. security/permissions.py still decides
14
- whether a tool is allowed at all and whether a call needs approval (D14,
15
- "stricter wins"); this module only carries the human's answer to the
16
- question that policy raised. That is why a grant lives on RunInfo and not
17
- in ToolContext.approval_overrides -- those OR, so they can only tighten.
18
-
19
- §23 CARRIED OUT the generalisation this module used to anticipate.
20
- `ApprovalProvider` and `ReviewConsent` both lived here and are gone: they
21
- were two caller-supplied ways to ask a question and block for an answer,
22
- and they are now one, `core.interaction.ResponseChannel`. What remains
23
- here is authorization DATA -- what the human already decided and how much
24
- of it is left to spend -- which is a different thing from the means of
25
- asking, and is why the two are separate modules rather than one.
26
-
27
- `RunAuthorization.provider` therefore holds a ResponseChannel now. The
28
- field keeps its name because it plays the same role in the bundle: the
29
- route by which a run can obtain an answer it does not already have.
30
-
31
- Deliberately a leaf module with no project imports -- core/interaction.py
32
- is imported for typing only, and it is itself a leaf. core/loop.py,
33
- main.py, tui/app.py and core/reasoning/ all depend on both; neither
34
- depends on them.
35
- """
36
-
37
- import threading
38
- from dataclasses import dataclass, field
39
- from typing import TYPE_CHECKING, Optional
40
-
41
- if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
42
- from core.interaction import ResponseChannel
43
-
44
-
45
- class GrantBudget:
46
- """A ceiling on how many pre-granted calls one run may make.
47
-
48
- Pre-flight authorization trades a per-call decision for a single
49
- up-front one, so the thing it gives up is the natural bound on how
50
- many times a granted tool runs. A ten-pass pipeline reading
51
- attacker-controlled web pages is exactly where an injected loop would
52
- spend that authority, and where nobody is watching it happen.
53
-
54
- ONE instance per pipeline run, shared across all ten passes BY
55
- REFERENCE -- a budget rebuilt per pass would multiply the ceiling by
56
- ten and read as if it were enforcing one.
57
-
58
- Exhaustion is not a failure: take() returning False means the grant
59
- stops applying, so the call falls back to being ASKED. With a provider
60
- present the run continues under supervision; without one it is denied,
61
- which is what a headless run does with any gated tool anyway.
62
-
63
- §47 slice 8: GUARDED, because the sentence above -- one instance
64
- shared by reference -- is exactly what makes it a shared mutable under
65
- threads. `take()` is a read-modify-write, so two children reading
66
- `used` before either writes it both proceed, and the ceiling that is
67
- the whole point of the class is exceeded. Guarded rather than copied
68
- per child for the reason the sharing exists at all: a budget rebuilt
69
- per branch multiplies the ceiling by the branch count while reading as
70
- if it enforced one.
71
- """
72
-
73
- def __init__(self, limit: int) -> None:
74
- self.limit = limit
75
- self.used = 0
76
- # Not an RLock: nothing under `take` re-enters this object, and a
77
- # plain Lock is what makes that claim checkable.
78
- self._lock = threading.Lock()
79
-
80
- def take(self) -> bool:
81
- """Consume one unit. False when the ceiling is reached.
82
-
83
- The test AND the increment are inside the lock. Guarding only the
84
- increment would keep the overshoot -- the decision to spend is the
85
- read, and a decision made on a stale read is the defect.
86
- """
87
- with self._lock:
88
- if self.used >= self.limit:
89
- return False
90
- self.used += 1
91
- return True
92
-
93
- @property
94
- def exhausted(self) -> bool:
95
- # One read of one int, so no lock: the answer is a snapshot either
96
- # way, and every CALLER that acts on it goes through take(), which
97
- # re-decides under the lock. This property is for reporting.
98
- return self.used >= self.limit
99
-
100
-
101
- @dataclass
102
- class RunAuthorization:
103
- """Everything a run needs to answer "may this gated call proceed?".
104
-
105
- Bundled rather than passed as three parameters because it threads
106
- through four layers -- shell, orchestrator, pass entry point, loop --
107
- and three of those only forward it. A bundle means adding a fourth
108
- kind of authorization later touches the layers that USE it, not every
109
- layer it passes through.
110
-
111
- granted_tools: names authorised before the run. Only meaningful for
112
- tools the registry reports as grantable; the loop re-checks rather
113
- than trusting the set, so a stale or hand-edited name cannot widen
114
- anything.
115
- provider: a core.interaction.ResponseChannel, present iff someone can
116
- be asked during the run. §23 replaced ApprovalProvider here; the
117
- field name stays because its role in the bundle is unchanged.
118
- budget: shared across every pass of one pipeline run.
119
- """
120
-
121
- granted_tools: set = field(default_factory=set)
122
- provider: Optional["ResponseChannel"] = None
123
- budget: Optional[GrantBudget] = None
124
- # Calls that proceeded on the grant, accumulated across every pass of
125
- # one run. Lives here rather than in module state or a per-pass return
126
- # value for the same reason the budget does: the bundle is already
127
- # shared by reference, and what the authorization was SPENT ON is
128
- # authorization state. The orchestrator points PipelineRun.granted_calls
129
- # at THIS SAME LIST at the start of the run, so the trail is on the run
130
- # at every §5 checkpoint and on the failure path.
131
- #
132
- # Not a copy taken at the end -- this comment used to say it was, which
133
- # is the design §25 rejected and the opposite of what the code does
134
- # (audit #83). Copying at the end would lose the trail on exactly the
135
- # runs most worth auditing; unit 9 mutated the share into `list(...)`
136
- # and it went red.
137
- granted_calls: list = field(default_factory=list)
1
+ """
2
+ core/approval.py
3
+
4
+ ROADMAP_v2 §25. How a run obtains human authorization for a tool call,
5
+ as data rather than as a mechanism baked into one shell.
6
+
7
+ There are exactly two ways an approval-gated call can proceed, and they
8
+ compose:
9
+
10
+ * a GRANT -- the user said yes before the run started, naming tools.
11
+ * a PROVIDER -- the user is present and can be asked, per call.
12
+
13
+ Neither is a policy relaxation. security/permissions.py still decides
14
+ whether a tool is allowed at all and whether a call needs approval (D14,
15
+ "stricter wins"); this module only carries the human's answer to the
16
+ question that policy raised. That is why a grant lives on RunInfo and not
17
+ in ToolContext.approval_overrides -- those OR, so they can only tighten.
18
+
19
+ §23 CARRIED OUT the generalisation this module used to anticipate.
20
+ `ApprovalProvider` and `ReviewConsent` both lived here and are gone: they
21
+ were two caller-supplied ways to ask a question and block for an answer,
22
+ and they are now one, `core.interaction.ResponseChannel`. What remains
23
+ here is authorization DATA -- what the human already decided and how much
24
+ of it is left to spend -- which is a different thing from the means of
25
+ asking, and is why the two are separate modules rather than one.
26
+
27
+ `RunAuthorization.provider` therefore holds a ResponseChannel now. The
28
+ field keeps its name because it plays the same role in the bundle: the
29
+ route by which a run can obtain an answer it does not already have.
30
+
31
+ Deliberately a leaf module with no project imports -- core/interaction.py
32
+ is imported for typing only, and it is itself a leaf. core/loop.py,
33
+ main.py, tui/app.py and core/reasoning/ all depend on both; neither
34
+ depends on them.
35
+ """
36
+
37
+ import threading
38
+ from dataclasses import dataclass, field
39
+ from typing import TYPE_CHECKING, Optional
40
+
41
+ if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
42
+ from core.interaction import ResponseChannel
43
+
44
+
45
+ class GrantBudget:
46
+ """A ceiling on how many pre-granted calls one run may make.
47
+
48
+ Pre-flight authorization trades a per-call decision for a single
49
+ up-front one, so the thing it gives up is the natural bound on how
50
+ many times a granted tool runs. A ten-pass pipeline reading
51
+ attacker-controlled web pages is exactly where an injected loop would
52
+ spend that authority, and where nobody is watching it happen.
53
+
54
+ ONE instance per pipeline run, shared across all ten passes BY
55
+ REFERENCE -- a budget rebuilt per pass would multiply the ceiling by
56
+ ten and read as if it were enforcing one.
57
+
58
+ Exhaustion is not a failure: take() returning False means the grant
59
+ stops applying, so the call falls back to being ASKED. With a provider
60
+ present the run continues under supervision; without one it is denied,
61
+ which is what a headless run does with any gated tool anyway.
62
+
63
+ §47 slice 8: GUARDED, because the sentence above -- one instance
64
+ shared by reference -- is exactly what makes it a shared mutable under
65
+ threads. `take()` is a read-modify-write, so two children reading
66
+ `used` before either writes it both proceed, and the ceiling that is
67
+ the whole point of the class is exceeded. Guarded rather than copied
68
+ per child for the reason the sharing exists at all: a budget rebuilt
69
+ per branch multiplies the ceiling by the branch count while reading as
70
+ if it enforced one.
71
+ """
72
+
73
+ def __init__(self, limit: int) -> None:
74
+ self.limit = limit
75
+ self.used = 0
76
+ # Not an RLock: nothing under `take` re-enters this object, and a
77
+ # plain Lock is what makes that claim checkable.
78
+ self._lock = threading.Lock()
79
+
80
+ def take(self) -> bool:
81
+ """Consume one unit. False when the ceiling is reached.
82
+
83
+ The test AND the increment are inside the lock. Guarding only the
84
+ increment would keep the overshoot -- the decision to spend is the
85
+ read, and a decision made on a stale read is the defect.
86
+ """
87
+ with self._lock:
88
+ if self.used >= self.limit:
89
+ return False
90
+ self.used += 1
91
+ return True
92
+
93
+ @property
94
+ def exhausted(self) -> bool:
95
+ # One read of one int, so no lock: the answer is a snapshot either
96
+ # way, and every CALLER that acts on it goes through take(), which
97
+ # re-decides under the lock. This property is for reporting.
98
+ return self.used >= self.limit
99
+
100
+
101
+ @dataclass
102
+ class RunAuthorization:
103
+ """Everything a run needs to answer "may this gated call proceed?".
104
+
105
+ Bundled rather than passed as three parameters because it threads
106
+ through four layers -- shell, orchestrator, pass entry point, loop --
107
+ and three of those only forward it. A bundle means adding a fourth
108
+ kind of authorization later touches the layers that USE it, not every
109
+ layer it passes through.
110
+
111
+ granted_tools: names authorised before the run. Only meaningful for
112
+ tools the registry reports as grantable; the loop re-checks rather
113
+ than trusting the set, so a stale or hand-edited name cannot widen
114
+ anything.
115
+ provider: a core.interaction.ResponseChannel, present iff someone can
116
+ be asked during the run. §23 replaced ApprovalProvider here; the
117
+ field name stays because its role in the bundle is unchanged.
118
+ budget: shared across every pass of one pipeline run.
119
+ """
120
+
121
+ granted_tools: set = field(default_factory=set)
122
+ provider: Optional["ResponseChannel"] = None
123
+ budget: Optional[GrantBudget] = None
124
+ # Calls that proceeded on the grant, accumulated across every pass of
125
+ # one run. Lives here rather than in module state or a per-pass return
126
+ # value for the same reason the budget does: the bundle is already
127
+ # shared by reference, and what the authorization was SPENT ON is
128
+ # authorization state. The orchestrator points PipelineRun.granted_calls
129
+ # at THIS SAME LIST at the start of the run, so the trail is on the run
130
+ # at every §5 checkpoint and on the failure path.
131
+ #
132
+ # Not a copy taken at the end -- this comment used to say it was, which
133
+ # is the design §25 rejected and the opposite of what the code does
134
+ # (audit #83). Copying at the end would lose the trail on exactly the
135
+ # runs most worth auditing; unit 9 mutated the share into `list(...)`
136
+ # and it went red.
137
+ granted_calls: list = field(default_factory=list)