@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/README.md CHANGED
@@ -1,3 +1,5 @@
1
+ ![Venastine Research Harness Screenshot](Venastine_Research_Harness_Demo_Photo.png)
2
+
1
3
  # Venastine Research Harness
2
4
 
3
5
  An agentic harness built from scratch — no LangChain, no agent framework — with two modes that share the same machinery:
@@ -22,6 +24,12 @@ npm install -g @yahyahammad/venastine
22
24
  venastine
23
25
  ```
24
26
 
27
+ For the full TUI experience you can use:
28
+ ```bash
29
+ venastine --tui
30
+ ```
31
+
32
+
25
33
  **npm handles the setup for you.** It delivers the harness as a folder of source — there is no bundled binary — and Python still runs it, so the only prerequisite you provide is an interpreter on PATH. Everything after that happens on first launch: the launcher finds a suitable Python, tells you which one and what it is about to install, and builds an isolated environment with the pinned dependencies once you agree. It asks every time it would install something, never installs during `npm install` itself, and refuses rather than proceeding when there is no terminal to ask in.
26
34
 
27
35
  Two things differ from a clone, both to make a command you run from anywhere behave sensibly:
@@ -587,8 +595,17 @@ The first connection to a **user-level** server asks once, showing the resolved
587
595
  | `/summary` | Distil this conversation and show it. Describes; does **not** fold — that is `/compact` |
588
596
  | `/ref [--list\|--clear]` | Pick another conversation and attach its summary to this one as standing context; `--list` and `--clear` manage attachments |
589
597
  | `/init [--software\|--research] [--config]` | Scaffold the project documentation set; `--config` adds `.venastine/settings.json` and `mcp.json` with default values, and on its own is the whole command |
598
+ | `/quit` | Leave the harness, on one invocation — a typed command is already deliberate. `/exit` and `/bye` are the same command under other names; type toward either and the suggestion list says so |
599
+
600
+ Keys: **ctrl+c** twice quits — the first press arms it and the footer changes to say so, and it goes back to `Quit` after a couple of seconds; a **ctrl+c** over selected text copies instead and arms nothing, so nothing you copy can end the session. **ctrl+q** quits on a single press, from anywhere, including under a dialog · **ctrl+t** thread picker · **ctrl+l** claims view · **ctrl+j** (or **shift+enter**) newline in the prompt · **up/down** and **enter**/**tab** to pick a slash command, **escape** to dismiss the list · **ctrl+click** a URL in an answer — or in a tool line — to open it.
601
+
602
+ Answers are rendered rather than printed as their source: tables become grids, headings and `**bold**` take weight, `*emphasis*` and `~~strike~~` take their own marks, code fences are highlighted, and a list item that runs past the edge wraps **under its own text** instead of back to the margin. A line indented four spaces or more is left exactly as written, so a code sample keeps its operators and its `#` comments. What is deliberately not rendered: block quotes, horizontal rules, heading *levels* (a `#` and a `######` look the same), and anything at all inside a reasoning block. `/copy` always hands back the markdown the model wrote — the rendering is what the screen does, never what is stored.
603
+
604
+ **A link can never hide where it goes.** `[the docs](https://example.com)` draws every character it was written with, and the only clickable thing on the row is the URL itself — so a model cannot present one destination and open another. Ctrl+click opens it, in `http`/`https` only, and only when the URL is plain ASCII: a lookalike address built from non-Latin characters still renders and still copies, but will not open on a click. Nor will an address that carries a username before its host — `https://accounts.google.com@else.example/x` goes to `else.example`, so the part you read as the destination has to *be* the destination — and nor will one the harness rewrote to hide a secret in it. The same is true of the `▸ fetch_url https://…` line: where that line shortens a long address, the click still opens the whole one, and the part shown always reaches the end of the site name, so what you can read is where you will land.
605
+
606
+ The prompt box wraps and grows to four lines as you type, then drops back to one when you send, so a long question can be read back before it goes. A line that runs past the edge wraps on its own — `ctrl+j` is for a break you actually want. `shift+enter` does the same where your terminal can send it, which in practice means kitty, ghostty, WezTerm, or any terminal configured to emit a newline for that chord; elsewhere it arrives as a plain Enter and sends the message, so `ctrl+j` is the one to reach for.
590
607
 
