@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
@@ -1,149 +1,149 @@
1
- """
2
- tools/builtin/todo.py
3
-
4
- ROADMAP_v2 §23 slice 2: the todo list. "A model-maintained checklist,
5
- persisted per thread."
6
-
7
- WHOLE-LIST WRITE, NOT GRANULAR OPERATIONS (J13). One call replaces the list,
8
- so it is always internally consistent, reordering is free, and no item is
9
- ever addressed by name or index. Granular add/complete/remove would each need
10
- a stable way to name one item -- which is the problem `clear_refs` refused to
11
- solve ("a per-reference removal needs a stable way for a person to name one")
12
- and the problem §21b's "removal is by id, never by substring" rule exists to
13
- prevent. A model naming the wrong id silently mutates the wrong entry; a model
14
- rewriting the list cannot.
15
-
16
- STORED IN extra_data (J14), under its own key beside §18's goal and §21c's
17
- refs. storage.py's `get_thread_extra` docstring has said "goal mode §18, todo
18
- list §23" since §18, and §27's column-versus-extra_data argument was about
19
- keeping `list_threads()` cheap -- a todo list is only ever read for the
20
- current thread, so queryability buys nothing.
21
-
22
- WORKS HEADLESS (J9). §23 AC2 says "both tools deny cleanly with no way to ask",
23
- but that was written before this tool's shape was settled: the deny rule
24
- exists because a blocking prompt nobody answers turns into a hang, and this
25
- tool never blocks and never asks anyone anything. A ten-pass research run
26
- keeping its own checklist is arguably where one helps most. It needs a
27
- conversation, not a person.
28
- """
29
-
30
- import config
31
-
32
- TOOL_SCHEMA = {
33
- "name": "todo_write",
34
- "description": (
35
- "Record or update your checklist for this conversation. Pass the "
36
- "WHOLE list every time -- it replaces what was there, so include "
37
- "the items that have not changed. Use it for multi-step work the "
38
- "user can then see the shape of: plan the steps up front, mark one "
39
- "in_progress while you do it, and mark it completed before starting "
40
- "the next. Do not use it for single-step requests, where the list "
41
- "is noise."
42
- ),
43
- "input_schema": {
44
- "type": "object",
45
- "properties": {
46
- "items": {
47
- "type": "array",
48
- "description": f"The complete list, in order, at most "
49
- f"{config.MAX_TODO_ITEMS} items. An empty "
50
- f"list clears it.",
51
- "items": {
52
- "type": "object",
53
- "properties": {
54
- "content": {
55
- "type": "string",
56
- "description": "What the step is, imperative and "
57
- "short.",
58
- },
59
- "status": {
60
- "type": "string",
61
- "enum": list(config.TODO_STATUSES),
62
- "description": "Defaults to pending.",
63
- },
64
- },
65
- "required": ["content"],
66
- },
67
- },
68
- },
69
- "required": ["items"],
70
- },
71
- }
72
-
73
-
74
- def _normalise(raw) -> tuple:
75
- """Validate one list. Returns (items, error) -- exactly one is truthy.
76
-
77
- Every failure is an error result the model can correct, never an
78
- exception -- tools/base.py carries the one copy of why, under "WHAT A
79
- CALLABLE REGISTERED BELOW MAY RAISE". The short version is not the one
80
- this used to give: a raise here is CONTAINED, and what an error result
81
- buys is a message the model can act on instead of a generic wrapper
82
- (batch 146).
83
- """
84
- if not isinstance(raw, (list, tuple)):
85
- return None, ("todo_write requires 'items' to be a list of "
86
- "{content, status} objects.")
87
- if len(raw) > config.MAX_TODO_ITEMS:
88
- # REFUSED, not truncated. A list silently cut would leave the model
89
- # believing it had recorded work it can no longer see.
90
- return None, (f"todo_write allows at most {config.MAX_TODO_ITEMS} "
91
- f"items; {len(raw)} were given. Keep the list to the "
92
- f"work actually in hand.")
93
-
94
- items = []
95
- for index, entry in enumerate(raw, start=1):
96
- if not isinstance(entry, dict):
97
- return None, (f"todo_write item {index} is not an object with a "
98
- f"'content' field.")
99
- content = entry.get("content")
100
- if not content or not isinstance(content, str):
101
- return None, (f"todo_write item {index} needs a non-empty "
102
- f"'content' string.")
103
- status = entry.get("status") or "pending"
104
- if status not in config.TODO_STATUSES:
105
- # Names the offender and the vocabulary. A silent coercion to
106
- # pending would report success while losing the state the model
107
- # meant to record.
108
- return None, (
109
- f"todo_write item {index} has status {status!r}; expected one "
110
- f"of {', '.join(config.TODO_STATUSES)}.")
111
- items.append({"content": content.strip(), "status": status})
112
- return items, None
113
-
114
-
115
- def _summary(items: list) -> str:
116
- """One line, for the transcript and for the CLI, which has no panel."""
117
- if not items:
118
- return "todo list cleared"
119
- done = sum(1 for i in items if i["status"] == "completed")
120
- active = next((i["content"] for i in items
121
- if i["status"] == "in_progress"), None)
122
- head = f"todo {done}/{len(items)}"
123
- return f"{head} — {active}" if active else head
124
-
125
-
126
- def run(params: dict, memory=None) -> dict:
127
- items, error = _normalise(params.get("items"))
128
- if error:
129
- return {"error": error}
130
- if memory is None:
131
- # Reachable only if dispatched outside a run. An explained error
132
- # rather than a silent no-op reported as success: the model would
133
- # otherwise believe a plan is recorded when nothing is, which is
134
- # worse than not having the tool. pin.py's reasoning.
135
- return {"error": "todo_write is only available inside a conversation."}
136
-
137
- # THE WHOLE LIST, through set_extra, which persists write-through. Not
138
- # `memory.extra[...] = ...`: `extra` is a COPY (core/memory.py), so
139
- # mutating it changes nothing and reports success.
140
- memory.set_extra("todos", items)
141
-
142
- return {
143
- "result": {"items": items},
144
- # §23 slice 2's event route (J10). The loop forwards any `notice` on
145
- # a tool result as a LoopEvent and strips it, so this reaches the TUI
146
- # panel without a tool name appearing in core/loop.py. The panel
147
- # re-reads the list from thread state -- this only says WHEN.
148
- "notice": {"kind": "todo_changed", "text": _summary(items)},
149
- }
1
+ """
2
+ tools/builtin/todo.py
3
+
4
+ ROADMAP_v2 §23 slice 2: the todo list. "A model-maintained checklist,
5
+ persisted per thread."
6
+
7
+ WHOLE-LIST WRITE, NOT GRANULAR OPERATIONS (J13). One call replaces the list,
8
+ so it is always internally consistent, reordering is free, and no item is
9
+ ever addressed by name or index. Granular add/complete/remove would each need
10
+ a stable way to name one item -- which is the problem `clear_refs` refused to
11
+ solve ("a per-reference removal needs a stable way for a person to name one")
12
+ and the problem §21b's "removal is by id, never by substring" rule exists to
13
+ prevent. A model naming the wrong id silently mutates the wrong entry; a model
14
+ rewriting the list cannot.
15
+
16
+ STORED IN extra_data (J14), under its own key beside §18's goal and §21c's
17
+ refs. storage.py's `get_thread_extra` docstring has said "goal mode §18, todo
18
+ list §23" since §18, and §27's column-versus-extra_data argument was about
19
+ keeping `list_threads()` cheap -- a todo list is only ever read for the
20
+ current thread, so queryability buys nothing.
21
+
22
+ WORKS HEADLESS (J9). §23 AC2 says "both tools deny cleanly with no way to ask",
23
+ but that was written before this tool's shape was settled: the deny rule
24
+ exists because a blocking prompt nobody answers turns into a hang, and this
25
+ tool never blocks and never asks anyone anything. A ten-pass research run
26
+ keeping its own checklist is arguably where one helps most. It needs a
27
+ conversation, not a person.
28
+ """
29
+
30
+ import config
31
+
32
+ TOOL_SCHEMA = {
33
+ "name": "todo_write",
34
+ "description": (
35
+ "Record or update your checklist for this conversation. Pass the "
36
+ "WHOLE list every time -- it replaces what was there, so include "
37
+ "the items that have not changed. Use it for multi-step work the "
38
+ "user can then see the shape of: plan the steps up front, mark one "
39
+ "in_progress while you do it, and mark it completed before starting "
40
+ "the next. Do not use it for single-step requests, where the list "
41
+ "is noise."
42
+ ),
43
+ "input_schema": {
44
+ "type": "object",
45
+ "properties": {
46
+ "items": {
47
+ "type": "array",
48
+ "description": f"The complete list, in order, at most "
49
+ f"{config.MAX_TODO_ITEMS} items. An empty "
50
+ f"list clears it.",
51
+ "items": {
52
+ "type": "object",
53
+ "properties": {
54
+ "content": {
55
+ "type": "string",
56
+ "description": "What the step is, imperative and "
57
+ "short.",
58
+ },
59
+ "status": {
60
+ "type": "string",
61
+ "enum": list(config.TODO_STATUSES),
62
+ "description": "Defaults to pending.",
63
+ },
64
+ },
65
+ "required": ["content"],
66
+ },
67
+ },
68
+ },
69
+ "required": ["items"],
70
+ },
71
+ }
72
+
73
+
74
+ def _normalise(raw) -> tuple:
75
+ """Validate one list. Returns (items, error) -- exactly one is truthy.
76
+
77
+ Every failure is an error result the model can correct, never an
78
+ exception -- tools/base.py carries the one copy of why, under "WHAT A
79
+ CALLABLE REGISTERED BELOW MAY RAISE". The short version is not the one
80
+ this used to give: a raise here is CONTAINED, and what an error result
81
+ buys is a message the model can act on instead of a generic wrapper
82
+ (batch 146).
83
+ """
84
+ if not isinstance(raw, (list, tuple)):
85
+ return None, ("todo_write requires 'items' to be a list of "
86
+ "{content, status} objects.")
87
+ if len(raw) > config.MAX_TODO_ITEMS:
88
+ # REFUSED, not truncated. A list silently cut would leave the model
89
+ # believing it had recorded work it can no longer see.
90
+ return None, (f"todo_write allows at most {config.MAX_TODO_ITEMS} "
91
+ f"items; {len(raw)} were given. Keep the list to the "
92
+ f"work actually in hand.")
93
+
94
+ items = []
95
+ for index, entry in enumerate(raw, start=1):
96
+ if not isinstance(entry, dict):
97
+ return None, (f"todo_write item {index} is not an object with a "
98
+ f"'content' field.")
99
+ content = entry.get("content")
100
+ if not content or not isinstance(content, str):
101
+ return None, (f"todo_write item {index} needs a non-empty "
102
+ f"'content' string.")
103
+ status = entry.get("status") or "pending"
104
+ if status not in config.TODO_STATUSES:
105
+ # Names the offender and the vocabulary. A silent coercion to
106
+ # pending would report success while losing the state the model
107
+ # meant to record.
108
+ return None, (
109
+ f"todo_write item {index} has status {status!r}; expected one "
110
+ f"of {', '.join(config.TODO_STATUSES)}.")
111
+ items.append({"content": content.strip(), "status": status})
112
+ return items, None
113
+
114
+
115
+ def _summary(items: list) -> str:
116
+ """One line, for the transcript and for the CLI, which has no panel."""
117
+ if not items:
118
+ return "todo list cleared"
119
+ done = sum(1 for i in items if i["status"] == "completed")
120
+ active = next((i["content"] for i in items
121
+ if i["status"] == "in_progress"), None)
122
+ head = f"todo {done}/{len(items)}"
123
+ return f"{head} — {active}" if active else head
124
+
125
+
126
+ def run(params: dict, memory=None) -> dict:
127
+ items, error = _normalise(params.get("items"))
128
+ if error:
129
+ return {"error": error}
130
+ if memory is None:
131
+ # Reachable only if dispatched outside a run. An explained error
132
+ # rather than a silent no-op reported as success: the model would
133
+ # otherwise believe a plan is recorded when nothing is, which is
134
+ # worse than not having the tool. pin.py's reasoning.
135
+ return {"error": "todo_write is only available inside a conversation."}
136
+
137
+ # THE WHOLE LIST, through set_extra, which persists write-through. Not
138
+ # `memory.extra[...] = ...`: `extra` is a COPY (core/memory.py), so
139
+ # mutating it changes nothing and reports success.
140
+ memory.set_extra("todos", items)
141
+
142
+ return {
143
+ "result": {"items": items},
144
+ # §23 slice 2's event route (J10). The loop forwards any `notice` on
145
+ # a tool result as a LoopEvent and strips it, so this reaches the TUI
146
+ # panel without a tool name appearing in core/loop.py. The panel
147
+ # re-reads the list from thread state -- this only says WHEN.
148
+ "notice": {"kind": "todo_changed", "text": _summary(items)},
149
+ }