@yahyahammad/venastine 0.2.0 → 0.3.8
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/.env.example +19 -14
- package/CONFIG_ARCHITECTURE.md +2002 -0
- package/NOTICE +1 -1
- package/README.md +233 -94
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/plan.md +23 -5
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +261 -195
- package/agents/subagent_tool.py +277 -43
- package/agents/tui_commands.py +7 -12
- package/bin/venastine.mjs +528 -382
- package/bin/venastine.py +71 -0
- package/cli_commands.py +835 -0
- package/config.py +95 -1198
- package/config.yaml +1090 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +966 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +158 -20
- package/core/ansi.py +452 -0
- package/core/approval.py +27 -5
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +1238 -82
- package/core/commands.py +454 -0
- package/core/compaction.py +830 -66
- package/core/config_loader.py +516 -97
- package/core/connect.py +686 -0
- package/core/events.py +68 -6
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +87 -4
- package/core/line_pattern.py +128 -0
- package/core/loop.py +1516 -440
- package/core/memory.py +120 -8
- package/core/pipeline_models.py +23 -9
- package/core/provider_errors.py +234 -0
- package/core/reasoning/confidence_scoring.py +70 -54
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +232 -53
- package/core/reasoning/output_writer.py +90 -31
- package/core/reasoning/payload_validation.py +133 -7
- package/core/reasoning/pipeline_storage.py +427 -361
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +38 -14
- package/core/reasoning/source_corpus.py +110 -4
- package/core/replay.py +158 -26
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +308 -180
- package/database.py +82 -1
- package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +118 -77
- package/json_store.py +236 -16
- package/logging_setup.py +121 -11
- package/main.py +1671 -199
- package/mcp_client/client.py +257 -23
- package/mcp_client/config.py +484 -379
- package/mcp_client/registration.py +163 -2
- package/memories/manager.py +15 -0
- package/memories/tui_commands.py +7 -12
- package/package.json +234 -4
- package/project_init/config_files.py +4 -0
- package/project_init/generator.py +201 -37
- package/project_init/manifest.py +418 -406
- package/project_init/tui_commands.py +7 -4
- package/prompts/revalidate.md +1 -1
- package/prompts/revise.md +17 -15
- package/prompts/system_prompts.py +64 -10
- package/providers.json.example +94 -92
- package/pyproject.toml +51 -2
- package/requirements.txt +252 -29
- package/safety/policy_enforcement.py +353 -17
- package/security/askpass.py +419 -0
- package/security/capability.py +37 -7
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +54 -7
- package/security/posture.py +124 -12
- package/security/protected_paths.py +198 -6
- package/security/sandbox.py +3262 -139
- package/security/secrets.py +855 -0
- package/skills/tui_commands.py +3 -4
- package/storage.py +368 -35
- package/tools/base.py +465 -305
- package/tools/builtin/_math_common.py +306 -16
- package/tools/builtin/_net_common.py +267 -61
- package/tools/builtin/arxiv.py +681 -223
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +239 -21
- package/tools/builtin/file_ops.py +341 -33
- package/tools/builtin/geometry.py +184 -148
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +10 -0
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +46 -12
- package/tools/builtin/probability_stats.py +224 -228
- package/tools/builtin/project_docs.py +80 -21
- package/tools/builtin/remember.py +21 -4
- package/tools/builtin/shell.py +586 -67
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +5 -3
- package/tools/builtin/web_search.py +329 -151
- package/tools/context.py +23 -0
- package/tools/isolation.py +387 -314
- package/tools/registry.py +347 -30
- package/tui/app.py +4645 -438
- package/tui/app.tcss +185 -2
- package/tui/commands.py +10 -154
- package/tui/diffs.py +286 -265
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +60 -10
- package/tui/meters.py +103 -7
- package/tui/screens.py +346 -92
- package/tui/themes.py +59 -19
- package/tui/widgets.py +1575 -111
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-

|
|
1
|
+