591
- Keys: **ctrl+c** quit · **ctrl+t** thread picker · **ctrl+l** claims view.
608
+ Type `/` and the commands appear above the prompt — name, description and flags, narrowing as you type and coming back if you delete. Arrow up and down to move the highlight — the list scrolls, so every matching command is reachable, not just the ones on screen; **enter** or **tab** fills the command in **without sending it**, so you can still add arguments, and a second **enter** runs it. **escape** puts the list away. The list is the same one `/help` prints, so nothing can go stale, and the panel's title says how many of the matches fit on screen.
592
609
 
593
610
  Three behaviours worth knowing: an unknown slash command is an error, never a chat turn — a mistyped command cannot silently burn a request. `/effort` and `/thinking` persist nothing, so make those stick through settings.json or launch flags; `/theme`, `/model`, `/critic` and `/embedder` are the exceptions — they are remembered for the next launch, in files of their own beside settings.json rather than by rewriting it. And the commands that spend money or swap models mid-session (`/compact`, `/summary`, `/research`, `/init`, `/model`, `/critic`, `/embedder`, `/grill-me`) refuse while a turn is still running rather than acting underneath it.
594
611
 
@@ -850,7 +867,7 @@ classifier is described under *Security model* above. If you have a fork or a lo
850
867
  note that `ToolApprovals.shell` now ships `False` and `SHELL_APPROVAL_MODE` is the gate — see
851
868
  `tests/BREAKING_CHANGES.md` §24.
852
869
 
853
- Run the test suite with `pytest` — 3510 tests, fully offline, no API keys needed. One further test is marked `integration` and excluded by default; it spawns a real stdio MCP server (`pytest -m integration`).
870
+ Run the test suite with `pytest` — 4045 tests, fully offline, no API keys needed. One further test is marked `integration` and excluded by default; it spawns a real stdio MCP server (`pytest -m integration`).
854
871
 
855
872
  ## Documentation
856
873
 
@@ -19,6 +19,7 @@ imports this module to register it, and core.loop imports tools.registry
19
19
  """
20
20
 
21
21
  import config
22
+ from core import agent_activity
22
23
  from storage import THREAD_KIND_SUBAGENT
23
24
  from tools.context import ToolContext
24
25
 
@@ -132,7 +133,7 @@ def request_payload(params: dict, context=None) -> dict:
132
133
 
133
134
 
134
135
  def run(params: dict, parent_context=None, parent_run=None,
135
- response_channel=None, signoff=None) -> dict:
136
+ response_channel=None, signoff=None, activity=None) -> dict:
136
137
  from core.loop import (
137
138
  RunAgentLoop, DEFAULT_PROVIDER, DEFAULT_SYSTEM_PROMPT,
138
139
  )
@@ -184,31 +185,53 @@ def run(params: dict, parent_context=None, parent_run=None,
184
185
  or DEFAULT_PROVIDER
185
186
  effort = parent_run.effort if parent_run else None
186
187
 
187
- response = RunAgentLoop.run_agent_conversation(
188
- user_goal=task,
189
- model=model,
190
- provider_name=provider,
191
- max_steps=agent.max_steps or config.MAX_ITERATIONS,
192
- context=child,
193
- effort=effort,
194
- # `child`, not the agent's own context: C6 intersects with the
195
- # parent, so a parent that excluded spawn_subagent must not have
196
- # the catalog re-invite its child to spawn one (review f19).
197
- # #68: the child's own facts, not the parent's. A subagent
198
- # spawned from a headless run inherits no channel, so its
199
- # catalogs must be decided by what IT can call -- the same
200
- # values handed to run_agent_conversation two lines below.
201
- system_prompt=manager.system_prompt_for(
202
- agent, DEFAULT_SYSTEM_PROMPT, context=child,
203
- callable_only=response_channel is None,
204
- granted=granted),
205
- response_channel=response_channel,
206
- granted_tools=granted if (response_channel is not None
207
- and granted) else None,
208
- # §27 AC1. A spawned agent's thread is not a conversation anyone
209
- # will resume, and one goal-mode turn can spawn several.
210
- thread_kind=THREAD_KIND_SUBAGENT,
211
- )
188
+ # Batch 59. THE SPAN AND THE PASS-DOWN ARE ONE CHANGE, and the
189
+ # pass-down is the half that does the work: `activity=activity` on the
190
+ # call below is what lets the child's OWN spawn_subagent open a span
191
+ # too, so a shell sees depth 2 rather than only the spawn it can
192
+ # already infer from tool_call_start. Without it this reports exactly
193
+ # what the TUI knew before the batch.
194
+ #
195
+ # A context manager rather than a pair of calls, because the exit has
196
+ # to happen when the child RAISES -- a provider error inside a
197
+ # subagent must not leave a row on screen describing a run that is
198
+ # over. run_agent_conversation does not contain its own exceptions
199
+ # (core/events.py: "exceptions raised mid-loop propagate naturally"),
200
+ # so this is a reachable path rather than a defensive one.
201
+ #
202
+ # `child.subagent_depth` and not a local count: C3 already maintains
203
+ # that number and a second one would be free to disagree with it.
204
+ with agent_activity.span(activity, agent.name, child.subagent_depth):
205
+ response = RunAgentLoop.run_agent_conversation(
206
+ user_goal=task,
207
+ model=model,
208
+ provider_name=provider,
209
+ max_steps=agent.max_steps or config.MAX_ITERATIONS,
210
+ context=child,
211
+ effort=effort,
212
+ # `child`, not the agent's own context: C6 intersects with
213
+ # the parent, so a parent that excluded spawn_subagent must not
214
+ # have the catalog re-invite its child to spawn one (review
215
+ # f19).
216
+ # #68: the child's own facts, not the parent's. A subagent
217
+ # spawned from a headless run inherits no channel, so its
218
+ # catalogs must be decided by what IT can call -- the same
219
+ # values handed to run_agent_conversation two lines below.
220
+ system_prompt=manager.system_prompt_for(
221
+ agent, DEFAULT_SYSTEM_PROMPT, context=child,
222
+ callable_only=response_channel is None,
223
+ granted=granted),
224
+ response_channel=response_channel,
225
+ granted_tools=granted if (response_channel is not None
226
+ and granted) else None,
227
+ # §27 AC1. A spawned agent's thread is not a conversation
228
+ # anyone will resume, and one goal-mode turn can spawn several.
229
+ thread_kind=THREAD_KIND_SUBAGENT,
230
+ # The recursion. Inherited exactly as response_channel is, and
231
+ # for the same reason: the child is a run in its own right and
232
+ # whatever is watching this stack is watching that one too.
233
+ activity=activity,
234
+ )
212
235
  return {
213
236
  "result": response.text,
214
237
  "subagent_thread_id": str(response.thread_id),
@@ -1,10 +1,10 @@
1
1
  """
