@yahyahammad/venastine 0.1.0 → 0.2.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.
package/core/replay.py CHANGED
@@ -1,167 +1,183 @@
1
- """
2
- core/replay.py
3
-
4
- Turns a stored thread back into something a shell can display
5
- (ROADMAP_v2 §27, bug 1).
6
-
7
- WHY THIS EXISTS AT ALL. Resuming a thread loaded its history correctly and
8
- showed NOTHING: `ConversationMemory(thread_id=...)` reads the full history
9
- at construction, but the TUI's picker callback swapped the object and wrote
10
- one line, and `main.py --thread` printed "Resuming thread: <uuid>" and
11
- dropped straight into the prompt. In the TUI it was worse than blank -- the
12
- PREVIOUS thread's transcript stayed on screen under the new thread's id, so
13
- the screen actively lied about which conversation was loaded.
14
-
15
- WHY IT IS ONE FUNCTION AND NOT TWO RENDERERS. D12 makes the CLI a permanent
16
- fallback, so both shells replay (§27 T5, §26's L6 again). What may be shown,
17
- and in what form, is a policy decision that must not differ between them --
18
- so the policy lives here and each shell only decides how to paint the
19
- entries it is handed. §26 spent a decision (L2, "one translation site") on
20
- exactly this shape.
21
-
22
- THE ARCHIVE, NEVER THE DERIVED VIEW (T3). `storage.archive_history()`
23
- returns every message ever written, compaction or not.
24
- `ConversationMemory.messages` on a compacted thread BEGINS with the
25
- synthesized summary that §21's M8 says must never be mistaken for something
26
- a person said -- and replaying it would render harness-generated text under
27
- a `you ›` label, which is precisely the mistake M8 exists to prevent. It
28
- also means a replayed thread shows what was originally said rather than a
29
- condensation of it, which is what a human resuming a conversation is looking
30
- for.
31
-
32
- THE LIVE VIEW SHOWS MORE THAN THIS ONE, DELIBERATELY (§41). Since batch 41
33
- the TUI renders a `write` or an `edit` as an inline diff, and a REPLAYED one
34
- here still shows `param_digest`. That is not a gap to close: a replay reads
35
- the archive, which records what was called and never what the file held at
36
- the time, so the digest is genuinely all this function has. The live view is
37
- better informed because it was there.
38
-
39
- REASONING IS REPLAYED, SINCE §44. §38 captured thinking for display and
40
- persisted none of it, so reopening a thread showed the answers with the
41
- reasoning silently missing -- the same conversation rendered two different
42
- ways depending on whether the session had been closed. The blocks are
43
- stored now (storage.MessageLog.thinking) and _reasoning_text pulls the
44
- prose back out of them. What a shell does with the entry is still the
45
- shell's: the TUI honours tui.show_thinking, because that is a display
46
- setting rather than a fact about the thread.
47
-
48
- TOOL RESULTS ARE SKIPPED, TOOL CALLS ARE ONE LINE (T4). A grounding-heavy
49
- thread carries hundreds of kilobytes of fetched page text in its
50
- `tool_result` rows; replaying that would bury the conversation in the
51
- material the conversation was about. The call is what says what happened,
52
- and `param_digest` says WHICH url or query -- redacted, because a tool
53
- argument can carry a credential and this is now the third place one could
54
- surface.
55
- """
56
-
57
- from __future__ import annotations
58
-
59
- from typing import List, Optional, Tuple
60
- from uuid import UUID
61
-
62
- from tools.registry import registry
63
- from storage import archive_history
64
-
65
- #: One replayed entry: (role, text). The roles are transcript palette roles
66
- #: (tui/themes.role_styles), so the TUI can paint them with what it already
67
- #: has and the CLI can label them. Deliberately NOT the neutral message
68
- #: shape -- a caller of this function is rendering, not reasoning about
69
- #: history, and handing it messages would invite a second policy decision
70
- #: about tool results at the call site.
71
- ReplayEntry = Tuple[str, str]
72
-
73
-
74
- def replay_entries(thread_id: UUID) -> List[ReplayEntry]:
75
- """A stored thread as display entries, oldest first (§27 T3/T4).
76
-
77
- Empty for a thread with no messages -- a `/new` thread that was never
78
- used is a real state, and the shells write their own "nothing here yet"
79
- line rather than this function inventing one.
80
- """
81
- entries: List[ReplayEntry] = []
82
- for message in archive_history(thread_id):
83
- role = message.get("role")
84
- if role == "user":
85
- text = _as_text(message.get("content"))
86
- if text:
87
- entries.append(("user", text))
88
- elif role == "assistant":
89
- # BEFORE the answer, because that is the order it happened in
90
- # and the order the live transcript drew it in (§43 RM1 puts
91
- # one `venastine ›` above whichever came first). A replay that
92
- # reordered the turn would be the same defect as one that
93
- # reflowed it.
94
- reasoning = _reasoning_text(message.get("thinking"))
95
- if reasoning:
96
- entries.append(("thinking", reasoning))
97
- text = _as_text(message.get("text"))
98
- if text:
99
- entries.append(("assistant", text))
100
- for call in message.get("tool_calls") or []:
101
- entries.append(("tool", _tool_marker(call)))
102
- # role == "tool": skipped by T4. Not a gap -- see the module
103
- # docstring. The CALL above is the record that it happened.
104
- return entries
105
-
106
-
107
- def _reasoning_text(record) -> str:
108
- """The displayable prose out of a stored thinking record (§44).
109
-
110
- The record holds the PROVIDER'S blocks, because that is what goes back
111
- on the wire; this is the other half of the same data, for a human. Two
112
- shapes reach here -- Anthropic's `thinking` blocks and the
113
- v1-compatible `reasoning_content` one -- and both are read by field
114
- name rather than by provider, so a third costs a name and not a
115
- branch.
116
-
117
- `redacted_thinking` contributes NOTHING and that is correct: it is
118
- opaque ciphertext meaningful only to the model, so rendering it would
119
- put a wall of base64 under a `venastine ›` label. It still travels on
120
- the wire; this function is about what a person sees.
121
- """
122
- if not isinstance(record, dict):
123
- return ""
124
- parts = []
125
- for block in record.get("blocks") or []:
126
- if not isinstance(block, dict):
127
- continue
128
- value = block.get("thinking") or block.get("text")
129
- if isinstance(value, str) and value.strip():
130
- parts.append(value.strip())
131
- return "\n\n".join(parts)
132
-
133
-
134
- def _tool_marker(call: dict) -> str:
135
- """One line for one tool call: name, then a redacted param digest.
136
-
137
- The digest comes from `registry.call_digest` rather than from a
138
- local copy -- it redacts BEFORE truncating, and a second
139
- implementation is how that ordering regresses in one place and
140
- not the other (§27's note on _param_digest, and the project's
141
- canonical producer/consumer bug).
142
-
143
- Through the REGISTRY since §42 (RA3), not `param_digest` direct,
144
- because dropping a tool's declared rationale param is part of the
145
- same rule and belongs at the same producer. Importing the registry
146
- here costs nothing measurable: `main.py` is this module's only
147
- caller and has already imported it, so it is in `sys.modules`
148
- (1.9s cold at process start, 0.0s here).
149
- """
150
- name = call.get("name") or "tool"
151
- digest = registry.call_digest(name, call.get("input"))
152
- # Standardised to ▸ like the live transcript (tui/app.py both modes).
153
- # Replay stays redacted via param_digest, same producer as live.
154
- return f"▸ {name} {digest}".rstrip() if digest else f"▸ {name}"
155
-
156
-
157
- def _as_text(value: Optional[object]) -> str:
158
- """Message content as a displayable string.
159
-
160
- `content` is whatever was persisted through json.dumps, so it is
161
- normally a string but need not be; str() rather than a type assertion,
162
- because a replay that raises on one odd row would take the whole resumed
163
- conversation with it.
164
- """
165
- if value is None:
166
- return ""
167
- return value.strip() if isinstance(value, str) else str(value)
1
+ """
2
+ core/replay.py
3
+
4
+ Turns a stored thread back into something a shell can display
5
+ (ROADMAP_v2 §27, bug 1).
6
+
7
+ WHY THIS EXISTS AT ALL. Resuming a thread loaded its history correctly and
8
+ showed NOTHING: `ConversationMemory(thread_id=...)` reads the full history
9
+ at construction, but the TUI's picker callback swapped the object and wrote
10
+ one line, and `main.py --thread` printed "Resuming thread: <uuid>" and
11
+ dropped straight into the prompt. In the TUI it was worse than blank -- the
12
+ PREVIOUS thread's transcript stayed on screen under the new thread's id, so
13
+ the screen actively lied about which conversation was loaded.
14
+
15
+ WHY IT IS ONE FUNCTION AND NOT TWO RENDERERS. D12 makes the CLI a permanent
16
+ fallback, so both shells replay (§27 T5, §26's L6 again). What may be shown,
17
+ and in what form, is a policy decision that must not differ between them --
18
+ so the policy lives here and each shell only decides how to paint the
19
+ entries it is handed. §26 spent a decision (L2, "one translation site") on
20
+ exactly this shape.
21
+
22
+ THE ARCHIVE, NEVER THE DERIVED VIEW (T3). `storage.archive_history()`
23
+ returns every message ever written, compaction or not.
24
+ `ConversationMemory.messages` on a compacted thread BEGINS with the
25
+ synthesized summary that §21's M8 says must never be mistaken for something
26
+ a person said -- and replaying it would render harness-generated text under
27
+ a `you ›` label, which is precisely the mistake M8 exists to prevent. It
28
+ also means a replayed thread shows what was originally said rather than a
29
+ condensation of it, which is what a human resuming a conversation is looking
30
+ for.
31
+
32
+ THE LIVE VIEW SHOWS MORE THAN THIS ONE, DELIBERATELY (§41). Since batch 41
33
+ the TUI renders a `write` or an `edit` as an inline diff, and a REPLAYED one
34
+ here still shows `param_digest`. That is not a gap to close: a replay reads
35
+ the archive, which records what was called and never what the file held at
36
+ the time, so the digest is genuinely all this function has. The live view is
37
+ better informed because it was there.
38
+
39
+ REASONING IS REPLAYED, SINCE §44. §38 captured thinking for display and
40
+ persisted none of it, so reopening a thread showed the answers with the
41
+ reasoning silently missing -- the same conversation rendered two different
42
+ ways depending on whether the session had been closed. The blocks are
43
+ stored now (storage.MessageLog.thinking) and _reasoning_text pulls the
44
+ prose back out of them. What a shell does with the entry is still the
45
+ shell's: the TUI honours tui.show_thinking, because that is a display
46
+ setting rather than a fact about the thread.
47
+
48
+ TOOL RESULTS ARE SKIPPED, TOOL CALLS ARE ONE LINE (T4). A grounding-heavy
49
+ thread carries hundreds of kilobytes of fetched page text in its
50
+ `tool_result` rows; replaying that would bury the conversation in the
51
+ material the conversation was about. The call is what says what happened,
52
+ and `param_digest` says WHICH url or query -- redacted, because a tool
53
+ argument can carry a credential and this is now the third place one could
54
+ surface.
55
+ """
56
+
57
+ from __future__ import annotations
58
+
59
+ from typing import List, Optional, Tuple
60
+ from uuid import UUID
61
+
62
+ from tools.registry import registry
63
+ from storage import archive_history
64
+
65
+ #: One replayed entry: (role, text, links). The roles are transcript palette
66
+ #: roles (tui/themes.role_styles), so the TUI can paint them with what it
67
+ #: already has and the CLI can label them. Deliberately NOT the neutral
68
+ #: message shape -- a caller of this function is rendering, not reasoning
69
+ #: about history, and handing it messages would invite a second policy
70
+ #: decision about tool results at the call site.
71
+ #:
72
+ #: `links` is batch 65's, and it does not narrow the sentence above: a
73
+ #: click target is a RENDERING fact about a line, not part of what was
74
+ #: said. It is here because the alternative is worse -- a tool line's
75
+ #: digest truncates a long URL, so without it a resumed thread would draw
76
+ #: the same characters as a live turn and quietly refuse to open them,
77
+ #: which is the one conversation rendered two ways that Section 44 removed
78
+ #: for thinking spans. Empty for every entry that is not a tool call.
79
+ ReplayEntry = Tuple[str, str, Tuple[str, ...]]
80
+
81
+
82
+ def replay_entries(thread_id: UUID) -> List[ReplayEntry]:
83
+ """A stored thread as display entries, oldest first (§27 T3/T4).
84
+
85
+ Empty for a thread with no messages -- a `/new` thread that was never
86
+ used is a real state, and the shells write their own "nothing here yet"
87
+ line rather than this function inventing one.
88
+ """
89
+ entries: List[ReplayEntry] = []
90
+ for message in archive_history(thread_id):
91
+ role = message.get("role")
92
+ if role == "user":
93
+ text = _as_text(message.get("content"))
94
+ if text:
95
+ entries.append(("user", text, ()))
96
+ elif role == "assistant":
97
+ # BEFORE the answer, because that is the order it happened in
98
+ # and the order the live transcript drew it in (§43 RM1 puts
99
+ # one `venastine ›` above whichever came first). A replay that
100
+ # reordered the turn would be the same defect as one that
101
+ # reflowed it.
102
+ reasoning = _reasoning_text(message.get("thinking"))
103
+ if reasoning:
104
+ entries.append(("thinking", reasoning, ()))
105
+ text = _as_text(message.get("text"))
106
+ if text:
107
+ entries.append(("assistant", text, ()))
108
+ for call in message.get("tool_calls") or []:
109
+ entries.append(("tool", *_tool_marker(call)))
110
+ # role == "tool": skipped by T4. Not a gap -- see the module
111
+ # docstring. The CALL above is the record that it happened.
112
+ return entries
113
+
114
+
115
+ def _reasoning_text(record) -> str:
116
+ """The displayable prose out of a stored thinking record (§44).
117
+
118
+ The record holds the PROVIDER'S blocks, because that is what goes back
119
+ on the wire; this is the other half of the same data, for a human. Two
120
+ shapes reach here -- Anthropic's `thinking` blocks and the
121
+ v1-compatible `reasoning_content` one -- and both are read by field
122
+ name rather than by provider, so a third costs a name and not a
123
+ branch.
124
+
125
+ `redacted_thinking` contributes NOTHING and that is correct: it is
126
+ opaque ciphertext meaningful only to the model, so rendering it would
127
+ put a wall of base64 under a `venastine ›` label. It still travels on
128
+ the wire; this function is about what a person sees.
129
+ """
130
+ if not isinstance(record, dict):
131
+ return ""
132
+ parts = []
133
+ for block in record.get("blocks") or []:
134
+ if not isinstance(block, dict):
135
+ continue
136
+ value = block.get("thinking") or block.get("text")
137
+ if isinstance(value, str) and value.strip():
138
+ parts.append(value.strip())
139
+ return "\n\n".join(parts)
140
+
141
+
142
+ def _tool_marker(call: dict) -> Tuple[str, Tuple[str, ...]]:
143
+ """One line for one tool call, and its click targets.
144
+
145
+ The line is the name, then a redacted param digest.
146
+
147
+ The digest comes from `registry.call_digest` rather than from a
148
+ local copy -- it redacts BEFORE truncating, and a second
149
+ implementation is how that ordering regresses in one place and
150
+ not the other (§27's note on _param_digest, and the project's
151
+ canonical producer/consumer bug).
152
+
153
+ Through the REGISTRY since §42 (RA3), not `param_digest` direct,
154
+ because dropping a tool's declared rationale param is part of the
155
+ same rule and belongs at the same producer. Importing the registry
156
+ here costs nothing measurable: `main.py` is this module's only
157
+ caller and has already imported it, so it is in `sys.modules`
158
+ (1.9s cold at process start, 0.0s here).
159
+ """
160
+ name = call.get("name") or "tool"
161
+ params = call.get("input")
162
+ digest = registry.call_digest(name, params)
163
+ # Standardised to ▸ like the live transcript (tui/app.py both modes).
164
+ # Replay stays redacted via param_digest, same producer as live.
165
+ #
166
+ # And the click targets from the same producer for the same reason
167
+ # (batch 65): a resumed thread that armed fewer URLs than the live
168
+ # turn would be the archive disagreeing with the screen it came from.
169
+ line = f"▸ {name} {digest}".rstrip() if digest else f"▸ {name}"
170
+ return line, registry.call_links(name, params)
171
+
172
+
173
+ def _as_text(value: Optional[object]) -> str:
174
+ """Message content as a displayable string.
175
+
176
+ `content` is whatever was persisted through json.dumps, so it is
177
+ normally a string but need not be; str() rather than a type assertion,
178
+ because a replay that raises on one odd row would take the whole resumed
179
+ conversation with it.
180
+ """
181
+ if value is None:
182
+ return ""
183
+ return value.strip() if isinstance(value, str) else str(value)
package/main.py CHANGED
@@ -89,7 +89,9 @@ def _print_replay(thread_id: UUID) -> None:
89
89
  print("(this thread has no messages yet)")