|
|
2
2
|
|
|
3
3
|
# Venastine Research Harness
|
|
4
4
|
|
|
@@ -13,9 +13,85 @@ The design premise is that a model's own confidence is not evidence. Everything
|
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
16
|
+
## Try it online
|
|
17
|
+
|
|
18
|
+
The same harness runs in your browser, nothing to install, on a [Hugging Face Space](https://huggingface.co/spaces/SolenopsisCampo/VenastineHarnessDemo) and a [ModelScope Studio](https://www.modelscope.ai/studios/Venastine-Research/VenastineHarnessDemo). Each tab gets its own session, deleted when the tab closes.
|
|
19
|
+
|
|
20
|
+
- **Connect a model with a sign-in.** `/connect huggingface` and `/connect openrouter` work on both, and `/connect modelscope` (modelscope.ai) or `/connect modelscope-cn` (modelscope.cn) wherever the deployment can complete that site's sign-in. Requests use your own account's allowance, and the landing page links each provider's page for revoking access.
|
|
21
|
+
- **The shared demo takes no pasted key**, and it does not offer the file and shell tools. A private duplicate of the Space in single-user mode takes both (set `VENASTINE_SINGLE_USER=1` in Hugging Face's duplicate dialog), and so does an install.
|
|
22
|
+
- **It runs a commit of `main` that passed every CI check**, named in each page's footer: the Space is redeployed automatically once all of them pass, and the Studio by hand with the same checks. [PRIVACY.md](docs/PRIVACY.md#the-hosted-demo-roadmap_v3-79) says what a hosted session changes.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
16
26
|
## Setup
|
|
17
27
|
|
|
18
|
-
**Python 3.11 or newer**,
|
|
28
|
+
**Python 3.11 or newer**, for every local install. `mcp_client/client.py` uses `asyncio.timeout`, which is 3.11+, and 27 sites use runtime `X | Y` annotations (3.10+). `pyproject.toml` declares the floor, so an install refuses an older interpreter rather than failing later from inside the MCP connect path.
|
|
29
|
+
|
|
30
|
+
### Install directly from GitHub
|
|
31
|
+
|
|
32
|
+
Requires **Python 3.11+**, including its `venv` module. Node, npm, Git, and
|
|
33
|
+
administrator access are not needed. On Linux/macOS (Bash and curl):
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
On Windows (PowerShell):
|
|
40
|
+
|
|
41
|
+
```powershell
|
|
42
|
+
irm https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.ps1 | iex
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
You can also download and inspect the scripts before running them. They
|
|
46
|
+
download the shared Python installer completely, then execute it. It resolves
|
|
47
|
+
`main` to a full commit ID, downloads that source archive, and installs the
|
|
48
|
+
runtime dependencies in an isolated environment. It does not install Python.
|
|
49
|
+
|
|
50
|
+
The source lives under `~/.local/share/venastine/app`, with a `venastine`
|
|
51
|
+
command in `~/.local/bin` (`venastine.cmd` on Windows). When that directory is
|
|
52
|
+
not on your PATH yet, the installer puts it there for the terminals you open
|
|
53
|
+
afterwards, the way npm's global commands already are. On Windows it appends
|
|
54
|
+
it to your user PATH, and to the PowerShell window that ran the installer. On
|
|
55
|
+
macOS and Linux it adds a marked block to your own shell's startup file —
|
|
56
|
+
`~/.zshrc`, `~/.bashrc`, fish's `conf.d/venastine.fish`, or `~/.profile` for
|
|
57
|
+
other shells, plus the bash login file you already have on macOS. Running it
|
|
58
|
+
again adds nothing twice. To leave PATH alone, set
|
|
59
|
+
`VENASTINE_NO_MODIFY_PATH=1` or pass `--no-modify-path`. If another
|
|
60
|
+
`venastine` — an npm install, say — comes first on your PATH, the installer
|
|
61
|
+
names it and prints this command's full path instead.
|
|
62
|
+
Then, from your project directory, run `venastine --tui` and use `/connect`.
|
|
63
|
+
`venastine --venastine-doctor` shows the installed version, commit, interpreter,
|
|
64
|
+
and state paths. Credentials and conversation state follow the same rules
|
|
65
|
+
as the npm installation below.
|
|
66
|
+
|
|
67
|
+
Rerun the installer to update, after closing running Venastine sessions. It
|
|
68
|
+
builds a fresh environment before replacing the active source and carries
|
|
69
|
+
your `config.yaml` edits forward through the existing settings merger.
|
|
70
|
+
Previous source trees (`previous-*`) stay under the install directory for
|
|
71
|
+
recovery. Python environments stay in `~/.config/venastine/runtime/github-*`,
|
|
72
|
+
inside the user tier the harness already protects from tool writes. Updates
|
|
73
|
+
therefore use more disk space. An unrelated existing directory or command is
|
|
74
|
+
never replaced.
|
|
75
|
+
|
|
76
|
+
Choose a branch, tag, or full commit ID with `VENASTINE_REF`; choose locations
|
|
77
|
+
with `VENASTINE_INSTALL_DIR` and `VENASTINE_BIN_DIR`, or a Python executable
|
|
78
|
+
with `VENASTINE_PYTHON`; `VENASTINE_NO_MODIFY_PATH=1` leaves PATH alone. Set
|
|
79
|
+
these before running either command. The default
|
|
80
|
+
ref is `main`; older refs without `bin/venastine.py` cannot use this installer.
|
|
81
|
+
The installer itself is downloaded from `main`, even when selecting another
|
|
82
|
+
source ref. Bash also forwards options to the helper:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash -s -- --ref main
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
From a checkout, `python scripts/install.py --help` lists the same options
|
|
89
|
+
without downloading or installing anything. To remove a GitHub installation,
|
|
90
|
+
remove its command, install directory, the `github-*` runtime directories it
|
|
91
|
+
created, and the PATH entry it added — from your user PATH on Windows, or the
|
|
92
|
+
block between the `venastine GitHub installer` markers in your shell's startup
|
|
93
|
+
file; other state in `~/.config/venastine` and artifacts in your projects
|
|
94
|
+
remain separate.
|
|
19
95
|
|
|
20
96
|
### From npm
|
|
21
97
|
|
|
@@ -37,6 +113,8 @@ Two things differ from a clone, both to make a command you run from anywhere beh
|
|
|
37
113
|
* **Credentials** fall back to `~/.config/venastine/providers.json` when the directory you are in has no `providers.json` of its own. A local one still wins, so per-project keys keep working.
|
|
38
114
|
* **Conversation state** — `app.db` and the log — lives in `~/.config/venastine/`, so threads and memories follow you between directories instead of each folder getting its own silo. Research reports still land in `./output` beside the work that produced them, and the file-ops workspace stays in the current directory because it is a permission boundary. An existing `./app.db` always wins, so running the command inside a clone uses that clone's data.
|
|
39
115
|
|
|
116
|
+
**Updating keeps your settings.** `npm update` replaces the package directory wholesale, `config.yaml` with it, so the launcher merges your own values back in before the harness starts and prints what it kept. Settings you never touched pick up the new version's defaults, and keys the new version adds arrive at theirs; a value the new version no longer accepts is dropped on its own and named, rather than costing you the rest. It works for values set with `/config` and for ones you edited in the file by hand, which is the only way to set a list like `ensemble_models`. The one case it cannot help with is an edit made after your last session and never launched before you updated -- npm has already replaced the file by the time anything of ours runs.
|
|
117
|
+
|
|
40
118
|
`venastine --venastine-doctor` prints every one of those resolved paths, plus the interpreter and environment it found.
|
|
41
119
|
|
|
42
120
|
### From a clone
|
|
@@ -61,7 +139,7 @@ cp providers.json.example providers.json # then add your provider's API key
|
|
|
61
139
|
cp .env.example .env # then fill in only the keys your tools actually need
|
|
62
140
|
```
|
|
63
141
|
|
|
64
|
-
Without the first file every model call fails — both shells say so at launch (#138),
|
|
142
|
+
Without the first file every model call fails — both shells say so at launch (#138). **In the TUI, `/connect` writes it for you**: `/connect` lists the providers it knows, `/connect <name>` asks for the key in a masked prompt and saves it (0600), and `/connect custom <NAME> <url>` adds any OpenAI-compatible endpoint. Three providers let you **sign in instead of pasting a key**, because their own documentation invites a third-party app to: `/connect huggingface` uses Hugging Face's device code flow (its [OAuth guide](https://huggingface.co/docs/hub/oauth) — a code to confirm on huggingface.co, with the `inference-api` scope only) through the project's own app, named by `hf_oauth_client_id` in `config.yaml`, and `/connect openrouter` uses [OpenRouter's PKCE flow](https://openrouter.ai/docs/guides/overview/auth/oauth), which shows a code to paste back and makes a key you can delete at openrouter.ai/keys. And `/connect chatgpt` signs in to a ChatGPT Plus or Pro plan through [OpenAI's Sign in with ChatGPT](https://developers.openai.com/siwc), which offers it to open-source apps running on your own machine: the page comes back to a one-shot listener on 127.0.0.1, so it works in a local install and never on a hosted one. Once you are signed in, `/model CHATGPT <model>` chats on the plan: the header says "Using ChatGPT plan" with a Manage usage link, and a usage limit stops and points there rather than retrying. Everything else is a pasted key. Either way the next turn uses the new key without a restart. **`/disconnect <name>` undoes it**: it asks first, then blanks the key (the entry's other settings stay for a later `/connect`) and says where to revoke the key itself, or signs out of the ChatGPT plan, revoking it at OpenAI; `--forget` also drops the plan's registration so the next sign-in can be another account. The selected model stays remembered, but the header says "Signed out | use /connect or add API key", including after a restart, so you can reconnect or choose another provider through OAuth or an API key.
|
|
65
143
|
|
|
66
144
|
Both are gitignored. They are kept apart on purpose: provider keys are read by one module at model-call time, while tool keys are handed to code that talks to third parties. Mixing them would put every tool's secrets in reach of the credential path and vice versa. If it is ever unclear which file a new secret belongs in, it belongs in `.env` unless a model provider is going to authenticate with it.
|
|
67
145
|
|
|
@@ -69,6 +147,26 @@ Both are gitignored. They are kept apart on purpose: provider keys are read by o
|
|
|
69
147
|
|
|
70
148
|
## Running it
|
|
71
149
|
|
|
150
|
+
**Run it from the directory you want to work in, not from the harness's own.** The directory you
|
|
151
|
+
launch from is the *project* — workspace trust, `.venastine/`, `/init`'s destination and
|
|
152
|
+
project-scoped memories all follow it — so launching from the install tree would make the harness
|
|
153
|
+
its own project, and that is refused at startup (exit 2). Either of these is the answer:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
cd ~/my-project && python /path/to/venastine/main.py # the project is where you are
|
|
157
|
+
AGENT_WORKSPACE=~/my-project python main.py # or name it, from anywhere
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
```yaml
|
|
161
|
+
# or, in config.yaml, for a setup with no variable to set
|
|
162
|
+
workspace_dir: ~/my-project
|
|
163
|
+
workspace_is_project: true
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Working on the harness itself is `AGENT_WORKSPACE=./workspace`, which is the shipped layout and is
|
|
167
|
+
exempt. `workspace_dir` alone is *not* a substitute for either route: it moves the workspace and
|
|
168
|
+
leaves the project where it was, which is what `workspace_is_project` beside it is for.
|
|
169
|
+
|
|
72
170
|
```bash
|
|
73
171
|
python main.py # chat, new thread
|
|
74
172
|
python main.py --thread <uuid> # resume a thread
|
|
@@ -77,11 +175,13 @@ python main.py --provider OPENAI --model gpt-5.1 # override provider/model
|
|
|
77
175
|
python main.py --tui # the full-screen interface
|
|
78
176
|
```
|
|
79
177
|
|
|
80
|
-
The line-based CLI is the default and is never going away
|
|
178
|
+
The line-based CLI is the default and is never going away. The TUI is a nicer shell over the same code, and most of it is reachable from the CLI too: the CLI's `/help` lists its slash commands, then each TUI command it does not have yet and where to find it instead.
|
|
179
|
+
|
|
180
|
+
Every launch flag is tabulated in the [CLI flag reference](#cli-flag-reference) below; every slash command under [The TUI](#the-tui), and the CLI's just below.
|
|
81
181
|
|
|
82
|
-
|
|
182
|
+
A turn prints as it runs, one step at a time: the model's reasoning, what it said, and a line for each tool call as it starts. During a turn, Ctrl+C twice within two seconds stops it at the next safe point; the first press only says so, so a stray one costs nothing. At the prompt, Ctrl+C or Ctrl+D exits. The thread id is printed after the first response so you can resume later — and resuming **replays the conversation**, so you can see what you are picking up. Tool calls replay as one line each; their results do not, since a single research turn can carry hundreds of kilobytes of fetched pages.
|
|
83
183
|
|
|
84
|
-
|
|
184
|
+
A line that starts with `/` is a command, as in the TUI, and never reaches the model; an unknown one is an error rather than a chat turn. The CLI has eighteen: `/help`, `/quit`, `/threads`, `/resume`, `/new`, `/goal`, `/agent`, `/skill`, `/grill-me`, `/effort`, `/model`, `/compact`, `/summary`, `/ref`, `/memories`, `/forget`, `/claims` and `/call`. They mean what the TUI's do: both shells read one catalog of commands, so a name, its arguments and its description cannot differ between them. `/threads` and `/ref` print a numbered list and ask for a number, or a thread id for one the list does not show. `/call` lists this conversation's tool calls, numbered, and `/call 3` shows the third in full: the whole command and what it returned, or a background session's output, or the run a subagent made. It is the CLI's version of ctrl+clicking a tool line in the TUI. `/model` here lasts for the session, since the CLI starts from `--model` or settings.json.
|
|
85
185
|
|
|
86
186
|
---
|
|
87
187
|
|
|
@@ -168,7 +268,7 @@ answers: `true`, `false` — meaning the run fetched this page and the quoted wo
|
|
|
168
268
|
which is a fabricated citation — and `null`, meaning there was nothing to check against, which is
|
|
169
269
|
not the same thing.
|
|
170
270
|
|
|
171
|
-
**Cited papers can be scored on their own standing.** With `
|
|
271
|
+
**Cited papers can be scored on their own standing.** With `scholar_lookup: true` in `config.yaml`,
|
|
172
272
|
an arXiv or DOI URL is resolved against OpenAlex and scored on venue (peer-reviewed or preprint),
|
|
173
273
|
citation standing, and author h-index. Citation standing is a percentile *within the paper's own
|
|
174
274
|
field-and-year cohort*, measured by two counting queries rather than modelled — OpenAlex's own
|
|
@@ -188,7 +288,7 @@ code:
|
|
|
188
288
|
| `confidence.grounding_weight_factor` | `0.5` | Weight of the grounding term |
|
|
189
289
|
| `confidence.critic_weight_factor` | `0.35` | Weight of the critic term |
|
|
190
290
|
| `confidence.assumption_flag_penalty` | `0.15` | Subtracted per assumption flag |
|
|
191
|
-
| `confidence.disagreement_penalty_factor` |
|
|
291
|
+
| `confidence.disagreement_penalty_factor` | — | Retired in batch 232: still accepted, warns, and does nothing. A claim the ensemble disagrees about is checked instead of marked down |
|
|
192
292
|
| `confidence.non_factual_score_cap` | `0.65` | Ceiling for claims that were never grounded |
|
|
193
293
|
| `confidence.grounding_weights` | `1.0 / 0.5 / 0.0` | Per grounded / partial / ungrounded |
|
|
194
294
|
| `confidence.tier_thresholds` | `0.8 / 0.55 / 0.3` | HIGH / MEDIUM / LOW; must stay ordered |
|
|
@@ -207,7 +307,7 @@ than refusing to start the run — unlike the compaction knobs above, where an i
|
|
|
207
307
|
model calls on every turn. An *unknown* key still raises, as everywhere else in `settings.json`.
|
|
208
308
|
`critic_model` and `embedder_model` are rejected there by name: both name a provider this harness
|
|
209
309
|
sends research content to, and a project's `settings.json` outranks your own — use `/critic` and
|
|
210
|
-
`/embedder`, or `config.
|
|
310
|
+
`/embedder`, or `config.yaml`.
|
|
211
311
|
|
|
212
312
|
### A pass that answers the wrong shape is corrected, then it stops the run
|
|
213
313
|
|
|
@@ -236,7 +336,7 @@ where *nothing* matched is treated as a failure. Every number in `04_confidence.
|
|
|
236
336
|
|
|
237
337
|
Set `CRITIC_MODEL` and passes 3a, 3b and 6c run on a *different* provider and model from the one that wrote the answer. A model checking its own output brings its own blind spots to the inspection.
|
|
238
338
|
|
|
239
|
-
**Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs
|
|
339
|
+
**Ensemble mode** extends the same idea to the answer itself. List `{provider_name, model}` pairs under `ensemble_models` in `config.yaml` (a settings.json key is deliberately absent — choosing providers multiplies spend, so it stays in the harness's own file) and Pass 1 runs once per entry, each candidate on its own provider and model. Fewer than two *distinct* pairs is refused: N copies of one model agree most confidently on that model's systematic errors, which is exactly where agreement has to mean something. Claims extracted from all candidates are pooled. A factual claim no more than half the candidates asserted is *contested*: it keeps the score its evidence earns and goes through the revise-and-revalidate passes to be checked, with the count in its feedback. Since batch 232; it used to be marked down instead, which no revision could undo. A candidate that fails mid-run is named and skipped; if only one survives, the run degrades to the ordinary single-response path rather than scoring an "ensemble of one". Artifacts come out as `01_candidate_1.md`, `01_candidate_2.md`, … numbered to match each claim's `asserted_by_candidates` tags.
|
|
240
340
|
|
|
241
341
|
### What you get out
|
|
242
342
|
|
|
@@ -246,12 +346,12 @@ Every run writes `output/<run_id>/`:
|
|
|
246
346
|
00_plan.md 04_assumptions.json trace.md
|
|
247
347
|
01_raw_response.md 05_confidence.json report.md
|
|
248
348
|
02_claims.json 06_revisions.json report.pdf (if weasyprint installed)
|
|
249
|
-
03_grounding.json 07_review.json confidence_chart.
|
|
349
|
+
03_grounding.json 07_review.json confidence_chart.svg
|
|
250
350
|
03_critic.json granted_calls.json sources/ code/
|
|
251
351
|
03_completeness.json pass_threads.json
|
|
252
352
|
```
|
|
253
353
|
|
|
254
|
-
`sources/` holds what each cited page actually served: `index.json` lists every URL the run retrieved text from — with the tool, the timestamp, a content hash and the length — and one `<sha256>.txt` per document holds the text itself, redacted. That is what makes a similarity score checkable after the fact rather than a number you have to take on trust; set `
|
|
354
|
+
`sources/` holds what each cited page actually served: `index.json` lists every URL the run retrieved text from — with the tool, the timestamp, a content hash and the length — and one `<sha256>.txt` per document holds the text itself, redacted. That is what makes a similarity score checkable after the fact rather than a number you have to take on trust; set `persist_source_text: false` in `config.yaml` to keep the index and drop the text.
|
|
255
355
|
|
|
256
356
|
In ensemble mode the Pass-1 slot is `01_candidate_1.md`, `01_candidate_2.md`, … — one file per surviving candidate, numbered to match the trace and each claim's `asserted_by_candidates` tags, since no single candidate is "the" response the claims came from.
|
|
257
357
|
|
|
@@ -294,7 +394,7 @@ startup rather than at its first call:
|
|
|
294
394
|
|
|
295
395
|
| | |
|
|
296
396
|
|---|---|
|
|
297
|
-
| **compute** | The six maths tools. Pure functions of their arguments with nothing to interrupt them from the inside, so they run in a separate process that can be stopped —
|
|
397
|
+
| **compute** | The six maths tools. Pure functions of their arguments with nothing to interrupt them from the inside, so they run in a separate process that can be stopped — 20 seconds by default, plus CPU and memory ceilings on Linux |
|
|
298
398
|
| **io** | Anything that reads a file, fetches a page or talks to an MCP server. Each already carries its own limit: a request timeout, a size check before opening, a sandbox |
|
|
299
399
|
| **human** | `ask_user` and `spawn_subagent`, which wait on a person or on a separately metered sub-run. A ten-minute pause here is the feature |
|
|
300
400
|
|
|
@@ -314,7 +414,7 @@ When a compute tool does hit its limit, the model is told which tool and which l
|
|
|
314
414
|
for something smaller instead of retrying the same call:
|
|
315
415
|
|
|
316
416
|
```
|
|
317
|
-
symbolic_math exceeded its
|
|
417
|
+
symbolic_math exceeded its 20s limit and was stopped. The inputs given are too
|
|
318
418
|
large for this operation -- try smaller values.
|
|
319
419
|
```
|
|
320
420
|
|
|
@@ -331,9 +431,9 @@ Because approval ORs, an override can only ever *add* a prompt. There is no way
|
|
|
331
431
|
|
|
332
432
|
| | |
|
|
333
433
|
|---|---|
|
|
334
|
-
| No approval | `web_search`, `fetch_url`, `arxiv_search`, `get_time`, the six maths tools (`symbolic_math`, `linear_algebra`, `probability_stats`, `discrete_math`, `logic`, `geometry`), `load_skill`, `pin`, `unpin`, `ask_user`, `todo_write`, `read_project_doc` |
|
|
335
|
-
| Depends on the call | `read`, `write`, `edit` — decided per path, and all
|
|
336
|
-
| Always | `shell`, `spawn_subagent`, `remember`, `write_project_doc`, and **every MCP tool** |
|
|
434
|
+
| No approval | `web_search`, `fetch_url`, `arxiv_search`, `get_time`, the six maths tools (`symbolic_math`, `linear_algebra`, `probability_stats`, `discrete_math`, `logic`, `geometry`), `load_skill`, `pin`, `unpin`, `ask_user`, `todo_write`, `read_project_doc`, and the three that act on this conversation's own background sessions (`shell_sessions`, `shell_output`, `shell_kill`), and `shell_input` — typing into an interactive shell you already approved (a line naming a protected path still asks, and a Ctrl-C never does) |
|
|
435
|
+
| Depends on the call | `read`, `view_image`, `write`, `edit` — decided per path, and all four are denied by default anyway. `view_image` is also only offered where the image can reach the model: a provider marked `accepts_images` in `providers.json`, outside a research pass |
|
|
436
|
+
| Always | `shell` and the three that start a session (`shell_background`, `shell_monitor`, `shell_interactive`), `spawn_subagent`, `remember`, `write_project_doc`, and **every MCP tool** |
|
|
337
437
|
|
|
338
438
|
Every registered tool appears in that table, and a test asserts it (audit #125): `ToolPermissions` and `ToolApprovals` are plain dataclasses, so "did the table keep up with the registry" is a question the suite can answer instead of a reader. `write_project_doc` is the one the omission mattered for — it is what `/init` uses to write documents into a repository, and §24's I1 gives it a fixed allowlist of document *names* with no path parameter precisely because it is dangerous enough to constrain.
|
|
339
439
|
|
|
@@ -343,31 +443,32 @@ Every registered tool appears in that table, and a test asserts it (audit #125):
|
|
|
343
443
|
|
|
344
444
|
### `shell` is classified, not just approved
|
|
345
445
|
|
|
346
|
-
`shell` ships **disabled** (`
|
|
446
|
+
`shell` ships **disabled** (`tool_permissions.shell: false` in `config.yaml`) and cannot be enabled at runtime, so none of this applies to a default install. If you do enable it, the gate is `shell_approval_mode` in the same file:
|
|
347
447
|
|
|
348
448
|
| mode | behaviour |
|
|
349
449
|
|---|---|
|
|
350
450
|
| `always` | every command is asked about, whatever it does |
|
|
351
|
-
| `tiered` | **shipped.** The classifier decides — see below |
|
|
451
|
+
| `tiered` | **shipped.** The classifier decides — see below. Only a read-only command runs unasked; anything that can run code asks, even inside the container |
|
|
452
|
+
| `contained` | anything the container confines runs unasked unless it needs network, code included; reads outside the workspace and network commands still ask. Flagged on the startup banner and the TUI badge |
|
|
352
453
|
| `never` | nothing is ever asked about |
|
|
353
454
|
|
|
354
|
-
|
|
455
|
+
There is deliberately no second switch: `tool_approvals` has no `shell` key, so nothing here can disagree with the mode. An agent's `approval_overrides` still reaches shell with the same one-way power -- an agent can demand approval for a command the mode would auto-approve, and can never wave one past a gate the mode set. An unknown mode string raises at startup rather than falling back to a default — one direction of that default asks about everything and the other about nothing, and a typo cannot pick.
|
|
355
456
|
|
|
356
|
-
Under `tiered`, each command is classified **once** into what it can do, and the same answer is read by the approval check and by the sandbox that runs it:
|
|
457
|
+
Under `tiered` and `contained`, each command is classified **once** into what it can do, and the same answer is read by the approval check and by the sandbox that runs it:
|
|
357
458
|
|
|
358
|
-
| tier | what it is | where it runs | asked
|
|
359
|
-
|
|
360
|
-
| `INERT` | read-only command, every argument inside the workspace | host | no |
|
|
361
|
-
| `HOST_READ` | read-only, but an argument reaches outside the workspace | host | **yes** |
|
|
362
|
-
| `SANDBOXED` | anything else, no network | container | no, if Docker is confirmed up |
|
|
363
|
-
| `SANDBOXED_NET` | **any** word is on the network allowlist (`curl`, `pip`, `git`, …) — first word only for an INERT command, which cannot chain | container, with network | **yes** |
|
|
364
|
-
| `UNKNOWN` | could not be characterised at all | — | **yes** |
|
|
459
|
+
| tier | what it is | where it runs | asked under `tiered`? | under `contained`? |
|
|
460
|
+
|---|---|---|---|---|
|
|
461
|
+
| `INERT` | read-only command, every argument inside the workspace | container (host when no container runtime is available) | no | no |
|
|
462
|
+
| `HOST_READ` | read-only, but an argument reaches outside the workspace | host | **yes** | **yes** |
|
|
463
|
+
| `SANDBOXED` | anything else, no network — it may run code | container | **yes** | no, if a container runtime (Docker or Podman) is confirmed up |
|
|
464
|
+
| `SANDBOXED_NET` | **any** word is on the network allowlist (`curl`, `pip`, `git`, …) — first word only for an INERT command, which cannot chain | container, with network | **yes** | **yes** |
|
|
465
|
+
| `UNKNOWN` | could not be characterised at all | — | **yes** | **yes** |
|
|
365
466
|
|
|
366
|
-
|
|
467
|
+
Under `tiered` the auto-approved set is narrower than the `read` tool's, which is already unprompted inside the workspace. There is **no list of interpreters** behind that: `python -c` is the obvious case, but `pytest` runs a `conftest.py`, `make` runs a Makefile, and `"python"`, `python3.13` and `echo x | python` are all the same call to a shell, so every command that is not `INERT` is treated as able to run code. Under `contained` a `SANDBOXED` command runs unasked and can do anything code can do inside the container — corrupt the workspace, as `write` and `edit` already can, or read a `.venastine/` directory the workspace contains — bounded to 1 CPU, 2 GB, 200 processes, 120 seconds, no network and no host filesystem.
|
|
367
468
|
|
|
368
469
|
**The argument rule does not parse, deliberately.** Every token after the first is read as a path and required to stay inside the workspace; a flag like `-la` passes only because it is *relative*, not because anything recognised it as a flag. Refusing to interpret shell syntax is what makes the check trustworthy — a classifier that parses is a shell parser, and a parser that is wrong auto-approves something dangerous. The cost is occasional false positives: `grep /etc/passwd notes.txt` searches for a string that looks like a path, and costs one prompt.
|
|
369
470
|
|
|
370
|
-
**Quoted arguments are never inert.** The corollary of not parsing: the raw tokens have to be the real tokens. A quoted command is classified `SANDBOXED` and goes to a container, because the classifier splits on whitespace while the executor splits with `shlex` — and `shlex` strips quotes, so `cat "/etc/passwd"` read as one token *inside* the workspace and then ran as two tokens naming the host's file. Under Docker this costs nothing: `cat "my notes.txt"` is still auto-approved, it simply runs in the container. Fixed in batch 37; `'single quotes'` and `--file="/etc/x"` did it too.
|
|
471
|
+
**Quoted arguments are never inert.** The corollary of not parsing: the raw tokens have to be the real tokens. A quoted command is classified `SANDBOXED` and goes to a container, because the classifier splits on whitespace while the executor splits with `shlex` — and `shlex` strips quotes, so `cat "/etc/passwd"` read as one token *inside* the workspace and then ran as two tokens naming the host's file. Under `contained` with Docker this costs nothing: `cat "my notes.txt"` is still auto-approved, it simply runs in the container. Under `tiered` it asks, as every command that is not `INERT` does. Fixed in batch 37; `'single quotes'` and `--file="/etc/x"` did it too.
|
|
371
472
|
|
|
372
473
|
**Escaped arguments are never inert either.** The same corollary, one character further, and it
|
|
373
474
|
took a second batch to find: `shlex` consumes `\` exactly as it consumes quotes, so
|
|
@@ -387,13 +488,13 @@ is set to something weaker than the shipped default, the harness says so at laun
|
|
|
387
488
|
|
|
388
489
|
**`never` is the old unbounded behaviour, kept on purpose.** In that mode `cat ~/.aws/credentials` runs on the host, unprompted, and its output goes into the model's context. It is reachable by writing the word `never` — which is the fix for [#157](https://github.com/YahyaHammad/Venastine-Research-Harness/issues/157): previously you reached it by switching off a field that read like "stop nagging me".
|
|
389
490
|
|
|
390
|
-
`shell_approval_mode` is **rejected** in `.venastine/settings.json`, by name and with a reason. A project's settings beat your own, and a cloned repository must not be able to set this. Set it in `config.
|
|
491
|
+
`shell_approval_mode` is **rejected** in `.venastine/settings.json`, by name and with a reason. A project's settings beat your own, and a cloned repository must not be able to set this. Set it in `config.yaml`.
|
|
391
492
|
|
|
392
|
-
If your workspace contains a `.venastine/` directory, it is bind-mounted **read-only** inside the container, so a sandboxed command cannot rewrite the context and MCP definitions that feed later prompts. This covers writes on the
|
|
493
|
+
If your workspace contains a `.venastine/` directory, it is bind-mounted **read-only** inside the container, so a sandboxed command cannot rewrite the context and MCP definitions that feed later prompts. This covers writes on the container path only, under Docker or Podman — not reads, and not the subprocess fallback.
|
|
393
494
|
|
|
394
|
-
**The workspace may not be the harness.** The container mounts your workspace read-write, and a sandboxed command with no network is auto-approved inside it — so a workspace pointing at the harness's own directory would be unattended write access to the code about to run next. `AGENT_WORKSPACE` is refused at startup, and by the sandbox, when it *is* or sits *inside* the harness install tree or `~/.config/venastine/`. The two artifact directories `workspace/` and `output/` stay usable, which is the shipped layout; everything else in the install tree is refused, including a module added in a later release — it is an allowlist, so it fails closed. When one of those trees is *nested inside* your workspace instead — a workspace set to your home directory, say — there is nothing to refuse, so it is bind-mounted read-only, along with `providers.json`, the conversation database and the log directory. The guard names the harness that is *running*, so pointing a globally-installed `venastine` at a development clone of its own source still works.
|
|
495
|
+
**The workspace may not be the harness.** The container mounts your workspace read-write, and a sandboxed command with no network is auto-approved inside it — so a workspace pointing at the harness's own directory would be unattended write access to the code about to run next. `AGENT_WORKSPACE` is refused at startup, and by the sandbox, when it *is* or sits *inside* the harness install tree or `~/.config/venastine/`. **Since batch 107 the implicit route is refused too**: with the variable unset the project is the directory you launched from, so launching from the install tree made the harness its own project -- the same state, reached by saying nothing instead of by saying it. The two artifact directories `workspace/` and `output/` stay usable, which is the shipped layout; everything else in the install tree is refused, including a module added in a later release — it is an allowlist, so it fails closed. When one of those trees is *nested inside* your workspace instead — a workspace set to your home directory, say — there is nothing to refuse, so it is bind-mounted read-only, along with `providers.json`, the conversation database and the log directory. The guard names the harness that is *running*, so pointing a globally-installed `venastine` at a development clone of its own source still works.
|
|
395
496
|
|
|
396
|
-
**From approval to execution, one answer throughout.** The classification is computed once per call and the same profile is handed to both the approval check and the sandbox, so what was approved is what runs.
|
|
497
|
+
**From approval to execution, one answer throughout.** The classification is computed once per call and the same profile is handed to both the approval check and the sandbox, so what was approved is what runs. **The container comes from Docker, or from Podman when Docker cannot run one** — probed once per process, Docker first. Podman is used only if it can enforce the memory, CPU and process limits below: a rootless Podman on cgroups v1, or without those controllers delegated to your user, accepts the flags and ignores them, so it is refused and the reason is logged and shown. An inert command runs in that container as a plain argument list with no shell, and on the host only when no runtime is available. Anything else shares the probe's answer between gate and runner: if a runtime was up when the call was approved but gone when it executes, and the only route left is the fallback, the call returns an error telling the model to retry rather than silently downgrading onto the host. With no container runtime available and `allow_insecure_sandbox_fallback: true` in `config.yaml`, non-inert commands fall back to a weakly-isolated host subprocess — prompted per run unless `auto_approve_sandbox_fallback: true` opts that prompt away. Inside the container the workspace is mounted at `/workspace` and output comes back truncated at 50,000 characters (`max_read_chars`); the container runs under a 120-second wall clock, 2048 MB of memory, a single CPU core and a 200-process cap, while the weak fallback enforces its own rlimits instead — 30 CPU-seconds and the same memory ceiling — **on Unix only**. `rlimit` does not exist on Windows, so there that route runs under the wall clock and nothing else, which is worth knowing before you turn it on: it is the route with no filesystem isolation, and on Windows it is also the route with no memory or CPU ceiling. **A third backend exists and ships off: WSL.** With `allow_wsl_backend: true`, `shell`, `shell_background` and `shell_monitor` take a `backend` field the agent sets per call, and `backend: "wsl"` runs the command in a WSL distribution (`wsl_distro`, or WSL's default) instead of the container. It is there for work that genuinely needs your machine or a Linux toolchain the image does not carry — and it gives up everything the container provides: your own files, the network always on, no memory or process limits, no read-only bind over `.venastine/`, and Windows interop that no argv or environment choice can switch off. So it is treated as uncontained for every tier: under `tiered` and `contained` only a read-only command whose arguments are all inside the workspace runs without a prompt, a command naming a protected path segment is refused outright rather than asked about, and the backend appears on the startup banner and the sidebar badge for as long as it is on. An interactive shell cannot run there yet. **A fourth backend exists and also ships off: SSH.** With `allow_ssh_backend: true` and a host configured (`ssh_host`, `ssh_user`, `ssh_remote_workspace` and a PINNED `ssh_host_key`), `backend: "ssh"` runs the command on that machine. It is the strictest of the four to use and the least protected to run on: **nothing there is auto-approved, not even a read-only command**, because the check that decides whether a command's arguments stay inside the workspace resolves them against this machine's filesystem and would be answering about the wrong one. Authentication is a key or a running `ssh-agent` and the harness never asks for or holds a passphrase; a host key that changes is refused rather than accepted; and two things are disclosed rather than fixed — ending a session does not kill the remote command (its in-guest `timeout` does), and `write` saves locally while the shell runs remotely. **The harness can hold the credentials those backends need, encrypted at rest.** `/secrets` in the TUI (or `--secrets` on the CLI) stores named values -- `ssh.<host>.key_passphrase`, `ssh.<host>.login` -- in `~/.config/venastine/secrets.json`, sealed with AES-256-GCM under a master passphrase you type once a session. That is what lets an encrypted SSH key or a password-authenticated host work at all: before it, an encrypted key with no agent simply failed. A stacked `publickey,password` host works too. Nothing is taken from the command line -- every value is read at a masked prompt, because an argv is readable by every process on the machine and lands in your shell history. The file is useless without the passphrase, so a shell command the agent runs reads ciphertext; the plaintext lives in process memory only and is dropped on `/secrets lock`, on quit, and on anything unexpected. A stored value never reaches the model: it is stripped from tool output whatever your redaction setting says. **A command can also be run as root, on those two backends and nowhere else.** A call may set `needs_root`; the harness then prefixes `sudo -k -S -p '' --` and supplies the password stored for that machine as `wsl.<distro>.sudo` or `ssh.<host>.sudo`, on the command's standard input and nowhere else -- never in an argv, an environment or a log, and the command behind `sudo` has its own stdin closed so it cannot read the password either. The container is refused because a command there already runs as root, and the host fallback because Windows elevation is a consent dialog rather than a password prompt. **You are asked every single time**, above both sandbox opt-ins and in every approval mode but `never` -- and the question is asked whether the call declares `needs_root` or merely writes `sudo` itself, so the declaration is not a thing to forget your way around. If no password is stored for that machine the call is refused outright and the refusal names the entry to create: the stored secret is what turns root on at all, and there is no separate switch for it. Two environment knobs affect the mechanics: `AGENT_SHELL` overrides the detected host shell (bash on Linux/macOS, PowerShell on Windows), and `AGENT_SANDBOX_IMAGE` swaps the default `docker.io/library/python:3.13-slim` image (fully qualified, so Podman resolves it without a short-name alias).
|
|
397
498
|
|
|
398
499
|
### "Headless" means *unable to ask*, not "not a GUI"
|
|
399
500
|
|
|
@@ -471,7 +572,7 @@ Whichever you configure (`compaction.strategy` in settings.json), a span too lar
|
|
|
471
572
|
|
|
472
573
|
`pin` keeps recent turns out of any summary (capped at half the compaction trigger per call — a pin is a permanent floor, so refusing beats trimming); `unpin` releases it again when pinned detail goes stale. `/compact` in the TUI triggers a compaction by hand. **When compaction runs depends on what the thread is**: a chat thread folds at a share of the model's context window (85% by default, so 850k on a 1M model and 170k on a 200k one); research passes and subagents compact only at a hard backstop just under that window, wherever they are resumed — spending a model call on a judgement nobody is watching is not worth it mid-run. The chat trigger used to be a flat 40k regardless of model, which meant a 1M-window thread was condensed at 4% of its window.
|
|
473
574
|
|
|
474
|
-
The knobs, all under `compaction` in `settings.json`, each overriding a default in `config.
|
|
575
|
+
The knobs, all under `compaction` in `settings.json`, each overriding a default in `config.yaml`:
|
|
475
576
|
|
|
476
577
|
| Key | Default | Meaning |
|
|
477
578
|
|---|---|---|
|
|
@@ -506,15 +607,23 @@ A skill declaring `additional_tools` is stating a *need*, not granting anything
|
|
|
506
607
|
|
|
507
608
|
An agent declares `spawnable` — whether the `spawn_subagent` tool can actually feed it. A task string in a fresh thread is all a spawn can pass, and an agent that needs a transcript, a thread or a finished research run cannot be given one; spawning it anyway produces a confident answer about nothing. Your own agents are not spawnable unless they say so.
|
|
508
609
|
|
|
509
|
-
|
|
610
|
+
Eleven ship. Five are not spawnable, each because a real caller supplies something a task string cannot carry — `compactor` (a stretch of transcript), `initializer` (a document manifest), `pipeline-reviewer` (a finished research run), `grill-me` and `plan` (the live conversation). Six are:
|
|
510
611
|
|
|
511
612
|
| agent | for | reach it with |
|
|
512
613
|
|---|---|---|
|
|
513
614
|
| `plan` | designing an approach before the work starts — reads what exists, names the decisions, says what would make the plan wrong | `/agent plan` |
|
|
514
615
|
| `explore` | finding where something lives and how it is wired, in a codebase or in the literature, and reporting locations and evidence | `spawn_subagent`, or `/agent explore` |
|
|
515
616
|
| `review` | reading a finished change or document against what it claims to do, and reporting defects with the evidence for each | `spawn_subagent`, or `/agent review` |
|
|
617
|
+
| `build` | implementing a specified change from pointers — reads what exists, makes the smallest diff, reports what changed plus how it was verified | `spawn_subagent`, or `/agent build` |
|
|
618
|
+
| `test` | verifying a change against its claim — reproduces, runs the checks, reports pass/fail with the exact command and what was not covered | `spawn_subagent`, or `/agent test` |
|
|
619
|
+
| `writer` | turning notes, claims or sources into clear structured prose for a named audience — reports, READMEs, changelogs, decision records | `spawn_subagent`, or `/agent writer` |
|
|
620
|
+
| `general` | scoping a task's intent, splitting it into self-contained sub-tasks, delegating to specialized subagents in parallel, synthesizing their answers | `spawn_subagent`, or `/agent general` |
|
|
621
|
+
|
|
622
|
+
`build`, `test`, `writer`, `explore` and `review` are leaves: they take a task string as their entire input and cannot spawn further. `general` is the one spawnable branch — the spawning discipline lives there and nowhere else, so users who want a less constricted experience change one file or add their own. `plan` keeps its own spawning ability for interactive `/agent` use but is not itself spawnable.
|
|
516
623
|
|
|
517
|
-
|
|
624
|
+
An agent can also name **which** agents it may spawn, with `spawn_targets`. `plan` is the shipped case: it may spawn `explore`, `review`, `writer` and `test`, and asking it for `build` or `general` is refused with a reason rather than quietly obeyed. That is the point of planning as its own turn — you read the plan and change your mind before anything is written. Say nothing and an agent may spawn anything spawnable, which is the default every definition had before the field existed; a list only ever narrows, and narrows again for anything it spawns in turn.
|
|
625
|
+
|
|
626
|
+
`explore`, `review`, `build`, `test` and `writer` are **read-only or write-only by omission**: none of them lists `spawn_subagent`, `remember` or `write_project_doc`, so no configuration makes one reachable. `build` is the exception that proves the shape — it declares `write`/`edit` because implementing means writing, while the other four simply absent them. They all list tools (`read`, `shell`) which are [denied by default](#what-needs-approval-by-default) and cannot be enabled at runtime — so on a stock install `explore` works from `read_project_doc` and the three network tools, and all become code agents only where you have enabled file access in `config.yaml`. Approving a spawn of a leaf grants nothing standing: `shell` carries a per-call gate, so it is excluded from every grant path by name and each non-inert command still asks.
|
|
518
627
|
|
|
519
628
|
Fourteen skills ship, under `security/`, `crypto/`, `math/`, `research/` and `software/` — methodologies for reviewing code, debugging, designing tests, designing experiments, statistical inference, reproducibility, evaluating sources, technical writing, numerical methods, formal specification, literature review, proof writing, cryptography verification and cybersecurity research.
|
|
520
629
|
|
|
@@ -544,7 +653,7 @@ An agent's or a skill's `name` and `description` go straight into the system pro
|
|
|
544
653
|
|
|
545
654
|
### MCP servers
|
|
546
655
|
|
|
547
|
-
Configured in `mcp.json`, at `~/.config/venastine/mcp.json` or `.venastine/mcp.json
|
|
656
|
+
Configured in `mcp.json`, at `~/.config/venastine/mcp.json` or `.venastine/mcp.json`. **The user-level one is created empty on startup if it is absent**, and the launch says where it is — two plausible homes and no way to tell from inside a session meant an edit could land in a file the harness never reads. `/init --config` creates an empty project one to fill in. Claude Code compatible, and unrecognised keys are ignored so a config shared with another client works as-is:
|
|
548
657
|
|
|
549
658
|
```json
|
|
550
659
|
{"mcpServers": {"files": {"command": "npx", "args": ["-y", "@example/server"]}}}
|
|
@@ -568,6 +677,18 @@ The first connection to a **user-level** server asks once, showing the resolved
|
|
|
568
677
|
|
|
569
678
|
### The TUI
|
|
570
679
|
|
|
680
|
+
Type `@` in a chat message to complete a file or folder from the project directory. Match by
|
|
681
|
+
filename or relative path, use arrows to choose and Tab or Enter to insert. Names with spaces
|
|
682
|
+
are quoted, such as `@"docs/my notes.md"`. A mention tells the agent what to inspect; it does
|
|
683
|
+
not attach file contents. Normal file-access permissions still apply.
|
|
684
|
+
|
|
685
|
+
The path list loads in the background at startup. Files created by the agent's `write` tool
|
|
686
|
+
refresh it automatically; files you create yourself appear after restart. Ignored paths are
|
|
687
|
+
hidden by default; `/mentions ignored on` includes them for this session, and `/mentions`
|
|
688
|
+
shows the source and any limits. Git is optional: without a usable repository/binary, a
|
|
689
|
+
fallback skips common build/cache directories. The panel labels that fallback. Up to 50,000
|
|
690
|
+
paths are cached and 200 matches offered; narrow the query when a limit is shown.
|
|
691
|
+
|
|
571
692
|
| Command | What it does |
|
|
572
693
|
|---|---|
|
|
573
694
|
| `/help` | List every registered command with its usage |
|
|
@@ -577,15 +698,18 @@ The first connection to a **user-level** server asks once, showing the resolved
|
|
|
577
698
|
| `/model [[PROVIDER] name]` | Switch provider and/or model, and it is remembered for the next launch. Refuses mid-turn, warns on a missing key, revalidates effort against the new model, and notes if an active agent pins its own |
|
|
578
699
|
| `/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 |
|
|
579
700
|
| `/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 |
|
|
701
|
+
| `/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 |
|
|
580
702
|
| `/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 |
|
|
581
703
|
| `/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 |
|
|
582
704
|
| `/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 |
|
|
583
705
|
| `/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 |
|
|
706
|
+
| `/config [key] [value]` | Browse and set the harness's own settings without leaving the session. Typing `/config ` lists all 133 of them in the same panel the slash commands use, with the values each one takes and the value in the file; completing a key then offers that key's values. A value you have already changed reads `pending restart` until you relaunch, and bare `/config` lists every one of them, old to new — so several settings can be changed in a row and applied together. Bare `/config <key>` explains one, including what outranks it — an environment variable, a `settings.json` key — and containers are listed but edited in the file. A write goes through the whole document's validation first, keeps every comment in `config.yaml`, and offers to relaunch, because values are read once at startup. The nine AUTHORITY keys ask first, naming what the key permits |
|
|
584
707
|
| `/claims [run id]` | Open the claims view — tier, grounding status, assumption flags, score breakdown per claim — during a run or afterwards (**ctrl+l**) |
|
|
585
708
|
| `/copy [last\|report\|claims\|conversation\|all] [--file <path>]` | Copy out of the session. Defaults to the last response; `conversation` is the exchange alone — your turns, the answers, the reasoning, the tool calls and the diffs; `all` is everything on screen (the harness's own lines included) plus report plus claims. Clipboard delivery cannot be confirmed, so `--file <path>` is the route that provably worked |
|
|
586
709
|
| `/threads` | Conversations-only picker — research runs' internal threads excluded — most recently active first, capped at 200 with a notice (**ctrl+t**) |
|
|
587
710
|
| `/resume <thread-id>` | Open any thread by id, however old |
|
|
588
711
|
| `/new` | Start a fresh thread; created lazily on your next message, so `/new` twice leaves nothing behind |
|
|
712
|
+
| `/kill [session-id]` | Stop a background session. Bare, it opens the picker **ctrl+b** opens; with an id it stops that one. Deliberately usable *while* sessions are blocking the prompt — it is the way out of that block, so it is the one command that never refuses for being busy |
|
|
589
713
|
| `/agent [name\|default]` | Make an agent active for subsequent turns; `default` clears. Active skills are re-checked against the new agent's tool policy |
|
|
590
714
|
| `/goal [text\|clear]` | Persistent objective for this thread — injected into every turn in either shell, mirrored in a banner |
|
|
591
715
|
| `/grill-me` | One turn under the grill-me agent inside the current thread, reading the live history rather than a digest of it |
|
|
@@ -595,9 +719,10 @@ The first connection to a **user-level** server asks once, showing the resolved
|
|
|
595
719
|
| `/summary` | Distil this conversation and show it. Describes; does **not** fold — that is `/compact` |
|
|
596
720
|
| `/ref [--list\|--clear]` | Pick another conversation and attach its summary to this one as standing context; `--list` and `--clear` manage attachments |
|
|
597
721
|
| `/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 |
|
|
722
|
+
| `/mentions [ignored on\|off]` | Show file mention status or include ignored paths for this session |
|
|
598
723
|
| `/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
724
|
|
|
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.
|
|
725
|
+
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, or the name on a `spawn_subagent` line to read what that agent did, or the name on a `shell_background`, `shell_monitor` or `shell_interactive` line to read that session -- its command, why it was started, what it printed, and what became of it. A session the harness no longer holds (it aged out, or you restarted) opens the same way and shows what the agent was given, saying so; a live one refreshes as it writes. While sessions are running the sidebar lists them, and clicking a row opens it; **ctrl+g** lists the runs going on right now and opens one from the keyboard · **ctrl+b** stops a background session, and always asks which one rather than killing on a single press. While background sessions are running the prompt and most commands are refused — `ctrl+b`, `/kill`, answering a dialog and quitting stay usable, because they are the ways out.
|
|
601
726
|
|
|
602
727
|
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
728
|
|
|
@@ -617,7 +742,7 @@ Only `AGENTS.md` is written for you in full; the rest arrive as skeletons with r
|
|
|
617
742
|
|
|
618
743
|
`/init --config` is the other half, and it is independent of the two above: it writes `.venastine/settings.json` and `.venastine/mcp.json`, and creates `.venastine/agents/` and `.venastine/skills/`. On its own it makes **no model call** and costs nothing — no document set, no question about which kind of project this is; combined (`/init --software --config`) it does both under one confirmation. An existing `settings.json` or `mcp.json` is never touched, per file, so a project with one and not the other gets the other. From the CLI it is `--init --project-config`.
|
|
619
744
|
|
|
620
|
-
The settings file it writes is **every key with a shipped default, at that default** — because the file cannot explain itself. An unknown key raises at startup, so there is no comment syntax, no `$schema` line and no way to leave a key in the file but switched off; the scaffold is the schema. Six keys are deliberately left out, because something reads them by *presence* rather than by value, so writing their own default would decide rather than restate: `default_provider` and `default_model` (adding either discards a model you picked with `/model` in that project), `effort` (makes every launch probe the provider's effort table), `compaction.trigger_tokens` (disables the window-derived trigger, invisibly), `ensemble_mode` and `research.subagent_review` (both defer to `config.
|
|
745
|
+
The settings file it writes is **every key with a shipped default, at that default** — because the file cannot explain itself. An unknown key raises at startup, so there is no comment syntax, no `$schema` line and no way to leave a key in the file but switched off; the scaffold is the schema. Six keys are deliberately left out, because something reads them by *presence* rather than by value, so writing their own default would decide rather than restate: `default_provider` and `default_model` (adding either discards a model you picked with `/model` in that project), `effort` (makes every launch probe the provider's effort table), `compaction.trigger_tokens` (disables the window-derived trigger, invisibly), `ensemble_mode` and `research.subagent_review` (both defer to `config.yaml` only while absent). Set any of those by hand and they work normally. Everything the scaffold does write changes nothing until you edit it — and because a project's `settings.json` beats yours by *presence*, the command tells you which of your own keys the new file has taken over before it asks to write it.
|
|
621
746
|
|
|
622
747
|
`/summary` distils this conversation and shows it — it does **not** shorten what the model sees; that is `/compact`. `/ref` picks another conversation, summarises it, and attaches that summary to this one as standing context: you choose what crosses between threads, so nothing read or argued in one conversation can steer another without your say-so. `/ref --list` and `/ref --clear` are the way back out, and the summaries are labelled so the model knows they are not part of this conversation. From the CLI the same two are launch flags: `--summary <thread>` and a repeatable `--ref <thread>`.
|
|
623
748
|
|
|
@@ -712,7 +837,7 @@ A level is validated against the model that will **receive** it, not the one it
|
|
|
712
837
|
|---|---|---|
|
|
713
838
|
| Anthropic | `low`, `medium`, `high`, `xhigh`, `max` — whichever the model reports supported | Queried live from the Models API, so newly released Anthropic models need no entry anywhere |
|
|
714
839
|
| OpenAI-compatible | `low`, `medium`, `high` assumed for unknown models | Static table (`config.MODEL_EFFORT_LEVELS`). Known non-reasoning models — gpt-4o family, gpt-3.5 — ship with *empty* lists, meaning "takes no effort parameter": a requested level is dropped cleanly instead of 400ing every call. An unlisted model gets the assumption plus a WARNING naming it |
|
|
715
|
-
| Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary
|
|
840
|
+
| Google | Levels map to integer thinking budgets, `low`→2,048 through `max`→dynamic | Mapped at the boundary and sent as `thinking_budget`. On since batch 172, when the `google-genai` pin moved to 2.29.0; an unlisted Gemini model gets the default level set plus a WARNING, like any other unlisted model |
|
|
716
841
|
|
|
717
842
|
**Seeing the thinking is separate from doing it.** Effort is what makes the model reason; whether the API hands those thoughts back to the client is a different question, and the answer varies by provider. Reasoning streams into the transcript on **Anthropic** and on OpenAI-compatible providers that send it — DeepSeek, Qwen, Z.AI, OpenRouter. It is absent on **OpenAI**, whose Chat Completions endpoint returns no reasoning text at all, and on **Google**, whose request deliberately does not ask for thought summaries: those would be billed as extra output for something the model produces either way. On those two the turn still thinks; you just do not see it. `tui.show_thinking` and `/thinking` control the display, never the reasoning.
|
|
718
843
|
|
|
@@ -732,11 +857,13 @@ Three things can end a turn or pass early:
|
|
|
732
857
|
|
|
733
858
|
The CLI names the figures behind an early stop — billed this turn, and the thread's measured context size — rather than a bare reason, because "budget exceeded" invites exactly the misreading that there is a size problem.
|
|
734
859
|
|
|
735
|
-
Other ceilings worth knowing: the six maths tools run in killable subprocesses under a
|
|
860
|
+
Other ceilings worth knowing: the six maths tools run in killable subprocesses under a 20-second wall clock (`tool_compute_timeout_s`) and are told which tool and which limit stopped them; pre-granted tool calls cap at 150 per research run (`MAX_GRANTED_TOOL_CALLS`), degrading to asking when exhausted; subagent nesting stops at depth 2 (`SUBAGENT_MAX_DEPTH`) and at most three subagents of one turn run at once (`SUBAGENT_MAX_PARALLEL`), with anything beyond that running in waves; attended prompts expire after 600 seconds (`ATTENDED_APPROVAL_TIMEOUT_S`), denying that one call while the run continues.
|
|
861
|
+
|
|
862
|
+
Subagents spawned in one model response run **concurrently**, up to `SUBAGENT_MAX_PARALLEL`. Their answers come back to the model in the order it asked for them however they finish, one approval question reaches you at a time, and the sidebar draws them as a tree rather than a chain. The database runs in SQLite's WAL mode to keep their writes from contending, which means `app.db` is accompanied by `app.db-wal` and `app.db-shm` while the harness is open — both are gitignored, and excluded from `git archive`, because a WAL file holds recently written messages.
|
|
736
863
|
|
|
737
864
|
### Logging
|
|
738
865
|
|
|
739
|
-
Two sinks from startup: stderr, and a rotating file — `logs/app.log` in the working directory, 1 MB per file, three backups kept. `AGENT_LOG_LEVEL` sets verbosity (a name like `INFO` or a number like `20`;
|
|
866
|
+
Two sinks from startup: stderr, and a rotating file — `logs/app.log` in the working directory, 1 MB per file, three backups kept. `AGENT_LOG_LEVEL` sets verbosity (a name like `INFO` or a number like `20`; anything else prints a warning naming the value and runs at `INFO`, as an unwritable `AGENT_LOG_FILE` does) and `AGENT_LOG_FILE` moves the file, creating the parent directory if needed. The file formatter redacts secret-shaped strings on the way out — the same patterns tool outputs get — because a failing tool's traceback routinely carries the request that produced it, and for an HTTP client that is a URL with the key in it.
|
|
740
867
|
|
|
741
868
|
In the TUI stderr is detached before the screen is taken (anything written there would paint over the rendered UI and vanish on the next repaint); the rotating file keeps everything, and WARNING-and-above is routed into the transcript so warnings stay visible where you are looking.
|
|
742
869
|
|
|
@@ -751,9 +878,9 @@ In the TUI stderr is detached before the screen is taken (anything written there
|
|
|
751
878
|
| `trusted_projects.json` | workspace-trust store | user-level (`~/.config/venastine/`); written by the trust prompt or `--trust-project`, keyed to resolved path + content hash |
|
|
752
879
|
| `AGENTS.md` | project context for the model | project root; covered by workspace trust |
|
|
753
880
|
|
|
754
|
-
Precedence for provider and model is CLI flag > `settings.json` > `config.
|
|
881
|
+
Precedence for provider and model is CLI flag > `settings.json` > `config.yaml`. Two different merge orders, deliberately:
|
|
755
882
|
|
|
756
|
-
- **Inside `settings.json`, project beats user** — this is the one file where "more specific wins" holds, which is exactly why the
|
|
883
|
+
- **Inside `settings.json`, project beats user** — this is the one file where "more specific wins" holds, which is exactly why the five authority-bearing keys below are rejected there by name. Nested objects merge key-by-key across tiers.
|
|
757
884
|
- **MCP servers, agents and skills run harness > user > project**, inverted from the usual rule, because there "more specific" means "arrived with a repository you cloned".
|
|
758
885
|
|
|
759
886
|
#### Every `settings.json` key
|
|
@@ -766,7 +893,7 @@ An unknown key raises at startup, naming the file and the key — a typo must ne
|
|
|
766
893
|
| `default_model` | string | `claude-sonnet-5` | Used unless `--model` overrides |
|
|
767
894
|
| `effort` | string | `"high"` | Reasoning effort for chat and research; `"auto"` clears even this. See [Reasoning effort](#reasoning-effort) |
|
|
768
895
|
| `max_token_budget` | int \| null | null — uncapped | Per-run billed-spend ceiling. See [Budgets and stop conditions](#budgets-and-stop-conditions) |
|
|
769
|
-
| `ensemble_mode` | bool | `false` | Master switch for ensemble Pass 1; the roster lives in `config.
|
|
896
|
+
| `ensemble_mode` | bool | `false` | Master switch for ensemble Pass 1; the roster lives in `config.yaml` |
|
|
770
897
|
| `ensemble_n` | int | — | Accepted with a warning; vestigial — the count now derives from the roster |
|
|
771
898
|
| `compaction` | object | — | Seven keys tabulated in [the compaction section](#long-conversations-condense-themselves) above |
|
|
772
899
|
| `tui.theme` | string | — | One of the fourteen theme names; validated at use and falls back rather than blocking startup. Outranked by a theme you picked with `/theme` — until you change this value, which re-asserts it |
|
|
@@ -777,46 +904,56 @@ An unknown key raises at startup, naming the file and the key — a typo must ne
|
|
|
777
904
|
| `research.approval_mode` | string | `"none"` | `"attended"` makes research runs ask about every gated call, as if launched with `--attended` |
|
|
778
905
|
| `research.subagent_review` | bool | `false` | Review on by default, as if launched with `--review`; escaped per run with `--no-review` |
|
|
779
906
|
|
|
780
|
-
|
|
907
|
+
Five keys are rejected **by name** — well-formed shapes that will never load, because a project tier that could set them would decide what runs without being asked:
|
|
781
908
|
|
|
782
909
|
| Rejected key | Why |
|
|
783
910
|
|---|---|
|
|
784
|
-
| `shell_approval_mode` | Decides whether shell commands are asked about at all; set `
|
|
911
|
+
| `shell_approval_mode` | Decides whether shell commands are asked about at all; set `shell_approval_mode` in `config.yaml` instead |
|
|
912
|
+
| `ensemble_models` | A roster chooses which providers N research passes call, so a cloned repository could point them at endpoints you never configured and multiply the run's cost by the length of its list; set `ensemble_models` in `config.yaml` instead |
|
|
913
|
+
| `critic_model` | Names a provider every claim is sent to; use `/critic`, which writes a user-tier store, or set `critic_model` in `config.yaml` |
|
|
914
|
+
| `embedder_model` | Names a provider sent claim text and the text of every page a run fetched; use `/embedder`, or set `embedder_model` in `config.yaml` |
|
|
785
915
|
| `research.granted_tools` | A persisted grant list could only ever *remove* prompts — standing authorisation carried by any repo you clone. Grants are per-run flags precisely so they cannot be |
|
|
786
916
|
|
|
787
|
-
#### `config.
|
|
917
|
+
#### `config.yaml`-only settings
|
|
788
918
|
|
|
789
|
-
Deliberately not settings.json keys: editing these means editing the file
|
|
919
|
+
Deliberately not settings.json keys: editing these means editing the harness's own file, which has exactly one location and no override variable, so nothing a cloned repository carries can reach them. `CONFIG_ARCHITECTURE.md` carries the argument for each.
|
|
790
920
|
|
|
791
|
-
|
|
|
921
|
+
| Key | Default | Controls |
|
|
792
922
|
|---|---|---|
|
|
793
|
-
| `
|
|
794
|
-
| `
|
|
795
|
-
| `
|
|
796
|
-
| `
|
|
797
|
-
| `
|
|
798
|
-
| `
|
|
799
|
-
| `
|
|
800
|
-
| `
|
|
801
|
-
| `
|
|
802
|
-
| `
|
|
803
|
-
| Sandbox bounds | image `python:3.13-slim`;
|
|
804
|
-
|
|
|
805
|
-
| `
|
|
806
|
-
| `
|
|
807
|
-
| `
|
|
808
|
-
| `
|
|
809
|
-
| `
|
|
810
|
-
| `
|
|
811
|
-
| `
|
|
812
|
-
| `
|
|
813
|
-
| `
|
|
814
|
-
| `
|
|
815
|
-
| `
|
|
816
|
-
| `
|
|
817
|
-
| `
|
|
818
|
-
| `
|
|
819
|
-
| `
|
|
923
|
+
| `critic_model` | `null` | Routes passes 3a/3b/6c to a different `{provider_name, model}` |
|
|
924
|
+
| `ensemble_models` (with `ensemble_mode`) | `null` (off) | Pass-1 roster; fewer than two distinct pairs is refused |
|
|
925
|
+
| `default_effort` | `high` | Effort when neither flag nor settings speaks |
|
|
926
|
+
| `model_effort_levels` | see file | Per-model level lists for non-Anthropic providers; an entry mapped to an *empty* list means "takes no effort parameter" and drops the level cleanly |
|
|
927
|
+
| `google_thinking_budgets` | low→2,048 … max→dynamic | Google level→thinking-token map |
|
|
928
|
+
| `models_rejecting_sampling_params` | current Anthropic models, and the two Gemini models that ignore them | The Anthropic models 400 on temperature/top_p/top_k and the Gemini ones ignore them; such parameters are dropped with a WARNING rather than sent. OpenAI's reasoning models are handled by effort, not by this list |
|
|
929
|
+
| `model_context_windows` / `default_context_window` | 256k fallback | The **fallback** for the window, not the only source: Anthropic and Google report it on their model endpoints, and the OpenAI-compatible providers that carry it (Groq, Mistral, Together, OpenRouter) are read through one alias sniff. This table answers for the ones that report nothing (OpenAI, DeepSeek, Perplexity). Feeds the research-pass compaction backstop **and** the summarizer's one-call input budget; an unknown model warns once and assumes the default. Keys are stored normalized — no date suffix, no `vendor/` prefix |
|
|
930
|
+
| `shell_approval_mode` | `tiered` | The shell gate: `always` / `tiered` / `never`; a bad value raises at import. Rejected in settings.json by name, see above |
|
|
931
|
+
| `network_allowed_commands` | pip, curl, git, npm, … | Binaries granted network access inside the sandbox. Matched against **every** word of a command that needs a sandbox, so `cd x && pip install .` is recognised and asked about — and against the **first word only** of an inert one, which cannot chain, so `grep pip notes.txt` still runs unprompted. This list is a *lexical* test, so since ROADMAP_v3 §50 the agent can also declare `requires_network: true` on `shell`, `shell_background`, `shell_monitor` and `shell_interactive` for anything the word list cannot see — an inline script that opens a socket, say. The declaration only ever ADDS network access, and the command is then asked about wherever your approval mode would allow a prompt |
|
|
932
|
+
| `inert_commands` | ls, cat, grep, wc, … | Read-only commands eligible to run unprompted under `tiered` — as a plain argument list in the container, or on the host only when no container runtime is available |
|
|
933
|
+
| Sandbox bounds | image `docker.io/library/python:3.13-slim`; 120 s, 2048 MB, 1 CPU core, 200 pids — under Docker, or Podman when Docker cannot run the sandbox. The container's CPU control is a RATE (`--cpus 1`), so `sandbox_cpu_seconds` (30 CPU-s) is a budget the weak fallback enforces instead, and on Unix only | `sandbox_docker_image`, `sandbox_timeout_seconds`, `sandbox_memory_mb`, `sandbox_cpu_seconds`, `sandbox_max_pids` |
|
|
934
|
+
| Background sessions | 3600 s cap; 4 live; 10 consecutive wakes; first 10,000 + last 190,000 characters of output kept, in memory only | `shell_session_timeout_cap_s`, `shell_session_max_live`, `shell_session_max_consecutive_wakes`, `shell_session_output_head_chars`, `shell_session_output_tail_chars` |
|
|
935
|
+
| `allow_insecure_sandbox_fallback` / `auto_approve_sandbox_fallback` | `false` / `false` | Enable, then de-prompt, the weak host-subprocess fallback |
|
|
936
|
+
| `allow_wsl_backend` / `wsl_distro` | `false` / `''` | Let the agent ask for a command to run in WSL, and which distribution. WSL is not a sandbox — see below |
|
|
937
|
+
| `allow_ssh_backend` / `ssh_*` | `false` / `''` | Let the agent ask for a command to run on one configured remote host. Nothing runs there unasked; the host key is pinned and auth is key-or-agent only — see below |
|
|
938
|
+
| `redact_tool_outputs` | `true` | Master switch for output redaction. Never affects input refusals, the depth-cap bound, or the log formatter's own guard |
|
|
939
|
+
| `tool_compute_timeout_s` | 20 | Wall clock per maths-tool subprocess |
|
|
940
|
+
| `max_granted_tool_calls` | 150 | Pre-granted calls per research run before it must ask again |
|
|
941
|
+
| `attended_approval_timeout_s` | 600 | Attended prompt deadline; expiry denies that call while the run continues |
|
|
942
|
+
| `subagent_review` | `false` | Shipped default for the post-pipeline review |
|
|
943
|
+
| `max_review_findings` / `max_review_refinements` | 25 / 3 | Consent-fatigue caps on the review stage |
|
|
944
|
+
| `max_pipeline_retries` / `max_json_retries` | 2 / 2 | Revise/re-validate rounds per claim; corrective attempts per malformed pass payload |
|
|
945
|
+
| `max_iterations` | 50 | Step ceiling for a turn or pass absent an agent's own `max_steps` |
|
|
946
|
+
| `subagent_max_depth` | 2 | `spawn_subagent` nesting limit |
|
|
947
|
+
| `subagent_max_parallel` | 3 | How many subagents of one model response run at once; 1 makes them sequential again |
|
|
948
|
+
| `pin_max_trigger_fraction` | 0.5 | Largest share of the trigger one pin may protect |
|
|
949
|
+
| `compaction_trigger_fraction` | 0.90 | Share of the context window a thread may fill before it folds. Applied to the HEADROOM, which is clamped by the two keys below — so it is exact at 160k and up, and a floor beneath that |
|
|
950
|
+
| `compaction_min_headroom_tokens` / `compaction_max_headroom_fraction` | 16,000 / 0.25 | Floor and cap on the room left between the trigger and the window. Nothing recovers from a prompt that overflows the window, and one capped read is 12,500 tokens, so a 64k model keeps 16,000 rather than the 6,553 a bare share leaves |
|
|
951
|
+
| `max_injected_memories` / `max_injected_refs` / `max_todo_items` | 50 / 3 / 50 | Prompt-injection caps; refs and todos refuse past the cap rather than trimming silently |
|
|
952
|
+
| `summary_target_chars` | 2000 | Size cap on whole-thread summaries injected via `/ref` |
|
|
953
|
+
| `max_catalog_text_chars` | 300 | Cap on an agent/skill `name` + `description` entering system prompts |
|
|
954
|
+
| `init_read_chars` / `init_max_steps` | 20,000 / 12 | `/init` per-read volume; step-ceiling fallback (the initializer agent's own frontmatter sets 12, which wins) |
|
|
955
|
+
| `init_max_hub_chars` / `init_diff_shown_lines` | 1,000,000 / 2,000 | Largest existing `AGENTS.md` `/init` revises (above it, it stops before any model call); most diff lines it prints before asking |
|
|
956
|
+
| `teardown_budget_s` | 10 | Shared wall clock for MCP shutdown; stragglers are named in a WARNING |
|
|
820
957
|
|
|
821
958
|
#### Environment variables
|
|
822
959
|
|
|
@@ -826,9 +963,9 @@ Deliberately not settings.json keys: editing these means editing the file in you
|
|
|
826
963
|
| `AGENT_PROVIDERS_FILE` | `providers.json` | Credential-file location |
|
|
827
964
|
| `APP_DB_PATH` | `app.db` | SQLite database path |
|
|
828
965
|
| `AGENT_OUTPUT_DIR` | `./output` | Research artifacts root |
|
|
829
|
-
| `AGENT_WORKSPACE` | `./workspace` | File-tools and sandbox workspace root. **When you set it, it is also the project**: workspace trust, `.venastine/`, `/init`'s destination, `output/` and project-scoped memories all follow it rather than the directory you launched from |
|
|
966
|
+
| `AGENT_WORKSPACE` | `./workspace` | File-tools and sandbox workspace root. **When you set it, it is also the project**: workspace trust, `.venastine/`, `/init`'s destination, `output/` and project-scoped memories all follow it rather than the directory you launched from. Unset, the project is the launch directory — and launching from the harness's own install tree is refused (exit 2), because that would make the harness its own project. The `workspace_dir` key in `config.yaml` sets the workspace but **not** the project on its own -- the rule is the presence of this variable, never its value -- so the file's way of saying it is the `workspace_is_project` key beside it |
|
|
830
967
|
| `AGENT_SHELL` | auto-detect | Host shell binary for the `shell` tool |
|
|
831
|
-
| `AGENT_SANDBOX_IMAGE` | `python:3.13-slim` | Sandbox container image |
|
|
968
|
+
| `AGENT_SANDBOX_IMAGE` | `docker.io/library/python:3.13-slim` | Sandbox container image, under Docker or Podman |
|
|
832
969
|
| `AGENT_LOG_LEVEL` | `INFO` | Log verbosity — name or numeric level |
|
|
833
970
|
| `AGENT_LOG_FILE` | `logs/app.log` | Rotating log location |
|
|
834
971
|
| `VENASTINE_REDACT_OFF` | unset | Truthy value disables tool-output pattern redaction for one run. The environment can only ever weaken redaction, never restore it past the constant — and input refusals, the depth-cap bound and the log formatter's guard stay on regardless |
|
|
@@ -843,6 +980,7 @@ Deliberately not settings.json keys: editing these means editing the file in you
|
|
|
843
980
|
| `is_v1_compatible` | `true` routes the provider through the OpenAI-compatible translation |
|
|
844
981
|
| `supports_stream_usage` | Promises streamed responses carry token usage. If a stream then ends with none, the harness **raises** rather than accounting zero tokens — a silent zero would disable the budget stop condition while looking healthy. Endpoints that don't return streaming usage ship with `false` |
|
|
845
982
|
| `echoes_reasoning` | Opt in to sending this provider's own reasoning back on the next request (§44). Off everywhere by default: there is no standard for it the way there is for receiving reasoning — DeepSeek documents that `reasoning_content` must not be supplied on input and returns a 400, while OpenRouter accepts it for some models and ignores it for others. Anthropic needs no flag; its thinking blocks are signed and are echoed to the model that produced them automatically |
|
|
983
|
+
| `accepts_images` | Opt in to delivering images that `view_image` attaches (ROADMAP_v3 §81). It must be JSON `true`; a quoted `"true"` does not count. It needs setting per endpoint because whether a request with an image succeeds depends on the endpoint and often the model, and sending one to a model without vision fails the request. The example sets it for ANTHROPIC and GOOGLE, the two providers where every chat model accepts images. For an OpenAI-compatible endpoint serving a vision model, add it yourself; the image then travels in a harness message after the tool results, because that API's tool messages carry text only. On GOOGLE the image travels the same way, after the function responses, and a GIF becomes a note there rather than an image. A provider without the flag gets a note saying the image was not sent, and `view_image` is not offered to it at all |
|
|
846
984
|
|
|
847
985
|
`mcp.json` entries are tabulated under [MCP servers](#mcp-servers).
|
|
848
986
|
|
|
@@ -852,7 +990,7 @@ Deliberately not settings.json keys: editing these means editing the file in you
|
|
|
852
990
|
|
|
853
991
|
**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).
|
|
854
992
|
|
|
855
|
-
**Remaining:** nothing in
|
|
993
|
+
**Remaining:** nothing in `ROADMAP.md` or `ROADMAP_v2.md`, and §10's revisit is now closed. `ROADMAP_v3.md` §49–§52, §54, §55, §58 and §61–§83 are built. The remaining sections are §53 (rolling network-I/O budgets), §56 (a decision-model shell classifier), §57 (`/submodel`), §59 (memory selection and agent cycling), and §60 (Unified Harness Protocol compliance), each specified and awaiting detailed design. §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 9 and 10 are open. 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.
|
|
856
994
|
|
|
857
995
|
**Not finished, though: an audit is open.** Both roadmaps being built is not the same as the
|
|
858
996
|
code being clean, and saying only the first would be the "built and runs are different claims"
|
|
@@ -863,33 +1001,34 @@ worked in numbered fix batches — 32 so far, each recorded in `DEVLOG.md` and
|
|
|
863
1001
|
`tests/BREAKING_CHANGES.md` with what was measured and what would break the fix.
|
|
864
1002
|
|
|
865
1003
|
**#157 — `shell`'s unbounded auto-approval — is closed** by batch 8 and ROADMAP_v2 §28; the
|
|
866
|
-
classifier is described under *Security model* above. If you have a fork or a local
|
|
867
|
-
note that
|
|
868
|
-
`
|
|
1004
|
+
classifier is described under *Security model* above. If you have a fork or a local config,
|
|
1005
|
+
note that shell approval is governed solely by `shell_approval_mode` -- `tool_approvals`
|
|
1006
|
+
deliberately has no `shell` key, so an old file carrying one is refused at startup
|
|
1007
|
+
naming the key — see `tests/BREAKING_CHANGES.md` §24.
|
|
869
1008
|
|
|
870
|
-
Run the test suite with `pytest` —
|
|
1009
|
+
Run the test suite with `pytest` — 8909 tests, fully offline, no API keys needed. 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. Four further tests are marked `integration` and excluded by default: three spawn a real stdio MCP server, the fourth runs an external program through the host fallback shell (`pytest -m integration`).
|
|
871
1010
|
|
|
872
1011
|
## Documentation
|
|
873
1012
|
|
|
874
1013
|
This file is the user-facing one. For working on the code:
|
|
875
1014
|
|
|
876
1015
|
- **[AGENTS.md](./AGENTS.md)** — the agent-context file, and the place to start. `CLAUDE.md` and `QWEN.md` are pointers to it so a tool looking for a particular filename finds one without the guidance being duplicated.
|
|
877
|
-
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — file-by-file contracts, what belongs where, and the known gotchas. Read before changing anything non-trivial, especially around persistence (`database.py` / `storage.py` / `core/memory.py` are three distinct and easily confused responsibilities).
|
|
878
|
-
- **[ROADMAP.md](./ROADMAP.md)** and **[
|
|
879
|
-
- **[DEVLOG.md](./DEVLOG.md)** — what was followed, what was deviated from, and why.
|
|
1016
|
+
- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — file-by-file contracts, what belongs where, and the known gotchas. Read before changing anything non-trivial, especially around persistence (`database.py` / `storage.py` / `core/memory.py` are three distinct and easily confused responsibilities).
|
|
1017
|
+
- **[ROADMAP.md](./docs/ROADMAP.md)**, **[ROADMAP_v2.md](./docs/ROADMAP_v2.md)** and **[ROADMAP_v3.md](./docs/ROADMAP_v3.md)** — implementation specs plus the locked Design Decisions Record that most of the reasoning above traces back to. Section numbers run on across the three: v3 opens at §49.
|
|
1018
|
+
- **[DEVLOG.md](./docs/DEVLOG.md)** — what was followed, what was deviated from, and why.
|
|
880
1019
|
|
|
881
1020
|
### Contributing and policies
|
|
882
1021
|
|
|
883
|
-
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — inbound license (Apache-2.0 + DCO), the setup and test loop, the issue and PR format, and a table of which document to update for what.
|
|
884
|
-
- **[SECURITY.md](./SECURITY.md)** — how to report a vulnerability privately, what is in and out of scope, and the coordinated-disclosure timeline. **Do not open a public issue for one.**
|
|
885
|
-
- **[PRIVACY.md](./PRIVACY.md)** — what is stored locally, what leaves your machine, and how to delete it. No telemetry.
|
|
886
|
-
- **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1, and the private channel for reporting a violation.
|
|
887
|
-
- **[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)** — the dependency license assessment: every declared direct dependency, its license, and its Apache-2.0 compatibility.
|
|
1022
|
+
- **[CONTRIBUTING.md](./docs/CONTRIBUTING.md)** — inbound license (Apache-2.0 + DCO), the setup and test loop, the issue and PR format, and a table of which document to update for what.
|
|
1023
|
+
- **[SECURITY.md](./docs/SECURITY.md)** — how to report a vulnerability privately, what is in and out of scope, and the coordinated-disclosure timeline. **Do not open a public issue for one.**
|
|
1024
|
+
- **[PRIVACY.md](./docs/PRIVACY.md)** — what is stored locally, what leaves your machine, and how to delete it. No telemetry.
|
|
1025
|
+
- **[CODE_OF_CONDUCT.md](./docs/CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1, and the private channel for reporting a violation.
|
|
1026
|
+
- **[THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md)** — the dependency license assessment: every declared direct dependency, its license, and its Apache-2.0 compatibility.
|
|
888
1027
|
|
|
889
1028
|
## License
|
|
890
1029
|
|
|
891
1030
|
Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE). Copyright 2026 Yahya Hammad.
|
|
892
1031
|
|
|
893
1032
|
No third-party source code is bundled here; dependencies are resolved from PyPI at install time
|
|
894
|
-
under their own licenses. [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) records the
|
|
1033
|
+
under their own licenses. [THIRD_PARTY_NOTICES.md](./docs/THIRD_PARTY_NOTICES.md) records the
|
|
895
1034
|
assessment of each one, and of the third-party text the repository reproduces.
|