2
2
  agents/tui_commands.py
3
3
 
4
- ROADMAP_v2 §18, D6 user-initiated half: /agent, /goal and /grill-me
5
- register into §16's slash registry. The shell hosts the commands; this
4
+ ROADMAP_v2 §18, D6 user-initiated half: /agent, /goal and /grill-me
5
+ register into §16's slash registry. The shell hosts the commands; this
6
6
  section owns them -- the same mechanism-vs-policy split tools/registry.py
7
- uses for tools. TUI-only for now (CLI stays unchanged per the §18 scope
7
+ uses for tools. TUI-only for now (CLI stays unchanged per the §18 scope
8
8
  decision); the model-initiated half lives in subagent_tool.py and works
9
9
  in every shell.
10
10
 
@@ -31,8 +31,9 @@ def _cmd_agent(app, args: str) -> None:
31
31
  return
32
32
  if args == "default":
33
33
  app.active_agent = None
34
- app._transcript.write_system("Active agent cleared — default harness.")
34
+ app._transcript.write_system("Active agent cleared — default harness.")
35
35
  _note_skills_under_new_context(app)
36
+ _refresh_agent_panel(app)
36
37
  return
37
38
  agent = manager.get(args)
38
39
  if agent is None:
@@ -43,15 +44,29 @@ def _cmd_agent(app, args: str) -> None:
43
44
  return
44
45
  app.active_agent = agent
45
46
  app._transcript.write_system(
46
- f"Active agent: {agent.name} — {agent.description}")
47
+ f"Active agent: {agent.name} — {agent.description}")
47
48
  _note_skills_under_new_context(app)
49
+ _refresh_agent_panel(app)
50
+
51
+
52
+ def _refresh_agent_panel(app) -> None:
53
+ """Batch 59: the panel's root row IS the active agent, so a
54
+ switch has to repaint it.
55
+
56
+ getattr rather than a direct call because this module is driven
57
+ against stub apps in tests/test_agents.py that carry a transcript
58
+ and nothing else -- and /agent must not start depending on a
59
+ sidebar widget to do its actual job."""
60
+ refresh = getattr(app, "refresh_agent_panel", None)
61
+ if refresh is not None:
62
+ refresh()
48
63
 
