## Summary
Adds `everos-cloud-memory`, a separately distributed memory plugin for
EverOS Cloud, and wires the host so a second memory plugin is a
first-class choice.
The plugin (`plugins-dist/everos-cloud-memory`) is a thin REST client
over httpx: one API key (the config slice
`plugins.config.everos-cloud-memory.api_key`, or
`EVEROS_CLOUD_API_KEY`), owner ids from the host's `ServiceLocator`
(never from the slice), every add in `agent` mode, and a flush only when
a caller marks the conversation over (`metadata.flush` /
`metadata.is_final`: the sub-agent handoff and the importer's final
batch) and once at stop. It ships its own onboard screen (env or on-file
key used without a prompt; 401 / 403 / unreachable get their own
sentences with Re-enter or Skip), `delete` answers False (the cloud
deletes by scope, nothing calls it), and `health()` classifies seven
answers for `raven doctor` and the settings card.
Host changes, each guarded so `memory.backend` `everos` and `null`
behave exactly as before:
- `raven onboard` step 4 asks "Which memory backend?" when more than one
plugin contributes a screen (preselects the current backend, `Off`
clears it, cancel exits 1 and writes nothing); with one plugin the step
is byte-identical to today.
- The memory page reads whichever backend `memory.backend` names: the
cloud slice's key goes out as a Bearer header and the `/health` probe is
skipped for the cloud; a missing distribution is named in the page's
note.
- `settings.everos` reports `reason: "other_backend"` for any non-EverOS
backend, so the Model page hides the three EverOS-only roles (embedding
stays: knowledge bases use that pin); `settings.everosSet` refuses those
three sections for another backend; `settings.set` admits
`plugins.config.<id>.<field>` against the plugin's manifest through the
same admission door channels use; new `settings.everosCloud` feeds the
card (key source, endpoint, health).
- Provider-key and main-model saves no longer restart the local EverOS
when another backend is active.
- ui-web: an EverOS Cloud card (status chip, key row, endpoint) and the
`settings.everosCloud` data behind it. No page mounts the card: it drew
on Model settings until the owner ruled that a memory backend's endpoint
and credential answer neither question that page asks, and where it
belongs is the Memory section's to say once that section has a design.
Until then the key is entered through `raven onboard` or
`EVEROS_CLOUD_API_KEY`. The fixture gate pins the four optional fields
the offline library never sends.
- Gates: the plugin boundary test scans both memory plugins, coverage
and the release workflow build the second wheel, deptry's ignore list
names the plugin beside `raven_everos`, and a conftest fixture keeps the
second plugin out of entry-point discovery for the existing onboarding
tests (they describe a one-plugin install).
A second topic rides along, because it is what makes the hosted backend
reachable from an agent product at all. Every product under `agents/`
pinned its memory at the stock EverOS address and only `raven-design`
read the host's, so the other four addressed whatever answered on 18791
-- the wizard moves a managed server when the port is taken, and a
server the user runs themselves is wherever they put it.
`inherit_memory_backend` in `raven/config/product_render.py` now carries
`memory.backend`, the endpoint, and (only when the product holds none
itself) the credential from the host into every render, beside the host
denials and plugin opt-outs that already travel there; `raven-design`'s
private copy is deleted and the five product configs stop naming an
address. Identity never travels, which is what keeps five products apart
inside one store. `memory.backend: null` travels like any other value,
because that null is how an operator turns long-term memory off and a
product that kept writing would be the one surface ignoring them; the
product's own default stands only when the host carries no key at all.
Which store memories live in is not a product's choice either: the host
reads a sub-agent's memories back through its own backend, so a product
writing anywhere else left that record empty with nothing reporting it.
`owned` is forced off whenever the local backend is in force, because a
product infers ownership from a slice naming no root -- the shape all
five ship -- and so answered a host that was merely not serving by
starting a second server against a root of its own, stranding every
memory written so far.
Decisions worth a reviewer's eye: the fake cloud
(`tests/_everos_cloud_fake.py`) honours or refuses every field the
backend can send and serves both an in-process transport and an HTTP
face for the real-host acceptance; the live tests
(`tests/integration/test_everos_cloud_real_cloud.py`) skip without
`EVEROS_CLOUD_API_KEY`; run with a real key on 2026-10-09 all six pass
against api.evermind.ai (round trip, get by session, empty flush, 401
wording, probe with and without a key, and extraction without a flush
within two minutes), so the documentation and the service agree on
everything the plugin sends. Design, acceptance cases and plan are under
`docs/specs/2026-10-08-everos-cloud-memory-*.md` and `docs/plans/`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Rebased onto main `182dacac0` on 2026-10-13. What that rebase and the
four commits on top were verified with:
- Full suite, `uv run --frozen --python 3.12 --extra dev pytest -q` ->
**29748 passed, 8 failed** in 4m10s. All eight fail identically with
these four commits' sources reverted in-tree at the same base, so none
of them is this branch's: the two `test_the_products_tool_face_*` cases
in the code and oncall launchers (an extra `web_search` in the visible
tool set), `test_agent_loop_token_budget`,
`test_rpc_files::test_a_host_without_libreoffice_says_so`,
`test_ppt_engine_image_search`, `test_shell_background`, and the two
`test_simulation_*` cases.
- Real-host before and after for the inheritance, driving the launcher
the host spawns (`agents/raven-research/run.py`) against an isolated
`RAVEN_HOME` whose EverOS address is `19701`, not the stock port.
Before: the product rendered `base_url: http://localhost:18791` with no
`owned` key, ignored the host, and started an EverOS of its own -- an
orphaned `everos server start --root <its own state root>/everos`
holding 18791, which is the stranding this change exists to stop. After:
it rendered `{"base_url": "http://localhost:19701", "owned": false}` and
said so itself, "the EverOS you manage is not running at
http://localhost:19701 ... Raven does not start or stop it", with `ps`
and `lsof` confirming nothing was started. On the cloud the product
rendered `memory.backend: everos-cloud` with the host's key and left the
out-of-force local slice untouched, and `raven doctor` over that
rendered config answered `everos-cloud: ok https://api.evermind.ai`, so
the credential reached the service. Identity stayed `raven-research-ng`
throughout, and a fingerprint of the operator's own EverOS root was
identical before and after.
- The first CI round on this head found one that the local gates did
not: `tests/test_import_cycle_budget.py`. `inherit_memory_backend` read
the backend-to-distribution pairing from `raven.core.plugin_stack`, and
that edge from `raven.config` into `raven.core` -- which imports
`raven.config` back -- took mutual pairs from 13 to 14 and packages
inside a cycle from 18 to 22. `make lint-imports` keeps ten contracts
and none of them covers that pair, so it was green throughout. The
pairing now lives in `raven/config/raven.py` beside the two fields it
joins (`MemoryConfig.backend` names a contribution,
`PluginsConfig.config` is keyed by the distribution), which `raven.core`
may import and which imports nothing back; `plugin_stack` re-exports the
two names its own callers read from it. An intermediate commit put it in
`raven.contracts` instead, which broke the cycle but took the papers
ceiling from 3700 to 3719 lines -- `tests/test_kernel_budget.py` says a
new paper is a reviewed change to that ceiling, so it moved again rather
than raising it.
- The review round on this head raised one non-blocking finding, fixed
rather than carried forward: the inheritance read `memory.backend` with
`.get()`, which collapses an explicit `null` into an absent key, so a
host with long-term memory off left every packaged agent on its own
shipped backend and still writing. Reproduced by calling the function
directly before the change and after, now read on presence, and pinned
by a case whose mutation (restoring the `.get()`) turns it and nothing
else red.
- One ordering problem found while checking the above, pre-existing and
not fixed here: `tests/test_rpc_settings.py` run before
`tests/test_cli_onboard_commands.py` leaves
`raven.home._current_config_path` pointing at a dead tmp config, so the
onboard cases write somewhere else. With main's own copies of both files
and main's conftest in the tree it is 57 failures; with this branch's,
19. Which cases turn red changes run to run as xdist distributes them
differently.
- `cd ui-web && npx vitest run` -> 876 files, 3728 passed, 0 failed;
`npm run lint` -> 0 errors (4 warnings, all in files this change does
not touch); `npm run gen:check` -> in sync (228 methods); `npm run
type-check` -> clean; `cd ui-tui && npm run lint:i18n && npm run
lint:rpc` -> in sync
- `make lint-python` / `lint-imports` (10 contracts kept) / `lint-types`
/ `lint-deps` -> all pass; `uv lock --check` -> exit 0 with both sides'
new packages present; `scripts/check_source_language.py` and
`scripts/check_large_files.py` on `github/main..HEAD` -> exit 0;
commitlint over every commit -> ok
- Semantic-conflict audit of the rebase, beyond what the suite answers:
21 of the branch's 66 files are also in main's 499, and every one of
main's changes in them is additive and elsewhere in the file. The one
that could have broken silently is main's new `vision.model` /
`vision.provider` simple keys meeting this branch's new
`plugins.config.<id>.<field>` branch in `settings_set`; nothing in the
suite exercises `vision.*` through that method, so it was run directly
-> `{'applied': True}` and `{"model": "..."}` on disk. The subtraction
decisions were re-checked against the new base: no new caller of a
memory backend's `delete`, main's new onboard cases are about TLS and
not the memory step, `inherit_everos_address` exists nowhere, and
`DEFAULT_EVEROS_BASE_URL` is still defined.
- Mutation runs on the new code, restored afterwards: dropping `owned:
false`, letting the host's credential overwrite the product's own, not
writing the host's backend name, and carrying every memory slice instead
of the one in force each turn their own cases red; making the cloud card
render nothing turns 4 of its 5 new cases red and leaves the fifth
("draws nothing when not selected") green.
From the earlier round, on base `6d509a8c5`:
- `uv run --frozen --python 3.12 --extra dev pytest -p no:cacheprovider
-q tests/test_everos_cloud_fake.py tests/test_everos_cloud_backend.py
tests/test_everos_cloud_backend_contract.py
tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py
tests/test_cli_onboard_commands.py tests/test_rpc_memory.py
tests/test_rpc_settings.py tests/test_plugin_boundary.py
tests/test_rpc_schema_match.py tests/test_rpc_registration.py
tests/test_release_plugin_list.py
tests/integration/test_everos_cloud_real_cloud.py` -> 1001 passed, 6
skipped (the six live tests, no key)
- `cd ui-web && npx vitest run` -> 214 files, 3211 passed; `npm run
lint` -> 0 errors (4 warnings, all in files this change does not touch);
`npm run gen:check` -> in sync (207 methods); `cd ui-tui && npm run
lint:rpc && npm run lint:i18n` -> in sync
- `make lint` (ruff, ruff format, ui tsc, deptry) -> ok; `make
lint-types` -> All checks passed; `make build-ui` -> boot snapshots
match; `scripts/check_large_files.py` and
`scripts/check_source_language.py` on `6d509a8c5..HEAD` -> exit 0;
commitlint and `scripts/check_commit_messages.py` on each commit -> ok
- Mutation runs per change (restored afterwards, `git diff` clean): a
host import of the plugin turns the boundary test red; `import
raven_everos` in the plugin turns the import-isolation test red;
removing the chooser's cancel exit, the Bearer header, the restart
guard, the slice-admission guard, the Roles filter and the fake's two
fixes each turn their own test red
- Real-host acceptance (64 cases,
`docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`) run against a
fake EverOS Cloud: the wizard in tmux (chooser, key typed / from env /
on file, 401 / 403 / unreachable wording, back, Off, Ctrl-C,
non-interactive, base-tree transcript byte-identical with one plugin),
`raven agent` turns (user and agent-track recall, agent-mode adds, 4 s
recall bound, a 300 KB message dropped with a warning, a sub-agent trace
stored under its own ids, flushed and read back, one exit flush per
unflushed session), `raven import run` (3 adds then one flush; a hung
flush retried 4x and the exit sweep defeated), `raven doctor` under
seven cloud conditions (seven sentences, exit 2 only for the five
faults) and with the distribution hidden, and the web page through
playwright-cli (memory page counts and the fake's episode, empty and
refused stores, the Model page hiding the three EverOS-only roles while
the embedding row stays, the cloud card rotating a key and showing the
401 wording, three refused settings.set frames over the gateway
WebSocket, the local everos / null / mem0 backends drawing the page as
before, and a provider-key save that restarts the local EverOS on the
base tree and does not on this branch). Evidence and the per-case
verdicts are kept outside the repo. The live service was reached with a
real key after the acceptance run: six tests, six passes, the service's
replies archived with the evidence.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible changes: the wizard's step 4 chooser (only when two memory
plugins are installed); Model settings hides the three EverOS-only role
rows when `memory.backend` is not `everos`/`null` and draws no cloud
card; the memory page sends a Bearer header for the cloud backend.
Two behaviour changes for agent products, both on the `agents/` lane
only. An agent product now follows the host's `memory.backend` and
endpoint instead of its own, which is a fix for the four products that
never followed the host and a change for `raven-design`, which followed
the endpoint but not the backend. And a product no longer starts an
EverOS server of its own: where it used to answer a host that was not
serving by starting one against an empty root of its own, it now reports
long-term memory as unavailable, which is what the host does. Rollback
for this part is the one commit; the product configs it edits are
shipped files, not user config. The plugin is not installed by default
(its wheel is built by the release workflow; nothing changes for an
install without it). Rollback: revert the squash commit; the config
schema gains no new key (the slice is a plugin slice), so an older raven
reads a config written by this one.
Credentials: the cloud key is written only by `set_plugin_config_fields`
into the plugin's slice; the settings page's key row goes through
`settings.set` with a manifest-declared field, and
`settings.everosCloud` reports `api_key_set` / `key_source`, never the
value.
## Related Issues
N/A
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The unit job takes twelve minutes on one runner. The first cut of this
PR took the production waits out of the tests, which made the suite a
quarter faster on a laptop and moved CI by 14 s (pytest 720.95 s on
main, 706.57 s here): the runner is three to four times slower than a
laptop on CPU-bound tests, and two of the twelve minutes are the four
xdist workers importing every test module. So the PR now attacks the
wall clock from every side that CI's own numbers pointed at.
- `ci(*)`: the unit job runs as four shards. pytest gains `--shard K/N`
in `tests/conftest.py`, decided in `pytest_ignore_collect` so a shard
never imports the other shards' files; test files are dealt round-robin
over their sorted list so the slow families that sort together (the ppt
engine's) are spread out. Each shard writes coverage data and no report;
a `coverage` job downloads the four data files, combines them, writes
`coverage.json` and `coverage.xml`, and runs the gates that used to
follow the tests.
- `perf(ppt-engine)`: `menu()` caches its reading of a template, capped
at eight entries. One bind reads the bound template and then every other
bundled template for the borrow offer; with ten templates bundled, every
bind evicted what the next one needed and re-measured all of them with
freetype. The cap is 32 and a hit moves its entry to the back. On this
PR's first CI run the template-tool file alone was 257 s of the
over-ceiling list, its tests 10 to 26 s each.
- `test(*)`: an autouse fixture collapses the provider chat retry
ladder, the loop's LLM-error ladder and the memory store backoff to a
millisecond per step, and the steer hook grace to one poll. It keeps
each tuple's length because both ladders count attempts with `len()`;
the steps are a millisecond rather than zero because the store pipeline
waits with `wait_for(stopping.wait(), timeout=delay)`, and a zero
timeout cancels that wait before it runs. A test that proves a timing
property opts out with the new `production_timing` marker. Ten tests
spent 257 s of the suite's worker time in those waits; none asserted on
the time.
- `test(*)`: a wall-clock ceiling. Setup plus call over 2 s on a test
marked neither `slow` nor `production_timing` is listed at the end of
the run; `--wall-clock-ceiling-strict` fails an otherwise green session
on it. Warning only here; CI flips to strict once the remaining tail is
marked.
- `test(*)`: every test created two numbered temp directories, and
pytest picks each number by scanning the base temp dir; the fake home is
now a sibling of `tmp_path`. `MPLCONFIGDIR` points at a git-ignored dir
in the checkout, because the fake home changed per test and matplotlib
rebuilt its font list from the system fonts on every run.
- `refactor(agent)`: the outer LLM-error retry ladder default `(15, 30,
60)` lived in three places; it is one constant in
`raven/config/schema.py` now, read by both `RecoveryLimits` and
`_ladder`. Behaviour unchanged.
- `test(updates)`: the first sharded run turned up an order dependency.
`beta_channel` binds `ReleaseInfo` from `raven.updates.upgrade` at
import, the update-notice tests stand a fake in for that module through
`sys.modules`, and `_refresh` imports `beta_channel` lazily; a worker
that imported `beta_channel` for the first time inside that test got an
`ImportError` swallowed as a failed refresh. The test module now imports
`beta_channel` at the top.
- `ci(*)`: the PR diff gate named every `.py` under `plugins-dist` as
production code while coverage measures only `raven` and `raven_everos`,
so a change to the ppt or design engine could never appear in the report
and the gate refused every such PR on sight; the first sharded run hit
it on `menu.py`. The pathspec now names `plugins-dist/everos-memory`,
and a test holds every production pathspec to a package some `--cov`
flag in the Makefile measures.
- Two slow tests were not waits: the sandbox second-cancel test
cancelled one tick too early (two pending cancels coalesce into one
`CancelledError`) and now waits, under a one second timeout, for the
kill to land; the two thousand-session dispatch tests wrote a span per
refused enqueue through a store that opens its file per span, so tracing
is off for them. Follow-up on the product side: `raven/tracing/store.py`
should reuse its handle.
The suite has 30 upper-bound assertions of the form `assert elapsed <
X`; shortened delays can only make those looser.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [x] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Whole suite, `uv run --frozen --all-extras pytest -q` (macOS, 4
workers), 22051 passed / 43 skipped each time:
| tree | wall clock | unmarked tests over 2 s |
|---|---|---|
| main before this branch | 372.82 s | (no ceiling yet) |
| after the waits were taken out | 279.65 s | 63 |
| this branch | 224.25 s | 39 |
The shards partition the suite exactly (`uv run --frozen --all-extras
pytest --collect-only -q -n 0 --shard K/4`, K = 1..4):
| whole | shard 1 | shard 2 | shard 3 | shard 4 | union | ids in two
shards |
|---|---|---|---|---|---|---|
| 22095 | 5058 | 5555 | 5955 | 5527 | 22095 | 0 |
196 / 195 / 194 / 194 test files per shard. A shard collects in 7 s
where the whole suite takes 23 s on the same machine. `--ignore` still
works under `--shard`: with four `--ignore` flags on shard 1, the
ignored file that shard owns is gone from its collection (5034 ids
against 5058).
Combining loses nothing. Two small runs with `--cov=raven
--cov=raven_everos --cov-branch --cov-report=` and `COVERAGE_FILE` set,
then `make coverage-combine COVERAGE_DATA_DIR=<dir>`, against one `make
coverage` of the whole suite on main:
| report | files | statements | branches |
|---|---|---|---|
| one run of the whole suite | 704 | 82634 | 25548 |
| two shards combined | 704 | 82636 | 25548 |
Same file set; the two extra statements are the new constant and its
import. A source package's never-imported files reach the combined
report through the shard that imported it, as they reached the single
run.
The menu cache, the three files that bind templates (`uv run --frozen
--all-extras pytest -q tests/test_ppt_engine_template_tool.py
tests/test_ppt_engine_outline_checks.py
tests/test_ppt_engine_default_templates.py`): 101 s of worker time in
the last profile, now `196 passed in 11.84s` with no test over 2.9 s.
The files that call `menu()` directly: `219 passed in 8.06s`.
The font cache, the formula render test at `-n 0`: 8.91 s cold, 0.69 s
on the next run. Seven home-sensitive files: `484 passed in 5.30s`.
Ceiling guard, both modes, with the ceiling forced low so it has
something to list:
```
uv run --frozen --all-extras pytest -q -n 0 --wall-clock-ceiling=0.01 tests/test_import_cycle_budget.py tests/test_updates_install_guard.py
uv run --frozen --all-extras pytest -q -n 2 --wall-clock-ceiling=0.01 --wall-clock-ceiling-strict tests/test_updates_install_guard.py
```
First: 28 passed, five listed, exit 0. Second: 24 passed, four listed,
exit 1 (the controller flips the status; workers do not).
`make lint-python` clean, `make lint-imports` passes. The CI run on this
PR is the measurement that matters: four `unit` shards and one `coverage
gates` job.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none: CI
plumbing, a cache cap, test setup)
## Risk
- The coverage gates now run in a job after the four shards. A red shard
skips the gates, a deliberate trade: combining three of four data files
would report a coverage drop that is not one, and the PR is red either
way. The gate scripts and their thresholds are unchanged.
- The diff gate no longer sees `plugins-dist/ppt-engine` or
`plugins-dist/design-engine` at all, as it could never judge them;
measuring them (`--cov=raven_ppt --cov=raven_design`, a new ratchet
baseline) is the follow-up that would bring them under the gate.
- `--shard` is opt-in; a plain `pytest` run collects everything as
before. Shard data artifacts are kept one day, the combined reports 30
days as before.
- No product behaviour change: the ladder default is the same tuple read
from one place; the menu cap only changes how long the cache keeps
entries.
- Test-only risk: a test that implicitly relied on a production-length
retry delay would see different timing. The full suite passed with the
fixture on, and a single test can opt out with `production_timing`.
- Rollback: revert the PR. The unit job goes back to one runner with the
gates inline; both markers are additive.
- [x] Security impact considered (no security surface touched)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
The onboard wizard stored the web_search vendor's key without checking it, so a mistyped or revoked key surfaced as the tool's first failure inside a conversation. Step 5 now spends one real query on the key right after the prompt and before anything is written.
- `WebSearchTool.probe()` runs the same provider request `execute()` uses, asking for one result, and returns `(ok, detail)`. The detail carries vendor and HTTP status only. Exception text is never echoed: SerpApi puts the key in the request URL, and an unusable proxy URL can carry its own credentials, so that branch reports the exception class alone.
- Interactive step 5 loops the key prompt through the probe. On failure the user picks re-enter, retry, or continue anyway. A stored key kept with Enter is probed too, since it may have been revoked. An empty slot is not probed, since leaving web_search off is a choice, not a failure.
- The flag path (`--search-api-key`, `--serper-api-key`) writes first and then probes, warning on failure without dropping the write, because a scripted run has nobody to re-enter the key. Only the active search vendor's key is probed there.
- The page reader is not probed. Jina works with no key, and a keyed reader whose key does not resolve is replaced by Jina at registration. A keyed reader with a wrong key still fails at call time; that is unchanged and out of scope here.
- All wizard strings reuse existing zh catalog entries; README step 5 and the `--search-api-key` help mention the check.
Deliberately not done, for the reviewer: the web settings page writes the same key slot and does not probe; a key supplied only through the vendor's env var is not probed; step 5 does not feed the wizard's end-of-run warnings list. A vendor that answers 200 with zero results passes, since only HTTP status and a Firecrawl refusal count as failure.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
uv run pytest tests/test_agent_tools_web_providers.py tests/test_cli_onboard_commands.py \
tests/test_i18n_boundary.py tests/test_agent_loop_web_tools.py 410 passed
make lint-python clean
make check-source-language exit 0
uv run python scripts/check_commit_messages.py origin/main..HEAD exit 0
```
Revert-the-fix check: with the onboard change reverted, the five new step 5 tests error out on the missing probe seam. No test reaches the network: an autouse fixture in the onboard tests replaces the probe, and the provider tests patch the HTTP client. `make lint-tui` fails on a stale generated i18n file that is identical on `main`; `make lint-bridge` needs `tsc`, which this box lacks.
Not verified: a live run against a real vendor key.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
User-visible change: onboarding spends one search query per key check against the chosen vendor, and a rejected key adds one prompt. The key still goes only to its own vendor's endpoint, through the configured `tools.web.proxy`. Nothing in config changes shape. Rollback is reverting the commit; no data migration.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
`raven.permissions` imported `raven.agent.tools.shell_policy` for
`CommandDecision` and `ShellCommandPolicy`, while the agent side imports
`raven.permissions` from the loop, the turn path and the `raven_loop` backend.
Four edges down, one edge back up, and a cycle between two top-level packages.
The one edge back was the misplaced one. `shell_policy` answers whether a
command may run and whether it needs approval -- which is what the permissions
package is for. It sat under `agent/tools` because that is where the shell tool
that consumes it lives, not because the policy belongs to the tool.
Moving it is unusually cheap: its 1262 lines import `re`, `shlex`,
`contextvars`, `dataclasses`, `enum` and `pathlib` and nothing from raven, so
the module arrives in `permissions` carrying no dependency of its own. Nothing
new enters that package's dependency set.
Its three consumers are repointed rather than reading through a shim at the old
path: the shell tool, the ACP server's approval-family wiring, and the
permissions rules that started this. `agent -> permissions` and
`acp -> permissions` are both directions that already existed.
This is the third instance of one shape in this tree: a capability with no
dependencies of its own, seated inside one of its consumers, which a lower layer
then has to reach up for. The vocabulary split in MR 610 was the second.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
```
$ uv run --frozen --python 3.12 lint-imports
Contracts: 9 kept, 0 broken.
$ uv run --frozen --python 3.12 pytest tests/test_shell_approval.py \
tests/test_shell_comments.py tests/test_shell_policy_reasons.py \
tests/test_permissions_gate.py tests/test_acp_server.py \
tests/test_agents_ppt_launcher.py -q
407 passed in 4.65s
$ uv run --frozen --python 3.12 pytest tests/ -q -k "shell or permission or policy"
746 passed, 8 skipped, 20 warnings in 23.73s
$ uv run --frozen --python 3.12 --extra dev ruff check raven/permissions/ \
raven/acp/server.py raven/agent/tools/shell.py
All checks passed!
$ make check-commits COMMIT_RANGE=origin/main..HEAD
exit 0
```
The eight skips in the wider sweep are pre-existing and environmental: optional
extras that are not installed in this checkout (`wecom_aibot_sdk`, the render
extra). None of them exercise shell policy.
Every consumer of the module was enumerated before the move -- three in `raven/`
and six test files -- and all nine are repointed in this commit, so no import of
the old path remains anywhere in the tree.
Effect on the dependency graph:
```
permissions -> agent edges 1 -> 0
mutually importing pairs 14 -> 13
packages in an import cycle 22 -> 22 (unchanged)
```
The package count does not move. Unlike the config vocabulary split, this pair
was not the only thing holding any other package in the component -- worth
recording, because it is the case where a mutual pair disappears and the
component does not shrink.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No user-facing surface changes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This module decides whether a shell command runs, so the security-relevant
question is whether the decision changed: it did not. The file moves unedited --
git records it as a rename -- and the matchers, the approval families and the
policy class are byte-identical. `tests/test_shell_approval.py`,
`tests/test_shell_comments.py` and `tests/test_permissions_gate.py` cover the
deny and approval paths and pass unchanged apart from the import line.
No public surface is affected: `shell_policy` is internal to raven and its old
path had no consumers outside this repository. Rollback is reverting the one
commit, which git will apply as the reverse rename.
## Related Issues
N/A
## Summary
Three reader-facing changes to the TUI transcript and the instance strip.
**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.
The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.
Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.
**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.
**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.
`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on a worktree at this branch's tip, against the current main tip:
- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0
No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Three user-visible changes, all inside the terminal UI:
- a tool call that returned something now opens to a capped preview instead of
staying shut. A reader who prefers it shut clicks once, and that decision
holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
has one column less for its name.
- the status ticker shows a different set of glyphs and words.
No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Three reader-facing changes to the TUI transcript and the instance strip.
**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.
The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.
Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.
**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.
**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.
`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on a worktree at this branch's tip, against the current main tip:
- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0
No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Three user-visible changes, all inside the terminal UI:
- a tool call that returned something now opens to a capped preview instead of
staying shut. A reader who prefers it shut clicks once, and that decision
holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
has one column less for its name.
- the status ticker shows a different set of glyphs and words.
No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## What
Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.
## Why
On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:
- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
from three classes outside the falsified list" (the falsified list named 18 specific
hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".
The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.
## The three rules
1. The owner's words and scope go into every node's brief as written; the orchestrator's
own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
*not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.
## Checks
- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
`tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
adds later in the same file.
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.
It comes back as a section of the card, not a third verb on the row:
- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.
No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.
**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:
- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.
This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.
**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)
**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.
**Checked and deliberately not changed, for the reviewer:**
- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:
- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.
```
npm run test --prefix ui-web 101 files, 1550 passed
npm run test --prefix ui-tui 141 files, 2017 passed, 13 skipped
npm run gen:check --prefix ui-web generated client matches the contract (162 methods)
npm run type-check --prefix ui-web clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui 23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py pass over the branch
make build-ui dist rebuilt and served
```
The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)
## Risk
User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.
- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.
Key decisions:
- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
`use_skill` and the segment builder's post-gate hydrate refuse exactly what
they refused before. Reading is the weaker case because it installs nothing
and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
products rather than being one, so reporting the root refused a skill for
mentioning XDG at all. The reported path now runs down to the segment naming
the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.
`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.
- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
3 skipped. The three skips are pre-existing and environment-bound (two
`chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
note `these instructions reference paths outside Raven (~/.config/mcporter,
~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.
The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.
The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.
Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.
**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.
**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.
**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.
**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.
The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.
Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Branch and base run in separate worktrees, both at the same base, same interpreter.
- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
`unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
need `--localstorage-file` for `localStorage` to exist on this box at all, and with
it the store no longer refuses, so the refusal each asserts does not happen. Both
reproduce on the base, and neither file imports anything this change touches. A
second environment settles it: review ran the same head and reported 1,536 tests
passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
`check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
`lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
`renamed` call, a missing export, a missing harness verb, and the pre-edit title.
The ordering one is driven through the real `rpc.onReconnect` rather than
`openLiveSession`, because the ordering is between the two and a test that calls the
inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
editor gone, button back, zero title calls, no page error. Reconnect with the editor
open, forced by closing the socket from the page: before, `Cannot read properties of
null (reading 'textContent')` with the input stranded and no session reload; after,
heading restored, editor gone, reload done, no page error. Reconnect with a name
typed into an open editor: heading and rail row both settle on the committed name,
no page error. That probe renamed a real conversation, so its title was put back and
the stored metadata checked byte-identical afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
User-visible, all of it in the same direction: a title that used to vanish stays put.
- Ending an editor on a conversation switch commits what was typed, which is what
leaving the field already did. It cannot reach a different conversation than the one
it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
only case that changes is a name being generated, where the heading is empty and the
row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
shape or a schema.
Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
The turn path's four strategy decisions become named seams the loop delegates
to, with no behaviour moving. Memory owns the turn's window, Planning passes
the turn's messages through, Capability reports what the tool registry offers,
and Action dispatches the one streaming-or-retrying model call the loop made
inline. The shell keeps everything that made the loop worth trusting:
iteration accounting, hook phases, tool execution and approval, the three
in-turn recoveries, persistence and event order.
This is the minimal step on purpose. The seam is what the change buys: those
four points can now be replaced without touching the loop's machinery. Widening
Action to own extract-and-verify (the three in-turn recoveries, a billing-wrapped
call service, a repair budget) is deliberately left for a follow-up, because
"reproduces the previous revision exactly" is provable for a single call and
much harder once several hundred lines move with it.
Key decisions:
- Memory is more than an adapter over the context engine. Two decisions that
sat in the shell move onto the role that owns them: which history slice is
even a candidate (it turns on whether the engine archives for itself), and
how much of the window a prompt may occupy (that window's own arithmetic).
organ_glue keeps both method names and forwards.
- Every input reaches a role through a callable, never a captured instance.
A live model switch rebuilds the provider and the window, and trajectory
replay rebinds loop.tools after the constructor returns. The context engine
is the exception and is bound directly: nothing rebinds it, and a
generation's window is its engine.
- contracts/harness.py is factory-loop tier beside loop_hooks, not the frozen
contract tier: a replacement loop may name its own strategy points, so these
four are this loop's rather than a cross-loop promise.
- Planning's seat is after the origin stamp, so a planner returning a different
list cannot move which message gets marked.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Behaviour preservation was measured, not asserted. A full turn runs through a
real AgentLoop on a scripted provider (context assembly, a tool call, its
observation, the answer) and every provider request is recorded: model, sorted
tool names, message roles and contents, plus the final answer.
- Captured on this branch and twice on its parent commit. Raw diffs contain
only wrap_untrusted fence nonces, which are random per invocation; capturing
the parent twice shows those are the sole variance. After normalising them
all three files share one MD5.
- `uv run pytest tests/` on the branch and the same failures on the parent
commit, so nothing here introduces one.
- `uv run pytest tests/test_harness_modules.py` -- 23 new cases covering the
default set, the two decisions Memory took over, both Action paths, the
callable indirection, and the frozen module set.
- `uv run ruff check raven/ tests/` and `ruff format --check` clean.
- `uv run lint-imports` -- 9 contracts kept, with raven.agent.harness added to
the one that keeps cargo out of the loop shell.
- `make check-source-language` clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No user-visible behaviour changes, which is the claim the capture comparison
above is there to support. The rollback path is the revert: the seam is
additive, the four defaults reproduce the inline code, and no caller outside
the loop reaches the new package.
The contracts line ceiling moves 2520 to 2730 for the new paper, reviewed in
test_kernel_budget's own docstring the way the previous move was. Without this
paper the package stands at 2515, five lines under the number it has been
passing on, so the ceiling is not absorbing unrelated growth.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.
Key decisions:
- **Templates are real code, fire-tested before templating.** The eleven
files under raven/templates/agents_scaffold/ pass ruff and py_compile
like any source, ride the wheel, and their content was proven live
before landing: discovery, handshake, and plugin tool/hook injection
all green on a hand-assembled probe in a disposable home. A dedicated
spike also proved the placement is invisible to the import-linter
contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
target is the raven home's agents/ tree, discovery's first root: a
scaffolded folder is on the roster without any registration.
--register mirrors the generated install.py through the same pinned
write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
manifest, re-parses the plugin manifest, compiles every generated
file, and really scans discovery; smoke spawns the launcher for one
initialize frame. Three smoke outcomes are told apart: GREEN, the
launcher's loud no-key refusal (fail-closed design, passed through
verbatim), and FAILED with the scene preserved. Display names are
fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
renders schemas/subagent.schema.json (a discriminated union on kind)
and schemas/raven-plugin.schema.json from the pydantic models; a
contract family holds the on-disk files byte-equal to a fresh render
and validates every real manifest on the tree against them. Editors
get instant validation with two settings lines, documented in the
guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
the from-zero developer guide (gold standard: a developer who never
read the source reaches a green handshake in ten minutes); CONTEXT.md
renames the category entry to Discovered agent -- agent the thing,
harness the mechanism, subagent the protocol seat -- with product
absorbed into Avoid; the charter gains the scaffold entry and the
engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
project in the working directory (pip install -e territory); --here
lands it on the plugins-dist shelf. The launcher adopts the official
ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
is missing; the doctor reports that row as disabled by design with
the install cure printed. No plugins/ directory ships beside an
engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
hostile lenses (filesystem edges of a command that writes into real
raven homes; template quality as the file set every future agent
copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
pin an enabled row that cannot start, the name fence ignored the
discovered tree, one installed engine wheel rode the host's and every
sibling's turns through a fixed tool name, and crash residue was
discovered as a hidden live agent. All fourteen close in a
dedicated hardening commit, each with a regression test built from the review's own
reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
Nothing under raven/contracts/ or the agent loop changed. The branch
carries exactly two narrow runtime fixes exposed by the review:
discovery now skips dot-directories (crash residue is never an
agent), and the config schema gains an engine round-trip field
(declared as a field-level neutral seam; merge and readiness
semantics untouched).
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- Every commit landed through a full-suite rehearsal on a clean bench
before touching the branch; tails over the original base's 19953
passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
every step a pure addition, +65 tests net. The branch diff is
fingerprint-stable across the rebase (git patch-id --stable verified
pairwise across two clean rebases); the branch closes at 20094 passed
/ 137 skipped / exit 0 on the current main base, +80 tests net over
whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
end: one command scaffolds into ~/.raven/agents, the four-segment
card runs all green, and a genuine LLM turn has the agent's own model
call its own scaffolded hello tool through the permission gate and
relay the exact output; the probe was then removed without touching
the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
four doctor lines, readiness ready, and a live ACP initialize
handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
tampered file each turn the family red); all six subagent manifests
and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
make check-large-files, make check-source-language: green at every
step; wheel build carries all seventeen template files and none of
schemas/.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.
## Related Issues
N/A
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
One wave back the backend left the wheel; the registry path degraded
loudly and everything else did not. Seven host surfaces imported the
plugin package directly -- 25 function-level imports, none guarded -- so
an install without the distribution turned raven doctor, onboard,
import, the memory RPC methods and the sub-agent trace writer into
tracebacks instead of the loud degrade the ruling requires. And no
install path carried the distribution at all: install.sh built only the
root project and the release published only its wheel, so a released
raven upgraded straight into the degraded state its own default config
names.
The host now asks one question, everos_plugin_installed -- a spec lookup
that executes no plugin code, so an installed-but-broken plugin stays a
visible bug instead of reading as an absence -- and each surface answers
in its own register: doctor reports plugin_missing as the fault it is,
onboard names what to install, the RPC returns its own error shape, the
trace writer logs once. install.sh carries the distribution on both its
paths with a degrade ladder that never blocks the install, the release
builds and uploads the sibling wheel, and the diff-coverage gate's
pathspec follows the code it had lost sight of. The absence tests take
the package away for real (a sys.modules sentinel) rather than stubbing
the guard they exist to prove.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
raven.evolver was 13.6k lines with no importer in the runtime and its own
entry point: a tool that drives raven against a benchmark, not a part of what
raven ships. It becomes evolver/ beside raven/ in the checkout, still imports
raven as a library (config, providers, skill_forge catalog, atomic_io), and is
no longer in the wheel. The runtime may not import it back: a fifth
import-linter contract says so (the package is external to the linter's root,
so external packages are now included in the graph) and a test says the same
to pytest. Its tests, the appworld bench adapters, the specs and the README
follow the new address; the Makefile lints it with the rest.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
- agent/subagent/dag_projection.py had no importer since the subagent_dag
package was folded away, and its docstring guarded against a host that is
not in this repository. Deleted.
- utils/win_fcntl_shim.py was installed by nobody since memory moved to the
out-of-process everos service; its docstring described a failure the
architecture cannot produce. Deleted, with its three coverage-omit entries
and the tests README paragraph.
- cli/_exit.py had one caller, the pytest session hook. flush_and_hard_exit
now lives in tests/_hard_exit.py next to that caller (the test that pins it
follows it as tests/test_hard_exit.py), and the CLI entrance carries no
test infrastructure.
Audit refs RES-02, RES-03, RES-05.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Three more commits landed on the trunk during the review round, so the branch
stopped fast-forwarding again. Merged rather than rebased for the same reason as
before: a rebase flattens the v0.1.12 merge commit and costs the ancestry this
whole branch exists to establish.
One conflict, additive: tests/test_cli_gateway_commands.py had a _risk_banner
group added on this branch and a gateway-shutdown ordering test added on the
trunk. Both kept.
ui-tui/src/rpc/generated.ts merged automatically. Since it is a generated file,
its result was checked rather than assumed: `npm run lint:rpc` reports it in sync
with rpc-schema/openrpc.json, which merged alongside it.
Verification:
uv run pytest 9018 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1022 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean
npm run lint:rpc schema and codegen in sync
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Installing one of the sub-agents that ship under `subagents/` required a running
raven: each folder's `install.py` registered its entry through
`PUT /raven/subagents`, so both the web service and the gateway had to be up. On a
machine that has just cloned the repository, neither is.
The installer now writes `subagents.thirdParty` in the host raven's config
directly, through `raven.config.update_subagents` - the supported write path,
which validates the entry against the schema, replaces the entry sharing its name,
refuses a list that would hold duplicates, and replaces the file atomically. Hand-editing the JSON gets none of that, and a
half-written config is one raven will not start on. That module is importable only
from the host raven's environment, which is rarely the interpreter running the
installer, so it is reached in a subprocess resolved from the shebang of `raven`
on `PATH` (or `RAVEN_PYTHON`, or `--raven-python`). The installer therefore stays
standard-library only and runs under a bare `python3`.
What the file write costs is hot-apply: a running raven holds the roster it read
at startup, so the installer prints a restart instruction and the guide says the
same. `--endpoint` is gone; `--config` and `--raven-python` are new.
Two additions on top:
- `subagents/install.sh` does the whole install for every folder, or the ones
named: builds each checkout's venv, scaffolds `.env` from its template, then
registers. It refuses to register a folder whose api key is still blank, so a
half-configured agent never reaches the roster, and exits non-zero while
anything still needs attention. It discovers the checkout by its lone
`pyproject.toml` and derives the key prefix from the folder name, so a new
folder needs no edit in the script.
- `subagents/README.md` is the directory-level guide: what a folder is made of,
the install steps, what the installer does and does not do, how to remove an
agent, what a new folder has to satisfy, and what never gets committed.
`subagents/*` stays excluded by default. Only the folders that were already
tracked are whitelisted, plus those two new files by name; a folder holding a
docker image tar or a private checkout is unaffected. The change also drops a
sentence that pointed a published README at an unpublished sibling folder.
The pre-install backup is written before the config is touched, holds the list as
it sits on disk rather than a schema round-trip of it (loading coerces an `openai`
entry's `readsLocalFiles` away, so a validated copy would restore something the
user never wrote), and is at mode 600 because another entry among the others can
carry its own api key. A backup that cannot be written stops the install with the
config untouched, rather than going missing after a config that already changed.
`install.sh` reads the api key the way the launcher does, first non-empty match
wins, so the two cannot disagree about a `.env` that sets it twice. It expands its
argument array through `${args[@]+...}`, since an empty array under `set -u` is an
unbound-variable error before bash 4.4 - the stock `/bin/bash` on macOS. A relative
`--config` is made absolute at parse time, because `install.py` runs with each
folder as its cwd and would otherwise resolve the path once per folder.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
The branch touches 12 files: `.gitignore` and 11 under `subagents/`. Nothing under
`raven/` or `tests/`, and `testpaths = ["tests"]`, so no unit test collects any of
it.
```
uv run pytest -q 8237 passed, 46 skipped, 13 deselected in 170s
uv run ruff check --no-force-exclude subagents/raven-code/install.py All checks passed
uv run ruff format --check --no-force-exclude subagents/raven-code/install.py 1 file already formatted
bash -n subagents/install.sh clean
python3 scripts/check_commit_messages.py origin/main..HEAD exit 0
python3 scripts/check_large_files.py origin/main..HEAD exit 0
```
`subagents/` is excluded in `[tool.ruff] extend-exclude`, so the two ruff commands
above need `--no-force-exclude` to reach the file at all.
End-to-end on a freshly provisioned host with no `raven`, no `uv`, and Python 3.10:
cloned the repository, installed `uv`, built the venvs, ran the installer twice and
spawned one agent for real.
- Installer on a clean clone with no keys: three checkout venvs built, three `.env`
files scaffolded at mode 600, stopped at the key gate for all three, exit 1. The
host config's mtime was unchanged and no backup file was written, so nothing
half-configured reached the roster.
- Same host with keys filled in: all three entries `replaced` in a config that
already held 8 third-party sub-agents, and all 8 survived. Each backup was mode
600 and held the full 8-entry list. `load_config()` then listed all 8, so the
written entry is valid to the runtime and not only to the writer.
- The resolved `command` of each entry pointed at the clone's own path, confirming
the placeholders resolve against the installer's location rather than the machine
that built the folder.
- One real spawn answered correctly in 22s.
- Before that, on a machine with no `raven` on `PATH`, the installer reported
`no raven on PATH; pass --raven-python ...` and recorded the folder as failed.
Probes for the fixed defects: a config seeded with `readsLocalFiles: true`
on disk produced a backup recording `false` before the fix and `true` after; a
`.env` setting the key twice with an empty second line made the shell installer
refuse an agent the launcher would run, and both now agree; an interpreter stub
printing non-JSON now yields `cannot read the writer's output` instead of a
traceback; a `--config` whose parent is a regular file makes the config write fail
with the backup already on disk, which is what shows the backup precedes it; and a
run with no flags at all registers against a scratch `HOME`, which is the path the
empty-array expansion used to break on bash before 4.4.
Proving the backup ordering took two attempts. Making the folder unwritable with
`chmod 555` proved nothing, because this runs as root and root ignores mode bits -
a trap the repository's own skipped test records. The failing-config probe above is
the one that holds.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
The first box is deliberately unchecked: there is no unit test covering this tree,
because pytest does not collect it. The end-to-end run above is the evidence
offered in its place. The unit suite was run anyway, on the rebased tree, and
reported no failures at all - so there are no failing ids to diff against the
target branch.
## Risk
**Behaviour change.** An install no longer takes effect immediately. Anyone
following the old flow will see the agent appear only after raven or the gateway
restarts; the installer's last line and the guide both say so. `--endpoint` no
longer exists, so a caller passing it gets an argparse error rather than a silent
fallback.
**Not reproduced, environment-dependent.** On the test host, the provider's model
listing answered 200 while inference answered
`403 This model is not available in your region.`, which the launcher reports as a
run that exits 0 having committed no answer - it reads like a launcher bug and is
not one. Exporting the site proxy fixed it, and the guide now records both that and
the fact that a missing EverOS degrades rather than fails.
**Security.** The pre-write backup can contain another entry's api key, so it is
written at mode 600 and is covered by the existing ignore rules. Keys stay in each
folder's `.env` at mode 600; the tracked `config.json` files hold none. The
installer no longer sends the entry list over a loopback HTTP service.
**Rollback.** Revert the commit: the previous installer talked to the RPC and needs
nothing else restored. Entries already written stay valid either way, since the
schema did not change.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.12 becomes a real ancestor: the next sync starts from v0.1.12
instead of v0.1.11, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.
Cost this round: 54 conflict hunks over 31 files, against 19 over 14 for
v0.1.11. The growth is ours, not upstream's -- 33 commits landed on the trunk in
the six days since the last sync, and they concentrate in the three files the
sync notes already name as hot (agent/loop/main.py, cli/tui_commands.py,
config/schema.py).
Notable conflict resolutions:
* agent/loop/streaming.py keeps our extracted stream_llm_call and grafts
upstream's one real addition into it: the truncation verdict
(upstream_finish_reason, flag_truncation, and the two LLMResponse fields).
Comparing function bodies against the merge base was what showed aclosing()
and the structured error classification were already there, not new.
* agent/loop/main.py splits an 87-line block that upstream left empty: two
helpers moved into upstream's new loop/failure_streak.py and had to go, four
with live call sites outside the block had to stay. Taking the block whole in
either direction was wrong.
* _dispatch_backend_store takes upstream's detached-task architecture and keeps
our memory-failure tracking inside the task body. The shared tail after the
hunk reads `e`, which upstream's `except Exception:` does not bind, and
drain_backend_stores already had three merged-in callers.
* context_engine/segments/render.py merges two dimensions into identity_text:
our work_dir split and upstream's routed model id. The shared body already
reads names from both sides.
* agent/tools/registry.py keeps both unparseable-argument mechanisms. They sit
at different layers on purpose -- RunMeta comes from a provider on the
non-streaming path, RAW_ARGUMENTS_KEY from the loop on the streaming one.
Nine breakages git merged cleanly and never flagged. This is the shape the
change fails in, and it is worth recording in full:
* The three vendored builds under subagents/ carry a copy of the pre-rename
raven/tui_rpc/ tree, so rename detection sent upstream's 50 lines of
tui_rpc changes into a dead copy instead of raven/rpc/. Only one of the four
files conflicted; the other three were silent.
* subagent/backends/raven_loop.py holds the tool loop we extracted from the
subagent manager, so upstream's run_meta argument never reached it.
* AgentDefaults.max_tokens: upstream dropped it for a dynamic
send_max_tokens(). Both make_provider sites merged onto the new scheme;
providers/resolving_provider.py did not, because upstream has no such file.
* ResolvingProvider never forwarded wire_model_id. Only upstream's own
invariant test catches that class, and the cost is a silently mis-sized
request (16384 against 4096 for one gpt-4o).
* CronService.add_job kept our body but took upstream's signature, losing
`deliver` from both the parameter list and CronPayload while two RPC methods
still pass it, and leaving a call to the _arm_timer scheme upstream replaced
with a wake Event.
* rpc/bootstrap.py still called make_on_cron_job positionally after the
signature narrowed.
* update_everos lost _EVEROS_CONFIG for a root-lookup family, and gained an
ownership gate over its write primitives.
* SessionInitInfo never declared config_notices, in the model or the schema,
while methods/session.py returns it and our own TUI already reads it through
a hand-written type intersection. Both are strict, so a config migration
would have made session.create fail validation in production.
* tests/test_skill_hub_tools.py keyed a fixture under the "local" router
namespace rather than a real registry layer, which upstream's new assertion
exists to refuse.
Also fixed while here: the rich Style cache poisoning that the ci branch
documents as a known crutch (one pinned color_system), and the coverage
baseline's 29 stale raven/tui_rpc/ paths. The baseline totals are still
upstream's own numbers and should be regenerated separately.
Verification, on macOS with a non-root runner:
uv run pytest 8888 passed, 33 skipped, 13 deselected
uv run ruff check all checks passed
uv run ruff format --check 1017 files already formatted
npx vitest run 99 files, 1265 tests passed
npx tsc --noEmit clean, TurnEvent exhaustiveness included
npm run lint:rpc schema and codegen in sync
make check-large-files exit 0
rpc-schema/openrpc.json is the source of truth here, so ui-tui/src/rpc/
generated.ts was regenerated rather than hand-resolved. Nothing under
subagents/ changed.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Adds direct chat with a sub-agent instance: talking to one of the instances a
session has spawned, without that exchange entering the main agent's context.
The TUI gets the feature end to end; the web UI then gets the same thing on the
same runtime.
**The runtime.** A direct turn runs on its own lane (`session#agent/handle`)
rather than the session's, so several instances answer at once while the main
agent keeps its own serial lane, and direct turns draw on a separate
concurrency pool so a user is never queued behind them. Direct turns are not
cancellable: `turn.cancel` keeps meaning the main agent's turn on both
surfaces. Each turn writes a record (`prompt.md` / `out.md` / `meta.json`), and
the main agent learns only that the exchange happened, through a handoff block.
**Sub-agent replies over ACP.** Three separate causes were losing most of a
reply. Raven answered every agent-initiated request with `method not found`,
including `session/request_permission`, and the codex adapter turns any error
from that request into a cancel -- so a turn died as soon as the agent asked to
run something. Raven now approves, choosing among the options the agent offered
by their protocol kind. A stop reason other than `end_turn` was returned as a
finished answer, so a truncated reply read as a complete one; it now carries a
notice. And several messages in one turn were joined with no boundary, so a
preamble, its tool calls and the answer ran together as one paragraph.
**Instance visibility.** A failed resume deleted the whole registry row, which
took the instance off the strip for the length of the turn recovering it, and
permanently if that turn failed; it now drops only the stale binding. A
capability snapshot whose fingerprint no longer matched was discarded, which
defaulted the agent to *stateless* -- editing an agent's `env` silently cost it
resume, its chip, and the `instance` parameter in the spawn schema. Its
capabilities are now kept and flagged, while its verdict is not, so the
`/subagents` row asks for a re-test.
**Working directory.** A direct chat was the one sub-agent dispatch that
supplied none, so it fell back to agent home and ran its commands against
raven's own memory instead of the user's checkout.
**The web UI.** Two wiring gaps came first, both silent: the browser's
dispatcher registered neither instance method, and the web channel never built
the map that tags an event with its addressee, so nothing a client could
demultiplex on was ever sent. The service then routes on that tag at the push
rather than at the read, because the main reply and a direct turn share one
subscription and two consumers on one queue would each swallow the other's
events -- including a `message.complete`, which would end the wrong turn. A
direct turn's events are published out of band; feeding them into the reply
stream is not an option, since that stream is one reply per turn.
Decisions and their measurements are recorded in `docs/specs/`. Notably, the
vendored AgentScope tree is *not* edited, which is a decision rather than an
omission: making a direct chat a real reply would mean re-keying a blocking
per-session lock that guards message storage and tool-call state as well as the
reply loop, and rendering reuse was obtained without it.
## Type
- [x] Feature
## Verification
- `uv run pytest -q` -- 8021 passed, 36 skipped. The one deselected failure,
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`, fails the
same way on `origin/main` in a clean worktree, so this introduces none.
- `uv run ruff check raven/ tests/ ui-webui/service/` -- clean;
`uv run ruff format --check` -- 957 files already formatted.
- Web service: `python -m pytest ui-webui/service/tests -q` -- 13 passed.
- Frontend: `pnpm lint` -- 0 errors, 18 warnings, each one also present before
this change; `pnpm build` -- succeeds; `tsc --noEmit` -- clean.
- Every fix here was checked by reverting it and watching its test go red. Two
tests that passed either way were rewritten after that check exposed them.
- End to end against a running gateway: a direct chat sent through the new web
route completed twice, each leaving a record whose `out.md` held the exact
reply asked for, and the history route returned those turns afterwards.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The last box is unchecked: the terms are defined in `CONTEXT.md` and the designs
in `docs/specs/`, but no end-user documentation or screenshots were produced.
## Risk
**Approving sub-agent permission requests is a widened trust boundary and the
main thing to review here.** An ACP sub-agent that asks to run something now
gets a yes, and the codex preset is configured for its most permissive mode --
wider than the `-a never` the cli transport used. It is unattended by
construction: a dispatch has no operator and no surface that could render a
prompt, so the alternatives were approving or refusing, and refusing leaves the
agent unable to do the work. Rolling back is per-agent config, or reverting
`raven/agent/acp/permissions.py` to restore the refusal.
Two known gaps, neither reachable today, both stated rather than fixed:
- The web UI's event consumer has no `target` guard of its own. The two
surfaces use disjoint session keys and the browser never sends a target, so a
direct turn cannot reach it; a caller that sent one on a `web:` session would
see a sub-agent's reply rendered as the main agent's. Fixing it would widen
this into unrelated files.
- Direct-chat record directories have no TTL and no count cap, like the spawn
and DAG trees beside them. Reclaiming them would also start deleting audit
trails that intentionally outlive session deletion, which is its own change.
Behaviour changes worth naming: a direct chat under a sandbox whose volumes do
not cover the working directory now fails where it used to run quietly in agent
home, matching what the main path already does; and a partial reply now carries
a `[raven]` notice, so anything parsing a sub-agent's reply verbatim sees it.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Adds Python coverage governance to CI so existing coverage cannot
silently
regress and new code stays well tested, without pretending the project
is
already near 100%.
- `scripts/coverage_gate.py` plus `make coverage*` targets compute line
and
branch coverage for the `raven` package and drive four gates:
- **summary** of totals and the lowest-covered files;
- **ratchet** of total line and branch coverage against the audited
`.github/coverage-baseline.json` (0.05pp tolerance for rounding noise);
- **diff coverage** requiring 90% on the executable lines a PR changes
(comments, deletions, and non-executable lines are excluded);
- **baseline-check** rejecting any proposed baseline that lowers line or
branch coverage relative to the target branch.
- The CI unit job runs the suite once with coverage and reuses the
report for
every gate, uploads xml/json/html artifacts on every run (`if:
always()`),
and keeps diff coverage as a PR-only gate.
- `pyproject.toml` configures `coverage.py` (branch mode, `raven`
source, three
documented omissions); generated reports are gitignored.
- Key decision: the ratchet uses a manually bumped, audited baseline
rather
than auto-raising, so the diff-coverage gate is what guards new code
while the
ratchet only blocks regression.
The production-file pathspec uses git glob magic
(`:(glob)raven/**/*.py`) so
top-level modules such as `raven/__init__.py` are not silently dropped
from diff
coverage; a regression test covers this.
## Type
- [x] Feature
## Verification
- `uv run --frozen --python 3.12 pytest tests/test_coverage_gate.py -q`
-> 13 passed
- `uv run --frozen --python 3.12 --extra dev ruff check
scripts/coverage_gate.py tests/test_coverage_gate.py` -> All checks
passed
- `uv run --frozen --python 3.12 --extra dev ruff format --check
scripts/coverage_gate.py tests/test_coverage_gate.py` -> already
formatted
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
No runtime `raven` code changes; this is CI and tooling only. The new
gates can
fail PRs that lower coverage, which is the intended behavior. Rollback
is a
plain revert of this commit (or disabling the coverage steps in the unit
job).
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>