90
90
  return
91
91
  print()
92
- for role, text in entries:
92
+ # `links` is the TUI's -- a ctrl+click target for a truncated URL
93
+ # (batch 65). This shell prints, so it drops them.
94
+ for role, text, _links in entries:
93
95
  if role == "user":
94
96
  print(f"You: {text}")
95
97
  elif role == "assistant":
@@ -94,7 +94,14 @@ def _cmd_summary(app, args: str) -> None:
94
94
  from core import compaction
95
95
  try:
96
96
  notice = compaction.summarize_thread(
97
- memory.thread_id, app.model, app.provider_name)
97
+ memory.thread_id, app.model, app.provider_name,
98
+ # Batch 59. /summary runs the compactor with
99
+ # nothing above it, so depth 0 -- it IS the stack.
100
+ # getattr: these commands are driven against stub apps
101
+ # in the suite (tests/test_thread_refs.py), and a
102
+ # summary must not depend on a sidebar widget
103
+ # existing. None is a fully supported sink.
104
+ activity=getattr(app, "_activity", None), depth=0)
98
105
  except Exception as e: # noqa: BLE001 — same containment as /compact
99
106
  app.call_from_thread(
100
107
  app._transcript.write_error, f"Summary failed: {e}")
@@ -193,7 +200,12 @@ def _attach_in_worker(app, thread_id, threads) -> None:
193
200
  def _work() -> None:
