@yahyahammad/venastine 0.3.17 → 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 +27 -4
- package/core/commands.py +3 -2
- package/core/loop.py +66 -10
- package/core/reasoning/events.py +6 -0
- package/core/reasoning/json_retry.py +12 -1
- package/core/reasoning/orchestrator.py +562 -270
- package/core/reasoning/pipeline_storage.py +86 -5
- package/core/reasoning/resume.py +557 -0
- package/core/reasoning/source_corpus.py +25 -10
- package/main.py +108 -6
- package/package.json +1 -1
- package/pyproject.toml +1 -1
- package/safety/policy_enforcement.py +55 -14
- package/storage.py +13 -0
- package/tui/app.py +114 -8
- package/tui/app.tcss +5 -1
- package/tui/screens.py +61 -0
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
|
|
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
|
|
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` —
|
|
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]]
|
|
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
|
-
|
|
2477
|
-
|
|
2478
|
-
|
|
2479
|
-
|
|
2480
|
-
|
|
2481
|
-
|
|
2482
|
-
|
|
2483
|
-
|
|
2484
|
-
|
|
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
|
-
|
|
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.
|
package/core/reasoning/events.py
CHANGED
|
@@ -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:
|