49
64
 
50
65
  def _note_skills_under_new_context(app) -> None:
51
66
  """K2's activation note is computed against the context active at
52
67
  activation time; an /agent switch changes the context for every
53
68
  subsequent turn, so re-check active skills and say what is now
54
- denied (review §19-20 f21). Advisory only -- enforcement still
69
+ denied (review §19-20 f21). Advisory only -- enforcement still
55
70
  happens per call via is_tool_allowed."""
56
71
  from skills.manager import manager as skill_manager
57
72
 
@@ -104,7 +119,7 @@ def _cmd_grill(app, args: str) -> None:
104
119
  prompt -- it reads the live history directly (no digest loss)."""
105
120
  if app._busy:
106
121
  app._transcript.write_error(
107
- "Still working — wait for this turn to finish.")
122
+ "Still working — wait for this turn to finish.")
108
123
  return
109
124
  agent = manager.get("grill-me")
110
125
  if agent is None:
@@ -114,7 +129,7 @@ def _cmd_grill(app, args: str) -> None:
114
129
  # run_one_shot owns the WHOLE assembly (#170): the channel, the
115
130
  # catalog facts and the run must come from one answer, so nothing is
116
131
  # decided here. (Review f19's "no context, deliberately" answered a
117
- # question §25 R15 replaced -- what matters now is not which policy
132
+ # question §25 R15 replaced -- what matters now is not which policy
118
133
  # governs but whether anything can answer, and only the run knows.)
119
134
  app.run_one_shot(
120
135
  agent,
@@ -123,7 +138,7 @@ def _cmd_grill(app, args: str) -> None:
123
138
 
124
139
 
125
140
  def register_agent_commands() -> None:
126
- """Idempotent — registering by name overwrites, matching §16's
141
+ """Idempotent — registering by name overwrites, matching §16's
127
142
  register_builtin_commands()."""
