@yahyahammad/venastine 0.3.18 → 0.3.19

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
@@ -423,6 +423,26 @@ python main.py --mode research "does the claim about X hold up?"
423
423
 
424
424
  In the TUI, a sidebar tracks passes and a running tier tally; `/claims` or **ctrl+l** opens every claim with its tier, grounding status, assumption flags and score breakdown — during the run as well as after it.
425
425
 
426
+ ### Picking up a run that stopped
427
+
428
+ A run that fails, or that you quit, keeps everything it finished. Its last line
429
+ says how to pick it up:
430
+
431
+ ```bash
432
+ python main.py --resume 1a2b3c4d # the run's id, or its first eight characters
433
+ python main.py --resume # list the runs that can be resumed
434
+ ```
435
+
436
+ In the TUI, `/research --resume <id>`, or bare `/research --resume` for a picker.
437
+ Passes that completed are not run again. The pass that failed carries on in its
438
+ own thread, with its research kept: an answer it had already written is checked
439
+ again first, with no model call, and a request the run stopped on is sent again.
440
+ The pages it fetched are read back from the stored tool results, so sources are
441
+ scored as they would have been. A resume runs on the session's current model,
442
+ and takes `--attended`, `--review` and `--grant` again, because a grant is never
443
+ stored. A run recorded before resume existed can be picked up too, unless it
444
+ stopped inside the revision loop.
445
+
426
446
  ### Having it review itself
427
447
 