194
201
  try:
195
202
  notice = compaction.summarize_thread(
196
- thread_id, app.model, app.provider_name)
203
+ thread_id, app.model, app.provider_name,
204
+ # getattr: these commands are driven against stub apps
205
+ # in the suite (tests/test_thread_refs.py), and a
206
+ # summary must not depend on a sidebar widget
207
+ # existing. None is a fully supported sink.
208
+ activity=getattr(app, "_activity", None), depth=0)
197
209
  except Exception as e: # noqa: BLE001
198
210
  app.call_from_thread(
199
211
  app._transcript.write_error, f"Reference failed: {e}")
package/package.json CHANGED
@@ -1,73 +1,73 @@
1
- {
2
- "name": "@yahyahammad/venastine",
3
- "version": "0.1.0",
4
- "description": "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline.",
5
- "keywords": [
6
- "agent",
7
- "llm",
8
- "research",
9
- "anthropic",
10
- "openai",
11
- "mcp"
12
- ],
13
- "homepage": "https://github.com/YahyaHammad/Venastine-Research-Harness#readme",
14
- "bugs": {
15
- "url": "https://github.com/YahyaHammad/Venastine-Research-Harness/issues"
16
- },
17
- "repository": {
18
- "type": "git",
19
- "url": "git+https://github.com/YahyaHammad/Venastine-Research-Harness.git"
20
- },
21
- "license": "Apache-2.0",
22
- "author": "Yahya Hammad",
23
- "type": "module",
24
- "bin": {
25
- "venastine": "bin/venastine.mjs"
26
- },
27
- "engines": {
28
- "node": ">=18"
29
- },
30
- "publishConfig": {
31
- "access": "public"
32
- },
33
- "scripts": {
34
- "prepublishOnly": "node scripts/prepublish-check.mjs",
35
- "check-pack": "node scripts/prepublish-check.mjs"
36
- },
37
- "files": [
38
- "bin/",
39
- "main.py",
40
- "config.py",
41
- "storage.py",
42
- "database.py",
43
- "credentials.py",
44
- "env_secrets.py",
45
- "logging_setup.py",
46
- "json_store.py",
47
- "core/",
48
- "tools/",
49
- "tui/",
50
- "agents/",
51
- "skills/",
52
- "prompts/",
53
- "mcp_client/",
54
- "security/",
55
- "safety/",
56
- "memories/",
57
- "project_init/",
58
- "requirements.txt",
59
- "pyproject.toml",
60
- "README.md",
61
- "LICENSE",
62
- "NOTICE",
63
- "THIRD_PARTY_NOTICES.md",
64
- "SECURITY.md",
65
- "PRIVACY.md",
66
- "providers.json.example",
67
- ".env.example",
68
- "!**/__pycache__",
69
- "!**/*.pyc",
70
- "!**/.ipynb_checkpoints",
71
- "!**/.pytest_cache"
72
- ]
73
- }
1
+ {
2
+ "name": "@yahyahammad/venastine",
3
+ "version": "0.2.0",
4
+ "description": "A from-scratch agentic harness: tool-using chat plus a ten-pass self-critiquing research pipeline.",
5
+ "keywords": [
6
+ "agent",
7
+ "llm",
8
+ "research",
9
+ "anthropic",
10
+ "openai",
11
+ "mcp"
12
+ ],
13
+ "homepage": "https://github.com/YahyaHammad/Venastine-Research-Harness#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/YahyaHammad/Venastine-Research-Harness/issues"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/YahyaHammad/Venastine-Research-Harness.git"
20
+ },
21
+ "license": "Apache-2.0",
22
+ "author": "Yahya Hammad",
23
+ "type": "module",
24
+ "bin": {
25
+ "venastine": "bin/venastine.mjs"
26
+ },
27
+ "engines": {
28
+ "node": ">=18"
29
+ },
30
+ "publishConfig": {
31
+ "access": "public"
32
+ },
33
+ "scripts": {
34
+ "prepublishOnly": "node scripts/prepublish-check.mjs",
35
+ "check-pack": "node scripts/prepublish-check.mjs"
36
+ },
37
+ "files": [
38
+ "bin/",
39
+ "main.py",
40
+ "config.py",
41
+ "storage.py",
42
+ "database.py",
43
+ "credentials.py",
44
+ "env_secrets.py",
45
+ "logging_setup.py",
46
+ "json_store.py",
47
+ "core/",
48
+ "tools/",
49
+ "tui/",
50
+ "agents/",
51
+ "skills/",
52
+ "prompts/",
53
+ "mcp_client/",
54
+ "security/",
55
+ "safety/",
56
+ "memories/",
57
+ "project_init/",
58
+ "requirements.txt",
59
+ "pyproject.toml",
60
+ "README.md",
61
+ "LICENSE",
62
+ "NOTICE",
63
+ "THIRD_PARTY_NOTICES.md",
64
+ "SECURITY.md",
65
+ "PRIVACY.md",
66
+ "providers.json.example",
67
+ ".env.example",
68
+ "!**/__pycache__",
69
+ "!**/*.pyc",
70
+ "!**/.ipynb_checkpoints",
71
+ "!**/.pytest_cache"
72
+ ]
73
+ }