128
143
  for command in (
129
144
  SlashCommand("agent", "switch the active agent", _cmd_agent,
@@ -0,0 +1,118 @@
1
+ """
2
+ core/agent_activity.py
3
+
4
+ ROADMAP_v2 §18, batch 59: WHICH agent is running right now, and how deep.
5
+
6
+ The harness runs exactly one agent at a time -- `core/loop.py` dispatches
7
+ tool calls in a plain `for` loop and `spawn_subagent` BLOCKS on the child
8
+ run, so there is never a second one alongside. What there can be is a
9
+ STACK: a chat turn at depth 0 spawning a subagent at depth 1 spawning
10
+ another at depth 2 (config.SUBAGENT_MAX_DEPTH), each frame suspended
11
+ inside the one below it. This module is how a shell learns the shape of
12
+ that stack while it exists.
13
+
14
+ WHY A CHANNEL AND NOT A LoopEvent, which is the obvious first reach:
15
+
16
+ * A generator cannot yield from inside a nested call. spawn_subagent's
17
+ handler runs inside registry.dispatch(), which runs inside _run()'s
18
+ `for call in response.tool_calls:` body -- there is no yield point
19
+ there, so a child's activity cannot be turned into a parent event
20
+ however much one would like it to be.
21
+ * run_agent_conversation drains its OWN _run() through
22
+ run_to_completion(), so a child's events are consumed internally and
23
+ never reach the parent's stream. That is not an oversight to route
24
+ around; §18/D6 returns only the subagent's distilled final text, on
25
+ the pipeline's "don't share raw history" principle.
26
+
27
+ So this carries LIFECYCLE ONLY -- a name and a depth, in and out. Never
28
+ the child's text, tool calls, or events. A shell that wanted those would
29
+ be asking for the thing D6 declines to give it.
30
+
31
+ It rides the same route response_channel already rides (loop -> dispatch
32
+ -> handler -> the child's own loop), for the same reason: an out-of-band
33
+ object is what crosses a boundary a generator cannot.
34
+
35
+ Lives in core/ rather than tui/ because D12 makes the CLI a permanent
36
+ fallback -- and because nothing here knows what a widget is.
37
+ """
38
+
39
+ from contextlib import contextmanager
40
+ from dataclasses import dataclass
41
+ import logging
42
+
43
+ logger = logging.getLogger(__name__)
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class AgentSpan:
48
+ """One agent-shaped run, while it is running.
49
+
50
+ `depth` is ToolContext.subagent_depth -- the value C3 bounds, so a
51
+ consumer indenting by it is drawing the same nesting the depth limit
52
+ is about. Frozen because a span is posted to another thread and read
53
+ later; a mutable one would be a second writer of the stack.
54
+ """
55
+ name: str
56
+ depth: int
57
+
58
+
59
+ class AgentActivity:
60
+ """A sink for span lifecycle. Override enter/exit; use span().
61
+
62
+ The base class is the null sink, so `NULL` below is an instance of
63
+ this rather than a separate do-nothing type -- one class, and a
64
+ subclass that overrides only what it cares about.
65
+ """
66
+
67
+ def enter(self, span: AgentSpan) -> None:
68
+ """A run began. Called on whatever thread the run is on."""
69
+
70
+ def exit(self, span: AgentSpan) -> None:
71
+ """That run ended -- successfully or not."""
72
+
73
+ @contextmanager
74
+ def span(self, name: str, depth: int):
75
+ """Bracket one agent-shaped run.
76
+
77
+ A CONTEXT MANAGER RATHER THAN A PAIR OF CALLS, and that is the
78
+ whole reason this module exists as more than a dataclass. `exit`
79
+ has to run when the child RAISES -- a subagent whose provider
80
+ errors, a compactor that times out -- or its row stays on screen
81
+ for the rest of the session, describing a run that is over. A
82
+ panel that lies is worse than no panel, and the way to make the
83
+ `finally` unforgettable is to make it structural.
84
+
85
+ FAILURES IN THE SINK ARE CONTAINED, both halves. A sink is
86
+ display machinery; a raise inside one must not take down the run
87
+ it is merely describing. Logged rather than swallowed silently,
88
+ so a broken sink is findable -- the same posture
89
+ tools/registry.dispatch() takes around a tool handler.
90
+ """
91
+ span = AgentSpan(name, depth)
92
+ try:
93
+ self.enter(span)
94
+ except Exception: # noqa: BLE001 -- contained
95
+ logger.exception("agent activity sink raised on enter")
96
+ try:
97
+ yield span
98
+ finally:
99
+ try:
100
+ self.exit(span)
101
+ except Exception: # noqa: BLE001 -- contained
102
+ logger.exception("agent activity sink raised on exit")
103
+
104
+
105
+ NULL = AgentActivity()
106
+ """The no-op sink. Every non-TUI shell runs on this."""
107
+
108
+
109
+ def span(activity, name: str, depth: int):
110
+ """Bracket a run against an OPTIONAL sink.
111
+
112
+ `activity` is None on every path but the TUI's, and this is what
113
+ keeps the call sites unconditional: one `with` statement, no branch,
114
+ nothing to get wrong at the five places that open a span. Callers say
115
+ `with agent_activity.span(activity, name, depth):` and never have to
116
+ ask whether anyone is watching.
117
+ """
118
+ return (activity or NULL).span(name, depth)
package/core/client.py CHANGED
@@ -140,8 +140,19 @@ class ModelResponse:
140
140
  # and mid-turn compaction shrinks clamped away. This is the figure
141
141
  # anything reasoning about SIZE reads; the spend meter must never be
142
142
  # read that way again (TECHNICAL_DEBT item 9, closed batch 27).
143
+ # turn_output_tokens: what the MODEL WROTE this turn -- output tokens
144
+ # and nothing else, summed across every step. Batch 61, and it is a
145
+ # THIRD instrument rather than a convenience: the two above are a
146
+ # SPEND meter and a SIZE meter, and a generation RATE can be derived
147
+ # from neither. turn_billed_tokens counts the prompt again on every
148
+ # step; turn_new_tokens adds the positive input deltas, so a
149
+ # tool-using turn's tool results land in it and it overstates what was
150
+ # generated. Dividing either by a duration produces a number that
151
+ # looks like tok/s and is not, which is exactly the misreading
152
+ # TECHNICAL_DEBT item 9 was closed for.
143
153
  turn_billed_tokens: Optional[int] = None
144
154
  turn_new_tokens: Optional[int] = None
155
+ turn_output_tokens: Optional[int] = None
145
156
  # Batch 44 (§44). The turn's reasoning, as the PROVIDER'S OWN BLOCKS
146
157
  # rather than as the text §38 streams for display:
147
158
  #