428
448
  ```bash
@@ -762,7 +782,7 @@ paths are cached and 200 matches offered; narrow the query when a limit is shown
762
782
  | `/critic [[PROVIDER] name\|off]` | Route the grounding and critic passes (3a, 3b, 6b) to a different model than the generator, so it is not checking its own output for errors. Remembered across launches; not cleared by `/model`, since being a different model is the point. Bare reports what is in force and where it came from |
763
783
  | `/embedder [[PROVIDER] name\|off]` | Choose the embedding model that scores how close each source is to the claim it was cited for. The selection is **probed** — one embedding call checks the provider, the slug and the key, and reports the dimension — and only what worked is remembered. Without one, similarity stays the grounding model's own estimate and every run says so |
764
784
  | `/submodel [[PROVIDER] name\|off]` | Run spawned subagents on a different model than the session's, so a cheap child need not run on its parent's expensive model. An agent whose own file names a model or a provider keeps its pin, and the compactor, the pipeline reviewer and `/init`'s initializer keep the session model; the command names what it does not reach. Remembered across launches, never in settings.json, and named in the header while set. Also in the CLI |
765
- | `/research [--attended] [--review\|--no-review] [--grant[=a,b]] <query>` | Run the pipeline live from the TUI. Leading flags compose in any order before the query; bare `--grant` opens the picker, `--grant=a,b` names them (`--grant-tools=` works as an alias); without flags, `research.*` settings apply |
785
+ | `/research [--attended] [--review\|--no-review] [--grant[=a,b]] <query>\|--resume [run-id]` | Run the pipeline live from the TUI. Leading flags compose in any order before the query; bare `--grant` opens the picker, `--grant=a,b` names them (`--grant-tools=` works as an alias); without flags, `research.*` settings apply. `--resume` comes last and picks a failed or abandoned run up where it stopped; bare, it opens a picker |
766
786
  | `/compact [--strength 1-5]` | Fold older turns now instead of waiting for the trigger. Recent turns keep exactly the protection an automatic compaction gives them |
767
787
  | `/trigger [tokens\|off]` | Override **when this chat compacts**, for this session only. An absolute prompt size (`80k`), not a margin below the window. A value below the warning margin or the keep-recent floor is refused naming it; a value below the thread's current size is accepted and says a fold is coming |
768
788
  | `/window [tokens\|off]` | Set this model's **context window** and remember it, per `(provider, model)` and across launches. It outranks both the provider's own answer and the built-in table, and it moves everything derived from the window: the chat compaction trigger, the research-pass backstop and the summarizer's input budget. Above what the provider reports it warns rather than refusing, because raising it is the point — a gateway or a self-hosted endpoint can report its own default rather than your deployment's |
@@ -871,6 +891,7 @@ Everything `python main.py` accepts. Wherever a value can come from more than on
871
891
  | `--grant-tools NAMES` | Research only. Same as `--grant`, but takes an explicit comma-separated list of tool names and works without a terminal |
872
892
  | `--attended` | Research only. Ask about every gated call as it happens; 600s with no answer denies that call and the run continues. Composes with grants — granted tools aren't asked about, everything else is |
873
893
  | `--review` / `--no-review` | Research only. Post-pipeline review on/off for this run; `--no-review` is the escape from a persisted setting |
894
+ | `--resume [RUN_ID]` | Pick a failed or abandoned research run up where it stopped; completed passes are not run again. Implies `--mode research`. The id's first eight characters are enough; with none, list the runs that can be resumed and exit |
874
895
  | `--memories` | List durable memories visible from this directory — id, scope, content — and exit |
875
896
  | `--forget ID` | Delete one memory by id — never by substring — and exit |
876
897
  | `--summary [THREAD]` | Print one thread's distilled summary and exit; falls back to `--thread`. A summary still current costs no model call — staleness is detected, not assumed |
@@ -882,7 +903,9 @@ Everything `python main.py` accepts. Wherever a value can come from more than on
882
903
 
883
904
  **Combinations the parser refuses** (rather than ignoring):
884
905
 
885
- - `--mode research` without a positional query.
906
+ - `--mode research` without a positional query (or `--resume`).
907
+ - `--resume` with a query — a resumed run keeps its own.
908
+ - `--tui` with `--resume` — use `/research --resume` inside the TUI.
886
909
  - `--tui` with `--mode research` — use `/research` inside the TUI.
887
910
  - `--tui` with a positional query — start the TUI and type.
888
911
  - Any of `--grant`, `--grant-tools`, `--attended`, `--review`, `--no-review` outside research mode, including under `--tui`.
@@ -1058,7 +1081,7 @@ Deliberately not settings.json keys: editing these means editing the harness's o
1058
1081
 
1059
1082
  **Built:** ROADMAP.md §1–§12 (§10's ensemble mode rebuilt by its revisit — diversity now comes from a roster of different models) and ROADMAP_v2.md §13 (streaming loop), §14 (config loader + workspace trust), §15 (permissions), §16 (TUI), §17 (MCP), §18 (agents), §19 (skills), §20 (post-pipeline review), §21a (compaction + `pin`), §21b (durable memory), §22 (live pipeline progress), §25 (authorised tool use in the pipeline), §26 (research legibility: per-pass tool calls, code-stage announcements, the claims view, role colour, `/copy`), §27 (thread legibility: transcript replay on resume, a conversations-only thread picker), §21c (session summaries and cross-thread referencing — §21 is now complete), §24 (`/init`), §23 (interactive tools: the response channel, per-tool subagent sign-off, `ask_user`, and the todo list), §28 (the shell capability classifier).
1060
1083
 
1061
- **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§59, §61–§93, §95, §96 and §97 are built. The section still to build is §60 (Unified Harness Protocol compliance), specified and awaiting detailed design. §56 lets a decision model approve a single contained shell command under the opt-in `classified` mode; §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. `TECHNICAL_DEBT.md` items 14, 17, 18, 21, 102, 116, 118, 119 and 120 are open, and so is the secrets half of item 97. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
1084
+ **Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§59, §61–§93 and §95–§98 are built. The section still to build is §60 (Unified Harness Protocol compliance), specified and awaiting detailed design. §56 lets a decision model approve a single contained shell command under the opt-in `classified` mode; §54 completes project file/folder mentions without loading contents; §58 supplies a short harness identity that follows the current model; §83's final live checks are confirmed, and the ChatGPT header distinguishes a selected provider from an active sign-in. `TECHNICAL_DEBT.md` items 14, 17, 18, 21, 102, 116, 118, 119, 120, 121 and 122 are open, and so is the secrets half of item 97. The two checks recorded against §10 are answered from the providers' documentation in `ROADMAP_v3.md` §87: the default `temperature` on OpenAI and Google is 1.0, and OpenAI's reasoning models refuse one whenever reasoning effort is not `none`, which the guard now follows.
1062
1085
 
1063
1086
  **And both audits are closed.** Both roadmaps being built is not the same as the code
1064
1087
  being clean, and saying only the first would be the "built and runs are different claims"
@@ -1077,7 +1100,7 @@ note that shell approval is governed solely by `shell_approval_mode` -- `tool_ap
1077
1100
  deliberately has no `shell` key, so an old file carrying one is refused at startup
1078
1101
  naming the key — see `tests/BREAKING_CHANGES.md` §24.
1079
1102
 
1080
- Run the test suite with `pytest` — 9829 tests, fully offline, no API keys needed. Since batch 243 the suite holds itself to that: a test that asks DNS for a name, or writes into your home folder, fails by name, and every test process runs with HOME pointing at a throwaway folder of its own. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Eight further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, one runs an external program through the host fallback shell, one builds the hosted bundle's Docker image, and three run the installers' uv path against a real uv (`pytest -m integration`).
1103
+ Run the test suite with `pytest` — 9916 tests, fully offline, no API keys needed. Since batch 243 the suite holds itself to that: a test that asks DNS for a name, or writes into your home folder, fails by name, and every test process runs with HOME pointing at a throwaway folder of its own. The suite's own packages are `requirements-test.txt`, separate from `requirements.txt` since batch 136: they used to be in the shipped dependency list, so installing the harness also installed a test runner. It runs in parallel by default (`pytest-xdist`, 70% of your cores): **1:26 on a 16-core machine, against 9:06 single-process.** `pytest -n0` forces the old serial run, which is what you want under a debugger or when something is parsing the output. Eight further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, one runs an external program through the host fallback shell, one builds the hosted bundle's Docker image, and three run the installers' uv path against a real uv (`pytest -m integration`).
1081
1104
 
1082
1105
  ## Documentation
1083
1106
 
package/core/commands.py CHANGED
@@ -138,8 +138,9 @@ _SPECS = (
138
138
  CommandSpec("quit", "exit the harness", aliases=("exit", "bye")),
139
139
  CommandSpec("ref", "reference another conversation's summary",
140
140
  "[--list|--clear]"),
141
- CommandSpec("research", "run the deep-research pipeline",
142
- "[--attended] [--review|--no-review] [--grant[=a,b]] <query>",
141
+ CommandSpec("research", "run the deep-research pipeline, or resume one",
142
+ "[--attended] [--review|--no-review] [--grant[=a,b]] "
143
+ "<query>|--resume [run-id]",
143
144
  absent={CLI: 'not yet; run venastine --mode research '
144
145
  '"<query>".'}),
145
146
  CommandSpec("resume", "resume a thread by id, even an old one",
package/core/loop.py CHANGED
@@ -1734,6 +1734,40 @@ def _finish_cancelled(memory, response, *, partial_text, unrun, reason,
1734
1734
  yield LoopEvent(final_response=response, stop_reason="cancelled")
1735
1735
 
1736
1736
 
1737
+ #: What a resumed pass tells the model about a call its run never answered
1738
+ #: (ROADMAP_v3 §98, RS4). Worded for the model, which is who reads it.
1739
+ UNANSWERED_ON_RESUME = (
1740
+ "Not run: the research run stopped before this call returned a result. "
1741
+ "Call it again if you still need it.")
1742
+
1743
+
1744
+ def answer_unanswered_calls(memory, reason: str = UNANSWERED_ON_RESUME) -> int:
1745
+ """Write an error result for every call of the thread's LAST assistant
1746
+ turn that has no result yet, and return how many (ROADMAP_v3 §98, RS4).
1747
+
1748
+ #42's lesson and `_finish_cancelled`'s, reached from a third side. A
1749
+ run killed while a tool ran leaves the `tool_use` D20 had already
1750
+ written with no `tool_result`, and a provider refuses the next request
1751
+ built from that thread. A cancelled turn answers its calls before it
1752
+ ends; a killed one could not, so the run that RESUMES the thread
1753
+ answers them first, in the shape a denied call already takes. Only the
1754
+ last assistant turn: every earlier one was answered before the loop
1755
+ took its next step.
1756
+ """
1757
+ messages = memory.messages
1758
+ last = next((i for i in range(len(messages) - 1, -1, -1)
1759
+ if messages[i].get("role") == "assistant"), None)
1760
+ if last is None:
1761
+ return 0
1762
+ answered = {m.get("tool_call_id") for m in messages[last + 1:]
1763
+ if m.get("role") == "tool"}
1764
+ missing = [call["id"] for call in messages[last].get("tool_calls") or ()
1765
+ if call.get("id") not in answered]
1766
+ for call_id in missing:
1767
+ memory.add_tool_result(call_id, {"error": reason})
1768
+ return len(missing)
1769
+
1770
+
1737
1771
  class RunAgentLoop:
1738
1772
 
1739
1773
  @staticmethod
@@ -2426,10 +2460,21 @@ class RunAgentLoop:
2426
2460
  context: Optional[ToolContext] = None,
2427
2461
  authorization=None,
2428
2462
  activity=None,
2463
+ resume_thread: Optional[UUID] = None,
2464
+ on_thread=None,
2429
2465
  ):
2430
2466
  """One research pass, as a generator of LoopEvents, RETURNING the
2431
2467
  ModelResponse (ROADMAP_v2 §26).
2432
2468
 
2469
+ ROADMAP_v3 §98 adds two arguments, both for a run that fails and is
2470
+ resumed. `on_thread` is called with the pass's thread id the moment
2471
+ the thread exists (RS3): the run used to learn it only when the pass
2472
+ RETURNED, so a pass that raised, or was abandoned, left a thread its
2473
+ run could not name. `resume_thread` continues an existing pass
2474
+ thread instead of opening one (RS4): no user row is added, any call
2475
+ the thread left unanswered is answered first, and the loop takes the
2476
+ step the failed run was about to take. `pass_input` is unused then.
2477
+
2433
2478
  Exists because §22's P2 -- "a pass's LoopEvents do not propagate
2434
2479
  up" -- made a pass opaque while it ran. The pipeline could say
2435
2480
  which pass had started and nothing about what it was doing, so a
@@ -2473,19 +2518,30 @@ class RunAgentLoop:
2473
2518
  # written as a 1: `_compactor_depth`'s rule, one entry point over.
2474
2519
  depth = (context.subagent_depth if context is not None else 0) + 1
2475
2520
  with agent_activity.span(activity, pass_id, depth):
2476
- memory = ConversationMemory(
2477
- kind=THREAD_KIND_RESEARCH_PASS,
2478
- # §47. No parent THREAD: a pass is a child of the RUN, and
2479
- # a run is not a conversation. §27's T2 already indexes
2480
- # them on `PipelineRun.pass_threads`, the run's own
2481
- # object, so a second index here would be two records of
2482
- # one edge -- the producer/consumer shape this project
2483
- # keeps finding.
2484
- agent_name=pass_id)
2521
+ if resume_thread is None:
2522
+ memory = ConversationMemory(
2523
+ kind=THREAD_KIND_RESEARCH_PASS,
2524
+ # §47. No parent THREAD: a pass is a child of the RUN,
2525
+ # and a run is not a conversation. §27's T2 already
2526
+ # indexes them on `PipelineRun.pass_threads`, the run's
2527
+ # own object, so a second index here would be two
2528
+ # records of one edge -- the producer/consumer shape
2529
+ # this project keeps finding.
2530
+ agent_name=pass_id)
2531
+ else:
2532
+ memory = ConversationMemory(thread_id=resume_thread)
2485
2533
  # The address, at the earliest moment it exists, so a pass is
2486
2534
  # openable WHILE it runs rather than once the report lands.
2487
2535
  agent_activity.bind(activity, memory.thread_id)
2488
- memory.add_user_message(pass_input)
2536
+ # ROADMAP_v3 §98 (RS3), the same moment for the same reason: a
2537
+ # run that fails or is abandoned in this pass can still name the
2538
+ # thread its work is in.
2539
+ if on_thread is not None:
2540
+ on_thread(memory.thread_id)
2541
+ if resume_thread is None:
2542
+ memory.add_user_message(pass_input)
2543
+ else:
2544
+ answer_unanswered_calls(memory)
2489
2545
  # #68. The catalogs are decided from the SAME bundle the tool
2490
2546
  # schemas are decided from a few frames down, so a pass cannot
2491
2547
  # be told to spawn a subagent it will not be given.
@@ -96,6 +96,12 @@ PIPELINE_EVENT_KINDS = (
96
96
  "tool_call", # pass_id + tool + text -- a pass invoked a tool
97
97
  "tool_result", # pass_id + tool + ok (+ text when it failed)
98
98
  "pass_activity", # pass_id + chars -- output streamed so far, throttled
99
+ # --- ROADMAP_v3 §98 -----------------------------------------------
100
+ "run_started", # text -- the run's id, first, before any pass. A
101
+ # shell needs it to say how to resume a run that
102
+ # then fails or is abandoned: the exception that
103
+ # ends a failed run carries no reference back to
104
+ # it, and run_complete is never reached.
99
105
  )
100
106
 
101
107
  # There is deliberately NO "step" kind. §26 set out to report which model
@@ -80,13 +80,24 @@ _TEXT_CORRECTIVE = (
80
80
  def parse_json_response(text: str) -> Any:
81
81
  """Callers are instructed (via the universal preamble, or an agent's
82
82
  own output-format section) to emit clean JSON, optionally in a code
83
- fence. Strip the fence if present."""
83
+ fence. Strip the fence if present.
84
+
85
+ A fence at EITHER end, since ROADMAP_v3 §98 (RS7). A lone closing fence
86
+ after bare JSON used to reach `json.loads`, which read the value and
87
+ raised "Extra data" on the three backticks. Measured on a real run: a
88
+ Pass 3a answer of 59,009 characters was a complete array of one entry
89
+ per factual claim followed by a newline and a closing fence, and it
90
+ failed a run that had spent 4h53m. Only the fence is taken. Any other
91
+ text after the value still fails and is corrected as before, because
92
+ a second value there could be the rest of the answer."""
84
93
  cleaned = text.strip()
85
94
  if cleaned.startswith("```"):
86
95
  cleaned = cleaned.split("```")[1]
87
96
  if cleaned.lower().startswith("json"):
88
97
  cleaned = cleaned[4:]
89
98
  cleaned = cleaned.strip()
99
+ elif cleaned.endswith("```"):
100
+ cleaned = cleaned[:-3].rstrip()
90
101
  try:
91
102
  return json.loads(cleaned)
92
103
  except json.JSONDecodeError as e: