## Summary
One plugin that failed to activate dropped every plugin.
`PluginRegistry.activate` raised on the first plugin whose factory would
not import (or whose contribution name collided), and
`build_plugin_registry` (`raven/core/plugin_stack.py`) answered by
returning an empty registry. A single broken user plugin therefore
silently removed research-flow, ppt-engine, design-engine, the memory
backend and the bundled playbook tools, with one stderr warning as the
only trace. Reproduced with two mock plugins under a scratch
`RAVEN_HOME`: `aa-broken` (factory raises `ImportError`) beside
`zz-good`; before this change the registry came back with `activated:
[]`, after it with `design-engine, everos-memory, playbook, ppt-engine,
zz-good` activated and `aa-broken` named as failed.
Changes:
- **Per-plugin activation** (`raven/plugins/registry.py`). Each admitted
plugin activates on its own. One that fails is rolled back whole (no
partial contribution in any table, and the `sys.path` entry
`_ensure_importable` appended for it is withdrawn), recorded as a
`PluginActivationFailure` (`activation_failures()`), and the plugins
after it still activate. In a name conflict the plugin activated first
(discovery order, by id) keeps the name and the other is recorded as
failed. A module `__getattr__` that raises something other than
`AttributeError` is now a recorded failure rather than an uncaught
crash.
- **Said to the user** (`plugin_stack.build_plugin_registry`,
`runtime.build_runtime`). Each failure is one notice naming the plugin,
its cause and the `plugins.disabled` escape, through the host's notifier
(`HostWiring.notify`), else stderr - the same channel the
missing-memory-backend notice already uses. When the configured memory
backend belongs to a plugin that failed, the memory notice names that
plugin and its cause instead of "no installed plugin provides it".
- **`raven plugins`** shows a `failed` status and the cause under the
table (the command called `activate` directly and previously crashed on
such a plugin).
- **Agents smoke check** (`raven/cli/agents_commands.py`) matched the
old log line "plugin activation failed", which no longer exists; it now
reads the shared `PLUGIN_FAILURE_MARKER`, and its test prints the notice
the real producer writes, so the two cannot drift.
- **Sub-agents inherit the host's opt-outs**
(`product_render.write_rendered`, `inherit_plugin_opt_outs`). A product
engine inherits `RAVEN_HOME`, so it scans the host's `<home>/plugins`
and the shared interpreter's entry points, but it read
`plugins.disabled` only from its own rendered config; a plugin disabled
on the host came back in every product. Every render now merges the
host's list after the product's own. The product's own engine plugin
never travels (`own_plugins=`, passed by all five launchers and the
scaffold): the PPT agent is `ppt-engine`, and a host turning it off for
its own agent is not a request to run the PPT agent without it. A
contract test reads every launcher's `write_rendered` call and requires
it to name its `*_PLUGIN_ID`.
- `CONTEXT.md` (Plugin Registry) and
`docs-site/docs/building-plugin{,.zh}.md` describe the new behaviour.
Not in this PR: the Web UI plugin list (`ext.list`) is discovery-only
and does not show a failed plugin; adding it is a wire change
(`ExtListResult`, openrpc, generated TS, the page) and is left for a
follow-up. The TUI, gateway and `raven agent` hosts show the notice
through their notifiers; the rpc stack (serve/acp) prints it to stderr,
which is also what the agents smoke check reads.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
**Rebased**: head 7cd000dbc on origin/main 8ee5ae0d8, without conflicts.
`git range-diff` shows every commit replayed unchanged. The branch's own
test files rerun at this head: 395 passed. Numbers elsewhere in this
description are from earlier heads.
Head b4d51aee8, rebased onto origin/main 6551f8259 after #698 and #708
merged. #698 conflicted in `raven/config/product_render.py` and
`tests/test_config_product_render.py`: both PRs added a function at the
same spot (`inherit_host_denials` there, `inherit_plugin_opt_outs` here)
and a call in `write_rendered`. The resolution keeps both functions and
all their tests; `write_rendered` now reads `host_config()` once and
passes it to both. #708 touches none of these files. At this head:
```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q -p no:cacheprovider
25948 passed, 109 skipped
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_config_product_render.py
44 passed
ruff check / ruff format --check / make lint-imports lint-deps lint-types / git diff --check origin/main...HEAD
check_source_language.py origin/main...HEAD / make check-commits / check-large-files
all clean
cd ui-tui && npm run lint:rpc && npm run type-check && npm test
144 files, 2106 passed
```
The earlier `TUI checks` failure (run 35834019105, head 5fc374035) was
`newInstancePicker.test.tsx > quick-selects by the number it printed`.
This PR changes nothing under `ui-tui/`; the test passed 5 of 5 runs
locally at this head and in the full ui-tui run above.
The numbers below are from the earlier heads and are kept for the
record.
```
uv run --frozen --python 3.12 --extra dev ruff check raven evolver agents plugins-dist tests scripts
All checks passed
uv run --frozen --python 3.12 --extra dev ruff format --check raven evolver agents plugins-dist tests scripts
2083 files already formatted
make lint-imports && make lint-deps && make lint-types
Contracts: 10 kept, 0 broken / No dependency issues found / All checks passed
git diff --check origin/main...HEAD
clean
COLORTERM=truecolor make coverage (full suite, head before rebasing onto 7fdf296f4)
25847 passed, 109 skipped
COVERAGE_BASE_REF=origin/main make coverage-diff
Diff coverage: 100.00% (71/71 executable changed lines)
PYTHONPATH=. uv run --frozen --python 3.12 --extra dev python scripts/check_source_language.py origin/main...HEAD
exit 0
make check-commits
pass
git merge-tree --write-tree HEAD origin/main
clean
```
After rebasing onto 7fdf296f4 (its two new commits touch none of these
files), the touched suites at this head:
```
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q tests/test_plugin_*.py tests/test_core_plugin_stack.py tests/test_cli_plugin_commands.py tests/test_cli_agents_commands.py tests/test_cli_tui_commands.py tests/test_config_product_render.py tests/test_agents_*launcher*.py tests/test_everos_plugin_discovery.py tests/test_release_plugin_list.py tests/test_cli_gateway_commands.py
727 passed
uv run --frozen --python 3.12 --all-extras pytest -q tests/test_subagent_vendored_agents.py tests/test_rpc_subagents.py tests/test_subagent_acp.py
452 passed
```
Revert-to-red, one production file restored to origin/main at a time
with the tests kept:
```
raven/plugins/registry.py -> 2 errors (plugin_stack imports PluginActivationFailure)
raven/core/plugin_stack.py -> 6 failed
raven/core/runtime.py -> 1 failed (build_runtime hands the host's notifier to the registry)
raven/config/product_render.py -> 42 failed
raven/cli/agents_commands.py -> 1 failed (smoke reds a handshake whose plugin did not load)
raven/cli/plugin_commands.py -> 1 failed (failed row and escaped cause)
agents/raven-ppt/run.py -> 2 failed (engine exemption, launcher contract)
```
Ten existing tests pinned "activation raises" (`test_plugin_registry`,
`test_plugin_bootstrap`, and the conflict tests for tools, hooks, tool
gates and session observers). They now assert the new contract instead:
the later plugin is recorded with the same reason text, the earlier one
keeps the name, and nothing of the loser is registered. Two stubs in
`test_cli_tui_commands.py` took `build_plugin_registry(cfg)` and now
accept the `notify` keyword.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- A plugin conflict used to disable all plugins; it now keeps the plugin
that activates first and skips the other with a notice. Two plugins
contributing the same name therefore run with one of them instead of
none.
- A product sub-agent now starts with the host's `plugins.disabled`
merged into its config (its own engine excepted). A plugin that was
disabled on the host but relied on inside a product stops loading there;
the remedy is to enable it on the host.
- `PluginRegistry.activate` no longer raises `PluginConflictError` /
`PluginFactoryImportError`; the only in-tree callers were
`assemble_plugin_registry` and `raven plugins`. The exception classes
stay exported.
- Security: the change only narrows what loads. A failed plugin's
directory leaves sys.path, and the inherited opt-outs can only remove
plugins from a product, never add one.
- Rollback: revert the squash commit.
- [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-5-5) <noreply@anthropic.com>
## Summary
Make `MemoryBackend` the only seam between the host and the memory
subsystem, so a second memory plugin can be installed without editing
host code.
The abstraction is the goal; no second backend is being added.
What the branch does:
- `health()` joins the Protocol. `raven doctor` and `raven import` read
a `BackendHealth(ready, checks)` the backend fills in with its own
vocabulary, instead of reaching into EverOS internals. Doctor prints the
checks verbatim and never interprets a label.
- A new `[[plugin.contributes.onboard]]` kind, with
`raven/contracts/onboard.py` as its paper. The host lends the wizard
shell as one `OnboardUI` and records the result; the screen returns a
`StepOutcome`. The plugin never writes `memory.backend` -- that key
stays the host's. EverOS's step-4 screen and its `everos.toml`
management move into the plugin.
- The skill source and the after-turn feedback prefix are named from
`memory.backend` rather than the literal `everos`.
- `enabled_by_default` is gone from the manifest: an installed plugin
the user has not disabled is active.
- `tests/test_plugin_boundary.py` pins the dependency direction in both
directions, with an equality assertion so the remaining exceptions
cannot grow.
That guard's allowlist started at five host files still speaking
EverOS's wire protocol. The follow-ups below close three of them.
Two things this branch itself introduced were found in manual acceptance
on an install without the plugin and fixed here: a turn printed which
backends were installed -- empty on exactly the install that needs the
sentence -- and `settings.everos` / `settings.everosSet` let
`ModuleNotFoundError` reach the dispatcher as an internal error carrying
a traceback. Both now carry the note doctor and the wizard already use,
naming the distribution to install.
Review on this PR found four blockers, all fixed and covered. A fifth
defect came out of manual acceptance rather than review, and four more
out of the rounds that followed it -- every one of those in the
embedding endpoint's own plumbing, each found by the round after the fix
that introduced it. They are listed under Risk; the blockers are:
1. `onboard` is an optional contribution, but the wizard equated "no
matching screen" with "not configured", so one `raven onboard
--skip-memory` wrote `memory.backend` back to null for a third-party
backend configured by hand. A backend with no screen now answers on the
strength of having been selected; only one whose own screen says it is
unconfigured is cleared, which is the case that rule exists for.
2. The record a sub-agent call leaves behind ran through a backend
nobody had started. The shipped adapter begins in an unknown state, so
the first flushing write only scheduled a readiness probe and answered
false -- the record said "unavailable" while the service was up the
whole time, and each per-record HTTP client was left open. One context
manager now owns start and stop around a record, in both the manager and
the DAG runner.
3. That record's write and the recall after it addressed different
owners: a real config spells its keys in camelCase and the block reaches
the backend as written, while the adapter read only the contract's
snake_case, so a sub-agent's memories were filed under the host
identity. The adapter reads both spellings.
4. Legacy embedding discovery had narrowed to the recorded plugin root,
so an install predating root recording lost its knowledge-base endpoint
with a valid file still on disk.
**The five follow-ups the seam left behind are in this PR too**, rather
than in three stacked ones, because they are one goal and the branch
protection dismisses an approval on every push:
- The embedding endpoint is raven's. A knowledge base indexes inside the
gateway process and never speaks to the memory service, yet it read its
endpoint out of everos.toml, so selecting another backend left it with
no vectors and no message naming the cause. Raven holds the block now
and hands it to the backend at start -- as a shared default, not an
override: a plugin that was given an endpoint of its own keeps it, and
only one that has none takes raven's. Discovery of an existing
everos.toml still checks all three places the plugin itself looks, read
with plain tomllib so it works where the plugin is not installed. No
data migrates: a base is keyed on its model and measured width, not on
the base url.
- `delete()` joins the Protocol. The browser used to delete a row out of
EverOS's index, in the host process, through the plugin's repository
layer -- while the markdown EverOS treats as the source of truth kept
the text, so the memory came back on the next rebuild, after the user
was told it was gone. The adapter now uses only operations EverOS
already performs, for the kinds it performs them for.
- Sub-agent memory goes through the contract. The read half is a new
optional `recall_session`; the write half needed no new surface, only
two metadata conventions written down. `agents.<name>.config.everos`
becomes `config.memory`, opaque to the host except the two keys the host
reads; the old spelling still loads.
- The memory and settings pages say why they are empty -- no plugin, or
a backend this page does not read -- instead of four zeros and a retry
button that cannot help.
- The `everos` package leaves the host's dependencies for the plugin's
own, at the same exact pin; the host reaches the tree through the
plugin. This is the package layer only: the installers already deliver
`everos-memory` as a sibling wheel from the same release, so an ordinary
install still has long-term memory.
The boundary guard's allowlist falls from five entries to two, both GUI
surfaces still shaped around EverOS's own store. Generalising their wire
is a frontend change and is deliberately not in scope.
This branch was reviewed on GitLab as merge request 639 over three
rounds, including a post-rebase range-diff check. It is being moved here
because GitHub is now the source of truth.
## Type
- [x] Refactor
## Verification
- `uv run pytest` on this branch, rebased onto `main`: 22146 passed, 4
failed, 45 skipped. Three of the four (`test_agents_oncall_launcher`,
`test_agent_loop_token_budget`, `test_agents_code_launcher`) were re-run
on a detached checkout of that same `main` commit in this environment
and fail there identically. The fourth (`test_ppt_engine_image_search`)
could not run in that checkout, whose environment lacks the deck
engine's extras; this branch's only change anywhere under
`plugins-dist/ppt-engine` is the removal of the `enabled_by_default`
manifest key, which that test does not reach. So this branch adds no
regression.
- `npx vitest run` in ui-web: 1680 passed across 103 files. `npm run
type-check` and `npm run gen:check` clean, so the generated client
matches the contract.
- Every fix in the follow-up commits was mutated away and its test
confirmed red, then restored and confirmed green. For the record path
that is three separate mutations: dropping `start()`, dropping `stop()`,
and narrowing the owner lookup back to one spelling.
- `uv run ruff check .` and `uv run ruff format --check` on the changed
files: clean.
- `uv lock --check`: consistent.
- `scripts/check_commit_messages.py`, `scripts/check_large_files.py`,
`scripts/check_source_language.py` over the branch range: clean.
- Manual acceptance against a real isolated install (temporary
RAVEN_HOME, isolated EverOS root and port), 34 cases: `raven plugins`,
`raven doctor` across four backend states, `raven onboard` interactive
and non-interactive including all three step-4 lanes, `raven import`
refusing and importing, an end-to-end write and recall, the web UI's
memory and settings pages driven through a real browser, a sub-agent
trace record, and an install with no memory plugin at all. 31 passed; 1
failed and was fixed; 1 partial; 1 carried over from the earlier round.
- The failure is the one worth reading. On a fresh managed install the
wizard reported embedding configured and the service it started the next
moment ran keyword-only: the spawned process carried no
`EVEROS_EMBEDDING__` values, and EverOS logged that the embedding key
was not configured. The rule deciding whether everos.toml already held
an operator's own endpoint asked whether its model name was a `"<...>"`
placeholder; the shipped template seeds every section with a real model
name and an empty key, so every fresh install read as a deliberate
choice and the host's endpoint was never bound. It now asks the
criterion the module already had -- model and key. The unit tests missed
it because each built its "operator's own" section with a key in it; the
regression copies the shipped template itself.
- The partial: the memory page's search returned relevant results
without error, but every memory in the test corpus was on one subject,
so narrowing could not be observed. The carried-over case is the
skill-source prefix, whose path this branch does not touch.
- Findings recorded and not fixed here, none introduced by this branch:
a progress spinner is still drawn after `import` reports it imported
nothing; an unsupported delete surfaces as a generic internal error; the
TUI log and `doctor` word "no memory plugin" differently; a turn that
did reach disk still prints that it was not written.
- The partial case: an induced agent skill is discovered through
`find_skill` with the backend's prefix, but `read_skill` / `use_skill`
on that id fail. Nothing writes the on-disk layer those tools look in,
on this branch or on `main`, and no test covers it. Pre-existing; filed
as a follow-up.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes:
1. User-track recall is now strictly bounded by `top_k`. A profile row
used to ride outside that bound.
2. `raven doctor` builds the plugin factory, so a managed EverOS setup
writes its env var and config templates during a doctor run. It used to
be read-only. The `--json` memory section is reshaped around
`health.checks`.
3. A third-party drop-in plugin without `enabled_by_default = true` used
to be skipped and now loads.
4. The loader no longer back-fills the EverOS config slice's `root` /
`owned`, nor strips a legacy `mode` key; a leftover `mode` now draws an
unknown-key warning.
5. The wizard's recap shows the contribution name `everos` rather than
`EverOS`.
6. `use_skill` with an unknown prefix reports "not found" after a disk
lookup instead of "unknown source".
From the follow-ups:
7. Config gains an optional top-level `embedding` block. Absent, the
knowledge base reads the EverOS file as before and says so once. An
operator who moves the values across changes nothing else; one who names
a *different* model there gets the existing `StaleBaseError` telling
them to rebuild that base. The block is a default for the memory plugin
rather than an override, so an install that had configured the plugin
separately keeps what it had. Note that a config carrying this block
does not load on an older Raven, which rejects unknown top-level keys.
8. `agents.<name>.everos` is written back as `agents.<name>.memory`. The
old spelling still loads; a per-agent `baseUrl` is ignored with a
warning, having never had a user.
9. Deleting a memory now changes what EverOS treats as the source of
truth, so it stays deleted. Profiles and cases report that they cannot
be deleted rather than appearing to succeed.
10. `pip install raven` no longer pulls the memory engine in.
`install.sh` and `install.ps1` are unaffected: both already resolve
`everos_memory-*.whl` from the release they install and pass it as
`--with everos-memory`, and the source path installs it editable, so
those installs keep long-term memory. An install that reaches neither --
a release predating the sibling wheel, or a bare `pip install` -- now
boots without memory and says which distribution to install rather than
failing on an import.
Found after the acceptance run, in review, all fixed here. They share
one cause worth stating once: the endpoint acquired a second home, and
each fix taught one more reader about it while leaving the next one
behind.
11. The endpoint the wizard saved never reached the EverOS process it
then started. The rule for "does everos.toml already hold an operator's
own endpoint" asked whether its model name was a `"<...>"` placeholder;
the shipped template seeds every section with a real model name and an
empty key, so every fresh managed install read as a deliberate choice
and the host's endpoint was never bound. The service came out of the
wizard running keyword-only while the wizard said embedding was
configured. The rule now asks the criterion the module already had:
model and key.
12. The exported `EVEROS_EMBEDDING__*` variables are a third home,
documented by EverOS and ranked above its file. They were being
overwritten. A complete triple is now an operator's choice; an
incomplete one is not an endpoint and is replaced whole rather than
topped up from the host.
13. Raven writes those same variables itself at startup, so a reader
that asked only whether all three were set called raven's own binding an
operator's export -- a blank settings card and a save refused by naming
variables nobody had set. The module now records which of them it set.
14. That record lived in a module-level set, and `raven gateway
--restart` re-launches through `os.execv`: the values survive, module
state does not. The record now travels in a variable beside them, and is
stripped from the environment handed to EverOS.
15. A settings save the environment would outrank is refused with the
variable names, rather than written and silently ignored.
Four of the five arrived one per review round, each in the fix for the
one before it. The tests that missed them all shared a shape: each built
its "an operator configured this" fixture with a key in it, or cleared
the environment before the case, so the states the product actually
produces -- a template with no key, a live process that has just bound
its own endpoint -- were never the input. The regressions now copy the
shipped template, and run the startup sequence and a second interpreter
rather than a prepared state.
Rollback is a revert of the branch: the seam is additive, and
`memory.backend` keeps its shipped default.
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## 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.
Three renames, no behaviour change:
- raven/plugin/ -> raven/plugins/: the package holds many, and every
sibling package with a plural content is already plural.
- raven/plughub/ -> raven/market/: the hub sells; "market" says so
without colliding with the plugin vocabulary it serves.
- channels' manager / intake / outlet / live_probe and the cli's
_gateway_lock move into a new raven/gateway/ package: they are the
daemon's pipe work, not per-service adapter code and not command-line
surface. The lock goes public as gateway.lock because live_probe,
an inner module, may not import raven.cli.
raven/channels/__init__ stops re-exporting ChannelManager: the re-export
made channels import the gateway package, which imports the channel
contract back -- a cycle. Zero consumers used that path.
The sweep also caught two path constructions the dotted-import rewrite
cannot see: _plugin_stack and its discovery test build the bundled
plugins directory from path segments, and both still spelled "plugin" --
bundled discovery would have come up empty on every start.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Found while investigating the first row of Dizhan's `子智能体功能与显示问题` doc (*回注内容过程中未正常显示,刷新后才会正常显示*). This is not that bug's fix, but it is a real defect on the same wire, and it is the one that explains why "前后端接线没有约定好" was a fair thing to say.
**`turn.started` is not in the `TurnEvent` union — on either side.** It has a schema component, it has a Pydantic model, and neither is reachable from the union that `tests/test_rpc_schema_match.py` walks. The 290-test contract guard has never looked at this event.
So it drifted the first time anyone touched it. `05957452` (judge a dag node) taught `announce_dag_exception` to emit:
```python
mark = {"kind": "dag", "label": run_id, "status": "exception", "run_id": run_id, "node_id": node_id}
```
while `TurnStartedEvent.payload.delegated` still declared `status: enum ["ok","error"]` with `additionalProperties: false`, and `TurnStartedPayload` had **no `delegated` field at all** under `extra="forbid"`. Verified with `jsonschema` against the published contract before changing anything:
```
Additional properties are not allowed ('node_id' was unexpected)
```
That commit did carry `exception` into `TranscriptDelegated` and `SubagentDeliveredEvent` — two of the three places this status lives. The third is the one no test covers.
**It does not crash today**, and I want to be exact about that: `SubscriptionEmitter.emit` pushes a raw dict with no validation, and the page reads only the fields it knows. But the contract test's own docstring says what the cost is — *"both sides declare `additionalProperties: false` / `extra="forbid"`, so a consumer validating against the schema rejects the whole event, not just the unknown field"*. Losing this event loses the boundary that advances the workspace turn counter and draws the delegated row.
## What this does
- `TurnStartedEvent` joins the `TurnEvent` union, in `openrpc.json` and in `raven/rpc/models.py`, so the existing sweep covers it from now on.
- The schema's `delegated.status` gains `exception`; `node_id` is declared.
- `TurnStartedPayload` gains `delegated` as a typed model (`TurnStartedDelegated`), three-valued status included.
- Both generated TypeScript clients regenerated.
- A new test drives **the exact marker `manager.py` builds** through both validators, so the next status or field fails here instead of in a client nobody is watching.
## One thing the union surfaced
`ui-tui` never handled `turn.started`. Its exhaustiveness check said so the moment the variant existed. It draws the delegated row from `subagent.delivered`, which the page deliberately ignores in favour of this event — the two mark different moments: **submitted** versus **started**.
Left as it is, with an explicit `case 'turn.started'` saying why. Moving that surface onto the truer moment changes when the TUI draws the row, which is a product change, not a contract fix.
## Verification
- New test red before the fix, by construction: adding the variant to the union alone reds `test_schema_match_turn_event_discriminated_union` and `..._payload_fields` (schema/pydantic drift), which is how the gap was proved.
- Mutation checks, each reverting one thing:
| reverted | reds |
|---|---|
| `exception` out of the schema enum | 1 |
| `node_id` out of the schema | 1 |
| `delegated` off the Pydantic payload | 2 |
- `uv run pytest -q` — **12900 passed**, 50 skipped, 5 failed; the same five pre-existing on `origin/main` (four `test_security_network.py` NAT64 cases, one `test_doctor_answers_where_the_memories_are`), reproduced on an untouched merge-base worktree.
- `uv run ruff check` / `ruff format --check` on `raven tests scripts` — both clean (both halves of `make lint-python`).
- `ui`: `gen:check` 147 methods, `type-check` clean, `npx vitest run` 89 files / **1225 passed**.
- `ui-tui`: `type-check` clean, `lint:rpc` in sync, `lint:i18n` up to date, `npm test` 138 files / **1990 passed**.
- Worth recording: with `ui-tui/node_modules` symlinked from another checkout the suite reports 82 failed / 59 failed — and reports **the same numbers on an untouched `origin/main`**. It is the symlink, not the branch. Ran `npm ci` in the worktree to get a trustworthy number.
- `scripts/commit_lint` — no errors.
- `git ls-files | grep -c node_modules` — 0.
## Type
- [x] Fix
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear
Widening a contract to match what the runtime already emits: every payload valid before is valid now. No emit site changes, no behaviour changes. The one code change outside the schema and the models is an explicit no-op branch in `ui-tui`. Rollback is a revert.
## Summary
Unit tests were leaking tracing spans into the real `~/.raven/traces`
store. Tracing is on by default and `trace.span()` calls are embedded in
library code (agent loop, subagents, TUI RPC), so any test exercising
those paths emitted spans with fabricated session keys (`session-a`,
`weixin:c`, `tui:default`, ...). Those spans then surfaced as phantom
sessions in `raven trajectory`, while the TUI `/sessions` list (which
reads the real session store) stayed clean.
This PR adds an autouse fixture in `tests/conftest.py` that:
- redirects `RAVEN_TRACING_DIR` to a per-test tmp directory, and
- resets the lazy module-level `TraceStore` cache
(`raven.tracing.spans._store`) around each test, since it pins the
directory resolved at first emit.
Key decisions:
- Only the directory is redirected, not the enabled switch, so the suite
keeps exercising the real emission path with zero behavior change; leaks
land in tmp instead.
- This centralizes the setenv-plus-cache-reset pattern that 8
tracing/trajectory test files already perform manually. Those tests keep
working: their own `monkeypatch.setenv` runs after the fixture and wins,
and they already reset the cache themselves.
- Existing phantom sessions come from archived span logs written before
this fix; the fixture only prevents new leaks. One archive file mixes a
real session with test keys, so cleanup needs line-level filtering and
is left out of scope.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Test-suite hygiene (`test` commit type).
## Verification
- `uv run pytest tests/test_tracing_api.py
tests/test_trajectory_store.py tests/test_trajectory_bundle.py
tests/test_trajectory_replay.py tests/test_trajectory_redact.py
tests/test_cli_tracing_commands.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py -q`: 308 passed, 1 failed
(`test_viewer_health_true_for_our_viewer`, fails identically on
unmodified `main`, environment-specific)
- `uv run pytest tests/test_agent_loop_run_emit.py
tests/test_subagent_manager.py tests/test_tui_rpc_turn_send.py
tests/test_deep_research_tool.py tests/test_agent_loop_approval.py -q`:
109 passed; the real `~/.raven/traces` log did not grow during the run
- Positive check: running `tests/test_agent_loop_run_emit.py` with
`--basetemp` shows the previously leaked session keys (`cli:c`, `tg:c`,
`weixin:c`) now land in per-test tmp dirs
- `uv run pytest tests/ --ignore=tests/integration -q`: 6837 passed, 11
failed, 20 errors; the same failure set reproduces on unmodified `main`
(environment-specific: cron/tz, everos server, theme, config loader,
viewer health), zero regressions from this change
- `uv run ruff check tests/conftest.py` and `uv run ruff format --check
tests/conftest.py`: both pass
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Docs box left blank: test-only change, no user-facing docs affected.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Test-only change; no production code touched. One known interaction:
`RAVEN_TRACING_DIR` takes precedence over `RAVEN_HOME`, so a future test
that fakes `RAVEN_HOME` and expects traces under it must also set
`RAVEN_TRACING_DIR` itself. Rollback: revert the single commit.
## Related Issues
N/A
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
A delivered artifact could not be opened from the page: the file viewer answered
403 and the transcript drew "Raven is confined to the workspace, so this file
cannot be opened here" over a delivery card it had just rendered.
The viewer's state-directory fence exempts the workspace subtree, on the stated
grounds that the default workspace lives inside raven's home and denying it
would refuse every file the agent itself wrote. Since agent home and the working
directory were split apart, a turn no longer writes there: it writes in
`~/.raven/tmp/<channel>`, a sibling of the workspace, inside the same state root
and outside the carve-out. So the fence denied exactly what the carve-out exists
to allow, one directory over, for every artifact produced since that split.
This exempts the working-directory root alongside the workspace, using the same
containment test in the same direction, so a working-directory root that happens
to sit above raven's home earns no exemption. `config.json`, `oauth/` and
`serve.json` are siblings of both and stay refused, which is what the fence is
for.
Worth noting for a reviewer: the bytes were already reachable. `/files/download`
serves a delivered file by token with no path fence, so this was never a
security boundary for deliveries -- only a viewer that refused to render what
the same page could already download.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_rpc_transport.py tests/test_rpc_files.py tests/test_rpc_knowledge.py tests/test_rpc_console.py -q` -> 123 passed
- `uv run ruff check` and `uv run ruff format --check` on both changed files -> clean
- Both new assertions were mutation-checked, each against its own mutation:
- narrowing the carve-out back to the workspace alone reds
`test_the_turn_working_directory_is_exempt_from_the_state_dir_fence` only (1 failed, 3 passed)
- dropping the containment-direction guard reds
`test_a_working_directory_root_that_contains_the_state_root_earns_no_exemption`
and the pre-existing state-dir test (2 failed, 2 passed)
- Against the real reporting case: the two files that were answering 403
(`~/.raven/tmp/tui/*.md`, `*.pptx`) now resolve, while `~/.raven/config.json`
and `~/.raven/serve.json` still raise PermissionError.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- Widens what the file viewer will render by exactly one subtree: the directory
turns work in. Everything the fence was written to protect (provider keys in
`config.json`, the OAuth token store, `serve.json`) sits beside that subtree,
not inside it, and stays refused -- pinned by the tests above.
- `fs.list` / `fs.reveal` share the function but pass the session's working
directory as the root, which their own containment check already bounds, so
their behaviour is unchanged.
- Rollback is a one-line revert of the exemption tuple.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
PR #360 reports every copy-on-select write as a permanent transcript
line, so a
reading session that drags through the transcript piles up "copied N
characters" rows under the conversation. The confirmation splits by what
the
line is for: the unbounded terse repeats become a transient notice
rendered
above the input box -- one line that replaces itself on every new copy
and
clears after 3 seconds -- while the first copy of a session keeps its
path
caveat in the transcript. The caveat is the answer a user comes looking
for
after a paste comes up empty minutes later, and it cannot pile up
because it
is once per session by construction.
The reporter still owns the per-session caveat tally and now returns
`{ text, firstOfSession }` so the caller can route the caveat to the
transcript and the repeats to the notice. A new `copyNoticeStore` holds
the
single notice; `showCopyNotice` keeps one dismiss timer, clearing any
pending
one before arming the next, so an earlier deadline can never clear a
newer
notice. `/copy` is deliberately untouched: an explicit command's answer
still
belongs in the transcript, and it cannot stack on its own.
## Type
- [x] Fix
## Verification
Run from `ui-tui/` at branch head, in a fresh worktree of `github/main`.
Dependencies came from `npm ci` in `ui-tui/` and in the hermes package;
the
hermes package's own `node_modules` holds only esbuild, so the ink
render
tests run against one react copy (two copies break every hook call).
```
npx vitest run --no-file-parallelism
Test Files 93 passed (93)
Tests 1084 passed | 13 skipped (1097)
npm run type-check
clean, exit 0
npm run lint
22 problems (0 errors, 22 warnings)
npx prettier --check src/app/copyNoticeStore.ts src/__tests__/copyNotice.test.tsx
src/__tests__/clipboard.test.ts src/app/useMainApp.ts
src/components/appLayout.tsx src/lib/clipboard.ts
All matched files use Prettier code style!
python3 -m scripts.check_commit_messages github/main..HEAD
exit 0
```
The 22 lint warnings are the baseline, not new: 22 before the branch and
22
after, none in a file this branch touches. The suite is run with
`--no-file-parallelism` deliberately: the ink render tests fail under
default
worker parallelism at this suite size, and no CI job runs them.
Suites that exercise the changed code directly:
`src/__tests__/copyNotice.test.tsx`
(7 cases), `src/__tests__/clipboard.test.ts` (30 cases, the 3 reporter
cases
updated to the new return shape).
New tests were proved load-bearing rather than assumed:
- Removing the notice render line in `appLayout.tsx` makes the render
test
fail (content and placement above the input box).
- Removing the pending-timer clear in `showCopyNotice` makes the
re-shown-notice test fail: the earlier 3s deadline then clears the newer
notice.
- The dismissed-notice case now shows a notice first, and removing
`dismissCopyNotice`'s atom clear turns it red (review fix).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No doc change. `ui-tui/CONTEXT.md` has no clipboard or selection entry,
and
"copy notice" continues the existing "notice" vocabulary of
`copyResultNotice`
/ `copyOnSelectNotice`, so nothing new is coined.
## Risk
Behaviour change: the per-drag copy confirmation is now transient and
above
the input box instead of a permanent transcript line, and the first copy
of a
session lands one transcript line, exactly as on `main`. Reverting the
branch
restores the #360 behaviour; no data or on-disk format is involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (deepseek-v4-pro) <noreply@anthropic.com>
Absorbs the GitHub release into the downstream trunk. A merge rather than a
rebase so v0.1.13 becomes a real ancestor: the next sync starts from v0.1.13
instead of v0.1.12, and the eventual contribution back to GitHub can still tell
our commits from the upstream ones it already has.
Cost this round: 51 conflict hunks over 27 files, against 54 over 31 for
v0.1.12. The hunks were the cheap half. Upstream's #284 moves the model and
provider from process-wide state to a per-session binding, and the trunk had 230
commits standing on the old shape.
What git reported as a clean merge and was not
---------------------------------------------
Fourteen upstream-changed paths do not exist here, because we renamed or moved
them since v0.1.12. Rename detection found none of them, so their changes were
merged into paths nothing reads, silently:
* raven/tui_rpc/* -> raven/rpc/* (renamed in ce526ad5). Nine files, including
question_broker.py, whose whole #354 rewrite was lost, and methods/config.py,
methods/model.py, methods/session.py, models.py and errors.py. Each was
replayed by three-way merge against dd82f52c. The three test modules were
rebased function by function onto upstream's version instead, after a
three-way merge spliced assertions into the wrong tests.
* raven/agent/tools/mcp.py -> raven/mcp/client.py. Carried the release-blocking
fix, and is handled in the commit that follows this one.
* ui-tui/rpc-schema/openrpc.json -> rpc-schema/openrpc.json.
Decisions
---------
Follow upstream wherever the two disagree about provider and model:
* providers/pin.py is gone, so a bare model id is refused instead of derived.
A model id does not name whose credential serves it, and the derivation
walked a list -- with two vendors configured, which one pays came down to
their order in it. rpc/methods/config.py now requires the provider.
* ModelSwitchInTurnError (-32009) is gone with it. A session switch lands on
that session's next turn, so there is nothing to refuse mid-turn.
* AgentLoop.refresh_context_window and the LazyProvider on_built wiring are
gone: the window rides on the binding now.
* The skill gate no longer forwards an unpaired pin.
Keep ours where the trunk is ahead, and graft upstream's behaviour into it:
* raven/agent/subagent/backends/raven_loop.py is the live sub-agent path, so
manager.py's inline loop stays retired and the web_search gate from #312
applies there.
* skill_hub/client.py keeps the public zip limits the skillhub RPC path imports,
and takes upstream's query-string cap.
* ask_user keeps our JSON-string normalizers and feeds them into upstream's
batch contract, so a batch validated by _prepare is one _normalize_questions
has already coerced.
* The chat view composes both filters: hideIntroAfterFirstTurn drops the cover,
visibleRows still hands the view to a direct chat.
Tests removed, not repaired
---------------------------
Eight tests covered mechanisms this merge deletes, and one of them hung rather
than failed:
* seven in test_agent_loop_model_switch.py over AgentLoop._pending_provider,
the switch-parking mechanism #284 replaced with per-session bindings. Its
replacement arrives with upstream as test_agent_loop_session_model.py.
* test_a_refusal_during_a_turn_keeps_its_own_code in test_acp_methods.py, whose
error class no longer exists.
Baseline: the pipeline for 01d39e58, this merge's base, is green, so nothing
here can be charged to a pre-existing failure.
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
A WeChat user asked for a recommendation and the bot answered "the web
search
tool is not configured here". That sentence was not the model's own
phrasing --
it was the tool's error text, relayed outward. `web_search` needs a
Serper key
and that deployment has never had one, but the tool was registered
unconditionally, so on every search-shaped question the model saw it,
reached
for it, and passed the setup error on to whoever was in the chat.
Withholding the tool fixes that and creates a second problem: an
unregistered
tool is invisible. Nothing in a running Raven then says the capability
exists at
all -- the model is never offered it, no document lists it, and `raven
doctor`
reports on providers and memory but has never mentioned tools. The only
way to
learn that web search is one account and one edit away was to read the
source.
This does both halves, because either alone leaves a real gap: the
deployer is
told what this install can and cannot do, and the model is still not
offered a
tool it cannot run.
### Withholding the unusable tool
`web_search` is gated on a resolved key, in the main loop and in the
sub-agent
surface (`subagent/manager.py`) -- a sub-agent that reaches for a search
it
cannot run reports the failure to its caller, and that text lands in the
parent
turn, the same leak one level down.
The gate asks the tool, not the config. `WebSearchTool.api_key` resolves
at call
time from the constructor value *or* `SERPER_API_KEY`, so reading
`tools.web.search.apiKey` alone would withdraw a working tool from any
deploy
that exports the variable and configures nothing.
The tool's error message also hard-coded `~/.raven/config.json` while
the
gateway runs with `--config` elsewhere, so following it meant editing a
file the
process never reads. It names the path actually in force now. That text
is
reachable only if the key disappears after registration, which is
exactly why it
should be right: it is the message for the case the gate cannot cover.
### Three rules, and nowhere to read them
Registration is decided per family, each a different shape:
| family | rule |
|---|---|
| `web_search` | a resolved key, asked of the built tool |
| `web_fetch` | nothing -- always registered, a key only improves
extraction |
| media x3 | an `api_key` *or* a `model`, either counting as configured
|
For media those are two questions, not one. A section naming only a
model is
registered, because a model alone counts as asking for the tool, and
then every
call returns a missing-key error. Whether a capability is *offered* and
whether
it *works* come apart there, and a report treating them as one fact
ticks a
capability that cannot run.
Each rule is defensible where it sits. What is missing is anywhere to
read them.
Providers had the same sprawl once and answered it with
`providers.auth`: a
declarative table plus `credential_status` as the single authority, with
an AST
invariant enforcing that authority, because six surfaces had answered
the same
question six ways and each looked reasonable alone. Tools never got the
equivalent.
### What this adds
**Each tool answers for itself,** twice where the questions differ.
`WebSearchTool.is_configured` reads the config value *or*
`SERPER_API_KEY`,
because those are two sources and only the tool consults both. The media
base
answers `is_configured` on a model *or* a key -- which is what stops an
OpenRouter credential set for chat from silently switching on three
tools that
bill per call -- and answers `has_key` separately on the chain it
actually
resolves at call time: its own section, the borrowed provider key, then
`OPENROUTER_API_KEY`. Both rules live with the credential they read.
**`capabilities.py` describes the five** for a human deciding what to
set up:
what each does in one line, how much work it is (nothing / reuse a
credential
you already have / obtain an account), where the key goes, where to get
one, and
what it costs. It rules on nothing -- `is_configured` and
`has_credential` both
ask the tools -- so it cannot become a second opinion.
**`raven doctor` grows a section**, listing every capability configured
or not,
ordered by how much the deployer has to do:
```
(markers render as a green check and a yellow bang; spelled [ok] and [!] here to
keep this description ASCII, since it becomes the squash commit body)
Tool capabilities
web_fetch: [ok] Read a web page the agent already has the URL for
image_generate: [ok] Generate an image (borrowed: providers.openrouter.apiKey)
text_to_speech: [!] Generate speech from text
no key resolves; calls will fail
set: tools.media.speech.apiKey
or env: OPENROUTER_API_KEY
video_generate: - Generate a video
switch on: tools.media.video.model
key: reusing providers.openrouter.apiKey
Billed per call; needs prepaid OpenRouter credit.
web_search: - Search the web
set: tools.web.search.apiKey
or env: SERPER_API_KEY
key from: https://serper.dev
2 capability(s) available but not set up; the agent is not offered them.
```
Three deliberate details.
Naming the credential is load-bearing in both directions. A row that
cannot
distinguish a reused credential from a missing one sends someone to
create an
account they already have -- and a row that claims a reuse with nothing
to reuse
is worse, because acting on it means setting a model, getting a
registered tool,
and watching every call fail on a credential they were told they had. So
the
reuse line prints only when a key is genuinely there to pick up, and a
capability already in that broken state says so outright instead of
showing a
satisfied tick.
The credential is named at the path that holds it. For the media family
`config_path` names the *model*, so reusing it as the key source pointed
the
deployer at a line with no credential in it.
And each fact is on its own line rather than in a sentence, because the
terminal
wraps a long line mid-path and a config key broken across two rows
cannot be
copied, which is the only thing that row is for.
Nothing here moves the exit code, including the warned row. An install
without
image generation is a choice, not a fault, and a doctor that fails on it
teaches
people to ignore doctor. The half-finished one is arguable -- the memory
section
does exit non-zero for a role the user configured that the server could
not
build -- but that failure is silent where it happens, recall just
returning
nothing, whereas this one returns an error string to the model on every
call.
Say the word and it becomes an exit code instead.
### Not in this change
Registration still lives in `AgentLoop`. Having it read the table is the
point
of this shape and removes the last duplicate reader, but it edits
`agent/loop/main.py`, which is under active change, and it is worth
doing on its
own once that settles. Until then the table is a description, and the
tests
below are what keep it honest.
`deep_research` is deliberately absent: it is moving to the sub-agent
surface
and its tool is going away.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
Mixed on purpose: the first commit is a fix and the rest are the feature
it
made necessary. Splitting them would land a change that hides a
capability
without landing the one that makes it discoverable.
## Verification
```
make lint exit 0
make build exit 0
npm run test --prefix ui-tui 969 passed, 13 skipped
uv run --all-extras pytest -q 6186 passed, 35 skipped, 1 failed
uv run pytest tests/test_tool_capabilities.py \
tests/test_cli_doctor_commands.py \
tests/test_agent_loop_web_tools.py 64 passed
uv run --extra dev ruff check raven tests scripts All checks passed
uv run --extra dev ruff format --check 828 files already formatted
npx commitlint --from origin/main --to HEAD exit 0
scripts/check_commit_messages.py origin/main..HEAD exit 0
```
The one failure is
`test_read_file_image.py::test_an_attachment_that_cannot_be_
read_costs_a_note_not_the_turn`, and it is not from this branch: it
fails the
same way on `main` at `1cb604a` with these commits absent. The case
makes a file
unreadable with `chmod 000`, which does not block a root user, so it
fails for
anyone running the suite as root and passes in CI. This branch does not
touch
that file or the code under it.
The capability tests drive a real `AgentLoop` and compare what it
registered
against what the table predicts, rather than asserting the table against
itself.
The gated set is derived -- tools present once credentials are supplied,
absent
without -- so a sixth gated tool whose author forgets the table fails
here rather
than going unnoticed.
That last claim was false when first written, and the last commit is
what makes
it true. The fixture listing the media tools by hand never switched a
fourth one
on, so a new one never joined the gated set and the assertion held over
an
already-incomplete table. #305, which adds a MiniMax voice-clone tool,
is that
case: merged against this branch the assertion passed. Read from
`MediaGenConfig` instead, it fails and names the tool -- `gated but
undeclared:
['voice_clone']`.
Which means whichever of the two lands second turns this red,
deliberately. The
fix is one table entry, and it needs the rule that PR settles:
`voice_clone`
counts as configured on `api_key or api_base or model` in
`effective_media_config` while registration still gates on `api_key or
model`,
so an `apiBase`-only install with no MiniMax key is configured by one
rule and
withheld by the other. That is the divergence this table exists to make
visible,
and it is worth resolving there rather than papering over here.
Fifteen mutations, each caught:
```
the web_search gate removed from the main loop 3 failed
the same gate removed from the sub-agent surface 1 failed
media rule reads only the key 7 failed
web_search rule reads only the config 1 failed
a tool removed from the table 6 failed
the doctor section not rendered 6 failed
doctor lists only configured tools 4 failed
unconfigured treated as a failure 17 failed
the reuse line is printed unconditionally 1 failed
the key source falls back to the model path 3 failed
a keyless registered capability is not flagged 1 failed
has_key always answers yes 1 failed
has_credential collapses into is_configured 1 failed
the credential chain drops OPENROUTER_API_KEY 3 failed
the reuse check ignores the environment 3 failed
```
Four of those tests exist only because a mutation pass found the earlier
versions insufficient, and the last rounds are why the shape changed. A
media
case that sets both a model and an OpenRouter key proves nothing about
the "or
model" half: the borrow fills the key in, so a rule reading only the key
still
answers correctly. The case that pins it has nothing to borrow.
The sub-agent case is the same argument applied to the second call site:
with
the gate present only in the main loop, every test above still passes,
because
nothing was watching what the sub-agent surface registers.
More usefully, mutating `has_key` to always answer yes changed no test
at all in
the first version, which said the ruling was not load-bearing: the
doctor was
inferring "no credential" from an *empty source string* rather than from
the
tool's answer, so a fourth credential source would have been reported as
a
missing one. `has_credential` is now its own fact, asked of the tools,
and that
mutation fails.
Separately, autouse fixtures clear `SERPER_API_KEY` and
`OPENROUTER_API_KEY`,
without which several of these pass for the wrong reason on any machine
where a
developer exported one.
Rendering was checked against a real config in six states -- nothing
set, a
provider key present, a model with nothing to borrow, a tool with its
own key, a
model plus a borrowable key, and an exported variable as the only source
--
rather than only asserted on.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
One behaviour change: `web_search` is no longer offered to the model
when no key
resolves. That is the fix. A deployment that has a key, in config or in
the
environment, is unaffected; one that has none was getting an error
string in
place of an answer.
The rest is additive. No other registration logic changed, so which
tools an
agent is offered is otherwise exactly what it was; `is_configured` moved
the
existing predicates onto the tools without altering them, and the
mutation
results above are what pins that. `has_key` and `_resolve_key` are new
names for
the chain `api_key` already resolved -- the property calls the extracted
one, so
callers see the same answers.
`raven doctor` gains a section and no new exit code. Its zero-network
guarantee
holds: the table reads config and environment only.
Two allowlist entries were added to
`test_only_the_auth_module_decides_configuredness_from_a_key`, argued in
place:
`subagent/manager.py`, which asks the built tool whether a key resolved
so an
unusable search is withheld, and `capabilities.py`, which reads keys to
*report*
-- which source supplied one, and whether one is there to reuse. Both
ruling
halves are delegated to the tools, whose files were already listed.
Rollback is a revert. Nothing is written and no configuration is read
differently.
- [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-5) <noreply@anthropic.com>
## Summary
- Declare the existing Raven application logo as the served page favicon.
- Copy the logo into the packaged page assets so installed builds render the same branding.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
- `npm test --prefix ui` - 32 test files and 528 tests passed.
- `npm run type-check --prefix ui` - passed.
- `npm run build --prefix ui` - passed.
- `python3 ui/build.py` - built the page and copied the Raven logo asset.
- `node ui/scripts/check-page.mjs` - passed.
- `make check-large-files` - passed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Low risk. The change only adds favicon metadata and packages an existing application asset. Reverting the two source changes restores the prior browser-default icon.
## Related Issues
N/A
## Summary
An identity EverOS cannot accept becomes a directory segment on its
write path, so `EverosBackend.start()` rejects it. The rejection carried
the one message a user can act on -- it names the key and the accepted
pattern -- and no surface delivered it as one. Three of the four call
sites fold the raise into `logger.exception`; under the TUI loguru is
file-only, so there an invalid identity turned memory off with nothing
on screen. The fourth, in `import_commands._build_and_run`, is not
wrapped at all, so the `ValueError` escaped as a bare traceback. Where
it was visible it was a traceback, which is not a thing a user reads as
"edit this key".
The state machine then told the user the opposite of the truth.
`start()` died before assigning a state, so `_state` stayed `UNKNOWN`,
which is not in `_NEVER_HAD_MEMORY`; every `store()` after it counted a
dropped write, and the session ended with:
```
1 turn(s) were not written to long-term memory because the memory service was
unavailable.
```
The service was fine. That sends the user to debug a server that never
broke.
**The change.** Catch the `ValueError` in `start()`, give it a
`BAD_IDENTITY` state, and file that state with the other two the user
must fix themselves:
- terminal, so a stray probe cannot promote it to `READY`;
- never-had-memory, so no dropped-write count and no outage wording;
- the message goes to stderr, matching what the unconfigured-LLM and
missing-binary paths beside it already do.
Two things came out of running it rather than reading it:
1. **The message needs escaping.** It quotes the accepted-character
class, and rich reads `[a-zA-Z0-9_.@+-]` as a markup tag and eats it,
leaving the user the pattern `^+$` to match their id against. The test
now pins the full class.
2. **`raven import` had the same defect on its own gate.** It kept the
outage wording and pointed at the server log, which holds nothing about
a config error. It now names the config keys instead.
Before / after, same config (`memory.userId: "bad/id"`), same command:
```
- 1 turn(s) were not written to long-term memory because the memory service was
- unavailable.
+ Long-term memory is off: memory.userId='bad/id' is not accepted by EverOS: it
+ becomes a directory segment on the write path, so it must match
+ ^[a-zA-Z0-9_.@+-]+$ and must not be '.' or '..'.
+ Fix memory.userId / memory.agentId in your config.json, then start a new session.
```
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Re-run after rebasing onto `d35e398c`, the current `main`.
```
uv run pytest tests/test_everos_backend.py tests/test_cli_import_commands.py \
tests/test_everos_plugin_discovery.py -q
162 passed
uv run pytest -q
1 failed, 6478 passed, 43 skipped, 13 deselected
uv run ruff check <the four touched files> All checks passed
uv run ruff format --check <the four touched files> 4 files already formatted
```
The one failure is
`tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare`. It
is pre-existing on this base: checked out `d35e398c` in a clean worktree
and ran `uv run pytest tests/test_cli_theme.py` there, same failure, 1
failed / 44 passed. It passes in isolation and fails when the file runs
as a whole, so it is order-dependent, and it is unrelated to anything
here. That file is untouched by this change.
Manual check, sandbox `RAVEN_HOME`, `memory.userId: "bad/id"`, `raven
agent -m "hi"`: prints the block quoted above, and the session no longer
ends with the dropped-write line.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Terminal-only wording plus one new enum member. No config, schema, or
protocol change; an identity that was accepted before is accepted now,
on the same code path. The only behaviour change for a valid setup is
none.
For an invalid identity the turn behaves as it did -- memory off, turn
completes -- and only what the user is told changes. Rollback is
reverting the single commit.
`ServiceState.BAD_IDENTITY` is new. Every consumer was checked:
`raven/cli/import_commands.py` (handled here) and
`tests/test_everos_plugin_discovery.py` (reads `READY` only).
`_may_spawn` allowlists `UNKNOWN` via `_SPAWNABLE_STATES`, so a new
member is non-spawnable without a change.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#271
Co-authored-by: zhanghui <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
## Summary
The session rail (left sidebar) becomes a React island: `ui/src/features/rail/` with types, a plain external store (draw/skeleton/markNew/remove/rename, fold state on the `raven.gui.grpfold` localStorage key), the Row/Group/RailApp components with classes and DOM shape copied byte-for-byte from the legacy renderer, and 13 tests.
Key decisions:
- `SESS`/`cur` stay shared page globals: ten demo/live files write them (including whole-array rebinds), so the island owns no rows. It reads through `DS.sessions.snapshot()`, a closure over the rebindable bindings, re-read on every `drawList()`.
- Island actions go out through 9 new optional bridge verbs (`drawList, setCur, openSession, removeSession, renameTitle, dropDraft, pinPersist, openCron, navState`), each one a guarded one-liner in 155-bridge.js and late-bound so live rebinds keep winning.
- `plainTitle` moved into the bundle and is republished as `window.plainTitle` for its 6 legacy callers (same pattern as `cronExprHuman`).
- Shrink: demo/050-rail.js 222 -> 16 lines; live/010-boot-guard.js raw-DOM skeleton painter became one `RavenIslands.rail.skeleton()` call; live/030-sessions.js untouched (already renderer-free, its helpers are read by other domains).
- Pre-existing bug left as-is: live/080-overrides' rename persist wrapper queries `#title input` after the h1 swap and throws today; the island reproduces the demo DOM dance exactly rather than patching another domain in this MR.
Ratchet: 57 -> 57 (the strands touching this domain remain demo-declared/live-assigned by design; nothing new added).
Note: pipelines are currently red project-wide with `ci_quota_exceeded` (shared-runner minutes exhausted). Local gates below are the same commands CI runs; the pipeline should be retried once quota recovers.
Review round: the fake shell handed `markNew` an empty nav and a folded More group, so both of its branches were dead in every test -- exactly the part of the port that changed shape (`Object.keys(NAV_OF)` to `nav.pages`, `$('#' + p)` to `getElementById`, `MORE_ROWS[i][0]` to `nav.morePages[i]`). Two cases added with the real nav: a module page up marks its own rail button over the new-task row, and an open More group puts the mark on the row whose page is up while the parent gives it up and takes it back when folded. Both fail against a wrong port.
## Type
- [x] Refactor
## Verification
- `npm run --prefix ui type-check` clean
- `npm test --prefix ui` 49/49 (13 new rail tests)
- `npm run --prefix ui build` (223.95 kB IIFE) and `python3 ui/build.py` (1,094,616 bytes)
- `node ui/scripts/check-page.mjs` OK; `node ui/scripts/count-shared-globals.mjs` 57/57
- `uv run pytest tests/test_ui_language_repaint.py` 9/9
- Stub browser pass (`?stub=1`): DOM byte-compared to legacy (.grp/.sess shapes, aria-current moves, fold persistence, search, pin+persist, delete+undo toast, rename via top bar, running mark lifecycle, More flyout marks, zh/en repaint)
- Live pass against a throwaway gateway (temp RAVEN_HOME, dummy keys, nonce auth): boot shows exactly 6 skeleton rows with the legacy width formula while `data-counts="pending"` holds, then the real list swaps in; draft's first send creates a real session; two-session switching moves a single mark; second boot renders with no mock flash
- Not exercised live: a successful provider turn and parked done/err badges (needs a real key); covered by unit tests and the stub replay
## Risk
User-visible behavior is intended to be identical; the rail DOM shape and class names are unchanged. Rollback is reverting the single commit.
## Related Issues
N/A
## Summary
Three follow-ups from #341, which fixed a retired `contextWindowTokens:
65536` capping every upgraded install at 64k. Two are its loose ends;
the third is the reason it happened at all.
**The notice no longer prints on stdout.** #341 drains config-migration
notices in the `run()` wrapper so every command tells the user, which
caught the two whose stdout is a machine-readable document: `raven
doctor --json` and `raven import --json`, both advertised for
automation. Reproduced -- a config still carrying the retired pin makes
`doctor --json` emit JSON with a sentence after it, and `jq` refuses the
result. Moved to stderr, where the rest of this class of message already
goes (the `ConfigReadError` branch a few lines up in the same wrapper,
and the loader's malformed-config warning). That fixes any future
`--json` command without it having to know this exists, which
allow-listing the two would not. The window is narrow -- the migration
fires once per install -- but the run it can spoil is a first run after
upgrading, and a CI job is exactly the caller not watching.
**`raven doctor` gains a Config section and a `--fix`.** The premise
changed while building it: the migrations run at load, so by the time
this command looks, nothing is pending -- they already happened,
silently, one launch ago. What is left for a person to ask about is what
Raven deliberately will not decide for them. So it reports a
`contextWindowTokens` pinned below what the configured model holds, and
names what rides on it: the per-turn history budget, when the Curator
starts paying for a slow path, and when memory consolidation archives.
`--fix` removes the pin.
Reported without `--fix`, never written: that pin is a real
configuration for a local model or an endpoint served smaller than the
catalogue thinks, and the flag is the user saying which case theirs is.
The write carries the file mode across (config.json holds
`providers.*.apiKey`) and uses a per-PID temp name -- the same rules the
loader's migration writer follows.
One check rather than two. A config naming no provider is the other
thing worth asking about, but it reads differently on either side of the
explicit-provider rule in #284, so it belongs to that change; a model
that routes to nothing is already reported above it.
**The bootstrap stops writing every default into the user's config.**
This is the cause of the bug #341 cured. `save_config` dumped the whole
`Config()`, so a new install started life with eight kilobytes of
settings its owner had never heard of and, worse, with that day's
defaults frozen into their file -- after which a default we improve
never reaches anyone who already has one. `contextWindowTokens: 65536`
got onto disk exactly this way.
It now writes only what differs from the defaults. Lossless on reload,
since a value equal to its default reloads as that default. A fresh
config drops from 7,985 bytes to 2, and to 634 once the extension blocks
are seeded -- what is left is the handful of lines someone actually
chose, which is also a config they can read.
That third one is the only change here with a broad blast radius, and it
has one visible consequence, which is an improvement: the onboarding
picker used to lead with the schema's default model, because the
bootstrap had written it into the config and the wizard read it back as
"the current model" -- a value nobody had chosen, offered as though
somebody had. With nothing written, the wizard leads with the provider's
own recommendation instead. The test that pinned the old list now pins
the new one and says why.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```
pytest tests/ 6650 passed, 1 failed, 33 skipped
(tests/test_cli_theme.py::test_bold_accent_renders_styled_not_bare,
which fails identically on github/main when its file runs
together and passes alone on both)
ruff check raven/ tests/ All checks passed
ruff format clean
```
Driven by hand as well as by tests, each against a throwaway home:
```
doctor --json on a fossil config stdout parses as JSON again; the notice is on stderr
doctor (pin 65536, model 1M) reports the pin and what is sized against it
doctor --fix pin removed, file still 0600, a second run reports nothing
save_config on a fresh Config() 2 bytes; 634 after the extension blocks are seeded
```
New cases cover the stderr split, both doctor paths including the mode
preservation, and the save round-trip keeping every value the user
chose.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
The bootstrap change alters what every new install's config file looks
like: nearly empty instead of a full dump. Existing configs are
untouched -- nothing rewrites them -- and both shapes load identically,
so the risk is confined to anyone reading `config.json` as documentation
of what can be set. `raven doctor` and the schema remain the answer to
that question.
The onboarding picker's default moves from the schema default to the
provider's recommendation, as described above.
`doctor --fix` writes only when asked, and only removes a key.
Everything else here is output routing.
Rollback: revert the commits. Nothing persists a new format, so a
reverted build reads every config written under this one.
## Related Issues
N/A
---------
Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
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
- Reframe the README around benchmark evidence, onboarding, Deep
Research, and Tracing.
- Restore the main branch's opening product capability overview before
the benchmark evidence.
- Keep the table of contents removed and place the native Markdown
benchmark table directly after the introduction.
- Remove outbound links from the three benchmark row labels while
preserving the reported results and supporting context.
- Synchronize the English and Chinese READMEs around the same structure,
spacing, and Back to top section boundaries.
- Place the GitHub User Content onboarding recording directly below the
benchmark table in both READMEs, using the same bare attachment URL.
- Reduce duplicate capability, gateway, status, and ecosystem copy while
preserving concise architecture and command references.
- Document current runtime behavior for the six-step onboarding flow,
MiroThinker-backed research delivery, and local trace storage.
## Type
- [ ] Fix
- [ ] Feature
- [x] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [ ] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
Commands and results:
- `.venv/bin/pre-commit run --files README.md README.zh-CN.md` - passed
all applicable hooks.
- `git diff --check origin/main...HEAD` - passed.
- `make check-large-files` - passed.
- `git merge-tree --write-tree HEAD origin/main` - passed with no
conflicts.
- README structure assertions - passed: no table of contents, no
benchmark-label links, and four matching Back to top boundaries in each
language.
- Confirmed both READMEs use the same 33378-byte GitHub User Content
hero banner; benchmark evidence is native Markdown.
- Confirmed the 1179517-byte onboarding MP4 round-trips from GitHub User
Content with SHA-256
124024e6d64c23b3e314aa6136d9e0d922f57ded97a830a5c97cd1323cb2c57f and
renders with controls below Benchmarks in both languages.
- `uv run pytest --tb=short -q` - 6130 passed, 33 skipped, and one local
Python 3.14 ANSI color assertion failed; the GitHub Python 3.12 unit job
passed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
This is a low-risk documentation-only change. Rollback requires
reverting the README commits; externally hosted user-content assets can
remain unreferenced without affecting repository size.
## Related Issues
N/A
## Summary
`workspace` meant two things at once: the agent's global home (user memory,
skills, transcripts, memory store, Skill Hub cache) and the directory a turn
reads and writes files in. This splits them, and gives each half a layout that
matches how it is used.
This MR was opened once before against a per-session design and withdrawn for
requirement alignment. What lands here is the aligned design: the gateway's
unit of isolation is the **channel**, not the conversation, and per-conversation
storage is the session's own directory under `sessions/`.
**Working directory.** `raven tui` and `raven agent` work in the launch
directory, so the agent operates on the checkout you started it in; its
bookkeeping stays under that directory's `.raven/`. `raven gateway` gives each
channel one directory, set by `channels.<name>.workspace` next to that
channel's credentials (`gateway.web.workspace` for web) and defaulting to
`~/.raven/tmp/<channel>`. The default is derived from agent home rather than
`$HOME`, so `--home` keeps an isolated instance isolated.
**Session storage.** A conversation's transcript and a new metadata directory
now sit together under one group: the slugged launch directory on tui/agent,
the channel name on the gateway. The slug reproduces the scheme Claude Code
uses for `~/.claude/projects/`, transliterated from the shipped implementation
rather than inferred: each non-alphanumeric character becomes one `-` (so `_`
folds too), and past 200 characters the slug is truncated with a hash of the
whole path. Terminal conversations stop piling up under `cli/` and `tui/` with
nothing tying them to the project they were about. The slug is a bucket, not an
identity -- the launch directory is recorded in `Session.metadata`.
**Sub-agent history.** Both ways of delegating now record what they were asked
and what they answered, under `sessions/<group>/<id>/subagents/`. `spawn` wrote
no file at all before - its reply went into the conversation and nowhere else,
so a sub-agent that failed left only a log line. Failed, aborted and cancelled
calls are recorded too, and the prompt is written before dispatch, so a call
that never returns still shows what was asked. DAG run directories move here
from `<workdir>/.ravenx_dag/`.
The mechanism is a per-turn `ContextVar` bound by `AgentLoop.run_turn`.
Components running inside the turn read it; anything that outlives a turn
(sub-agents, DAG runs) captures the directory as data at spawn, marked by an
explicit `follow_binding=False`. That distinction is load-bearing: an
`asyncio.Task` inherits the binding at creation, so a re-read appears to work
and then silently follows the wrong directory once the two diverge.
### Layout
```
~/.raven/workspace/sessions/<group>/
|-- <session_id>.jsonl transcript
`-- <session_id>/subagents/
|-- spawn/<call_id>/ prompt.md, out.md or error.md, meta.json
`-- mas_dag/<run_id>/ graph.json, manifest.json, <node>.*.md
~/.raven/tmp/<channel>/ gateway working directory (default)
<launch dir>/.raven/ tui/agent bookkeeping
```
### Breaking changes
- `--workspace/-w` no longer sets agent home; `--home` takes over that meaning.
A script passing an absolute path to `-w` keeps running but silently shares
the default agent home; one passing a relative path now exits with a
parameter error, because a working directory must be absolute.
- Gateway sessions no longer run in the agent-home root.
- DAG run directories moved; existing `.ravenx_dag/` is neither read nor
migrated.
- A working directory may not be agent home, anything inside its
memory/skills/session subtrees, or any directory containing agent home.
### Defects fixed from the previous round of review
- The DAG read side resolved run directories against agent home while writes
followed the turn binding, so a per-session run was unreadable the moment it
was written: the graph never restored and no node detail ever opened. The
read path is now derived from agent home plus the session key, which reads
correctly between turns when nothing is bound. `raven.subagents.dag.node`
gained the `session_key` it never carried.
- `validate_override` accepted an ancestor of agent home. `~/.raven` is the
instance data directory, and the per-turn checkpoint runs `add -A` over the
working directory, so pointing a session there would have committed
`config.json` and `oauth/` into a shadow git repo.
- Dot-only session-key segments escaped their own root: `safe_filename` leaves
`..` intact, which is fine for `<chat_id>.jsonl` but not for a bare directory
name.
### Defects fixed from the second round of review
- `channels.<name>.workspace` reached the resolver unvalidated, while every
other way of naming a working directory goes through `validate_override`.
Agent home itself, a protected subtree and a relative path were all accepted,
and the per-turn `add -A` would then have run over `user_memory/` and
`sessions/` -- the shape the ancestor check exists to prevent, reachable
through a different door. The field is settable from the web UI's channels
form, and the mount check only refuses an out-of-mount directory when the
executor is sandboxed, which the default backend is not.
- The default channel root is a sibling of agent home, which resolves to the
system `/tmp` when the home sits directly under the filesystem root:
`--home /workspace`, a common container mount, put every channel in a shared,
world-writable, reboot-cleared directory.
- `key_from_path` derived the channel from the parent directory, which under
project grouping is a slugged path no session key can match. The sentinel
producers call it on every file they scan before reading it, so for them that
fallback is the primary path.
- The slug was inferred from three directory names and got repeated separators
and trailing slashes wrong. It is now transliterated from the reference
implementation: replacement is per character rather than per run, and past
200 characters the slug is truncated with a base36 hash of the whole path.
The tests carry the reference algorithm rather than importing ours, so drift
fails them.
- The slug is deliberately still not collision-free (`/srv/a_b` and `/srv/a/b`
produce one segment, in the reference too), so the launch directory is now
recorded in `Session.metadata["project_dir"]` -- the reference solves this
the same way, by writing `cwd` on every transcript entry. Nothing is scoped
by group today, so a collision is currently invisible; the metadata is
written now so it is already there if `--continue` is ever scoped to the
project.
- The sub-agent history directory is append-only with no expiry, no cap and no
reclaim path but deleting the session. DAG runs dominate its volume, because
a node's rendered prompt inlines its dependencies' full output. Now stated in
`CHANGELOG.md`, `CONTEXT.md` and the design doc; bounding it is deliberately
a separate change.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest -q -p no:randomly` on this branch rebased onto `2178707` ->
5 failed, 6034 passed. The same command on `origin/main` at `2178707` in a
separate worktree -> 5 failed, 5898 passed. The two failure sets are
identical test ids: 0 introduced, 0 fixed. Those 5 are environmental or
pre-existing (three `test_channels_qr_*` assert a PNG prefix with no skip
guard for the optional `qrcode` extra, plus a theme test and an onboard
test). GitLab's server-side rebase produced tree `eccdc91c`, byte-identical
to the tree these numbers were measured on.
- `ruff check` over `raven tests scripts` -> clean. `ruff format --check` ->
one file, `tests/test_web_rpc_config.py`, which reproduces on `origin/main`
at `2178707`; it arrived with the everos memory config page and is left for
its author rather than fixed in an unrelated MR.
- `pnpm tsc -b --noEmit --force` in `ui-webui/frontend` -> exit 0.
- `pnpm eslint` on the changed frontend files -> 0 errors, 1 warning
(`react-hooks/exhaustive-deps` in `ChatViewport.tsx`), pre-existing on
`origin/main`.
- `npx vitest run` in `ui-tui` -> 1005 passed; 2 failures (`modelPicker`,
`theme`) reproduce on the baseline and pass in isolation, so they are
suite-order sensitive, not from this branch.
- Each of the three fixed defects was mutation-checked: reverting the fix makes
exactly the new assertions fail and nothing else.
- Manual: the web app was served from an earlier revision of this branch and
driven through real turns; that run is what found the checkpoint defect
already fixed in this branch.
One commit here is a rebase seam rather than this branch's own work:
`test(subagents): pass run_root in the dag test that arrived with the preset
config`. The preset-config change landed on `main` with a test calling
`run_dag` under the old signature, which this branch splits into `workdir` and
`run_root`. Neither side is wrong alone and the rebase is textually clean, so
the break only appears with both on one tree.
- [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
The override validator rejects relative paths, agent home, its
memory/skills/transcript subtrees, and any ancestor of agent home. Under a
sandbox, a directory outside the mount root is refused before it is created
rather than silently escaping. No filename in the history trees is derived from
a sub-agent's output, only from ids raven mints.
Backward compatibility: nothing on disk is migrated. A session whose transcript
predates project grouping keeps its file - `_get_session_path` falls back to an
existing `sessions/*/<id>.jsonl`, so resuming by id still continues the real
transcript instead of opening an empty one beside it. `list_sessions(channel=)`
and `find_most_recent_chat_id` now filter on the session key rather than the
parent directory, which no longer names the channel.
Known cost: each distinct working directory grows its own shadow-git repository
once a checkpoint runs there, and the cache is never evicted. Bounded by the
channel count, not the chat count. Noted in `CONTEXT.md` and the design doc.
Rollback is a revert of this squash commit; there is no configuration switch to
disable the split.
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## Summary
Adds Hermes as a cold-start import source, alongside the existing Claude
Code
scanner, across three kinds of data.
**Memory files.** `MEMORY.md` and `USER.md` are discovered through the
same
profile resolution Hermes itself uses (`HERMES_HOME`, then
`active_profile`
redirecting to `<root>/profiles/<name>`). `USER.md` entries are
additionally
mirrored into the native `user_memory/profile/user.md`: six host
consumers
(Curator, Personalizer, four Sentinel producers) read that file directly
and
never see EverOS-only content. An LLM picks each entry's H2 heading;
every
failure path lands the entry under `## Notes`, which injection always
includes,
so a misclassification costs tokens rather than visibility.
**Conversations.** Sessions are enumerated by shelling out to
`hermes sessions export --dry-run`, whose listing is capped at 100 rows.
The
scanner walks time windows until every session is covered rather than
silently
importing the first 100. Only ended sessions are candidates, and
`reopen_session()` can clear `ended_at`, so the window reconciliation
documents
the resulting race in both directions instead of assuming monotonicity.
**Skills.** Provenance is classified from on-disk evidence -- the
`.bundled_manifest` name-to-md5 map, `.hub/lock.json`, and `.usage.json`
-- with
a `package_hash` byte-identical to Hermes' own `_dir_hash`, so a skill
still
matching its factory content is left alone and only user-authored or
curator-managed skills are copied into the local skill pool. Skills
never travel
as ScanResults, so the menus, the confirm line and the final summary all
state
the skill count explicitly; without it a run that installs 12 of 82
reads as
having dropped 70.
Failure isolation: `scan_all` now reports a failing scanner through an
`on_error` callback and keeps the other platforms' results, and a Hermes
run
whose conversations cannot be enumerated still returns its memory files.
Two pre-existing defects found while working here are fixed in the same
branch:
a multi-line recall hit escaped its bullet in the context segment
renderer, and
a recalled EverOS profile was rendered as a Python repr and left
uncapped.
Also in this branch, from hands-on testing of the finished flow:
- `raven import run` could never reach its interactive path. The
selectors
called questionary's synchronous `ask()` from inside `asyncio.run()`,
and
prompt_toolkit drives `Application.run()` through `asyncio.run()`, which
raises inside a running loop. No test covered it: every case passed
`--platform` and `--tier`, bypassing the selectors.
- Import outcomes now render as one block after the progress display
closes.
Printing them from `_build_and_run` sent them to this module's Console
while
onboard's live progress belongs to its themed Console, and Rich's Live
can
only hold back writes on its own console, so they landed mid-bar and
left the
bar duplicated.
- The `import run` selectors use the shared prompt style and glyphs
instead of
questionary's defaults; onboard's foreground import gains the phase
reporter
it never had, so the multi-second USER.md mirror is no longer silent
behind a
bar reading 100%.
The EverOS backend moves with it. Agent-track recall turned out to be
dead:
agent-track HYBRID fuses `agent_case` and `agent_skill` through a rerank
cross-encoder, and with no rerank provider the server refuses the
request
outright, which `recall` catches and turns into an empty list against a
file-only logger. A live 1.1.3 probe returns `RuntimeError:
owner_type='agent'
with method='hybrid' requires a rerank provider`. The adapter now reads
`capabilities.rerank` from `/health` and asks for the LLM lane only when
the
cross-encoder is genuinely absent -- always sending it would make every
correctly configured user pay an LLM call per recall, never sending it
leaves
the track dead for anyone who skipped the optional rerank role in
onboard.
That capability is only readable from everos 1.2.1, so the pin moves
1.1.3 ->
1.2.1, skipping 1.2.0 (built from a branch missing the 1.1.4 fixes,
including a
knowledge-upload path traversal). Memory endpoints move to `/api/v2`,
canonical
since 1.2.0; `/api/v1` still resolves to the same handlers but is
documented as
a legacy alias. Only everos endpoints move -- the Skill Hub and
OpenRouter
clients have their own v1 surfaces.
That upgrade also broke an assumption Raven was making. "Server running"
and
"server can recall" used to be the same statement; 1.2.1 boots with
`[llm]` alone
instead of aborting, so a misconfigured provider answers 200 and quietly
serves
less. Raven decided a role was configured by reading model + api_key out
of
`everos.toml`, which cannot see that. Capabilities are now read from
`/health` at
all three points where it matters: the memory step (right after the
server it
already starts), `raven doctor` (which had no EverOS check at all), and
`backend.start()` -- the only one of the three on the path every session
takes,
which is where an expired key actually surfaces. It follows the
precedent already
set there for native Windows and prints to stderr rather than a log
nobody reads,
but does not drop to a no-op: writes still land, and `everos cascade
backfill`
gives those rows their vectors once the provider is fixed.
The same reading makes the embedding role genuinely optional. It was not
before:
recall sends no `method`, so it took the server default of HYBRID, which
everos
refuses without an embedding provider -- skipping the role produced a
memory that
stored everything and returned nothing. The adapter now asks for KEYWORD
when no
embedding capability is reported, searching the same rows lexically
instead of
semantically, and that also rules out the rerank fallback because
KEYWORD's agent
path never reaches the cross-encoder. So the wizard stops requiring
embedding and
states what each role buys before asking for it -- llm alone gets
keyword recall,
embedding adds meaning, rerank sharpens ordering -- and skipping
embedding is
reported in colour rather than dim, because skipping rerank costs
ordering while
skipping embedding costs semantic recall entirely.
Fault and degradation are now distinguished rather than lumped together:
only a
missing llm sets doctor's exit code, and `raven doctor` names what each
unconfigured optional role costs, per role, since "optional" alone does
not help
anyone decide. The wizard also stops asking whether to enable memory at
all --
everos is the only backend, so the question framed a choice that does
not exist,
and both of its answers were described wrongly (declining was said to
use "native
Markdown memory", which does not exist: `raven/plugin/memory/` holds
only everos,
and `ContextAssembler.owns_compaction` is a hardcoded True that stops
the
consolidator from ever updating user.md). Backing out is still possible
and now
states the real consequence in colour. The memory LLM field is
pre-filled with
the user's own main model rather than a recommended id, because a
recommendation
is only reachable if their key carries it.
Two rounds of review on this branch found defects worth naming, since
each was
invisible for the same reason -- no test covered the path:
- **Skills were copied before the run's own `Proceed?` gate.** The two
early
returns that install a skills-only import sit above it, so a machine
whose only
importable data is skills had directories copied before being asked
anything.
Both paths now name the count and ask; the wizard's `Start?` gate is
further
down still, so its two call sites ask as well. Every covering test
passed
`--yes`, which is what hid it.
- **A cancelled run still ran both post-phases.** `run_import` returns
normally
once it sees the cancel file, so `raven import stop` halted the
conversation
loop and then started an LLM call per USER.md entry plus a full skill
copy.
- **Org-mirror skills were imported past a gate Hermes applies itself.**
Hermes
token-gates `_org/`: with no `.active_org` marker it prunes the whole
mirror,
and with one it descends only into the named org, so a stale mirror is
content
Hermes no longer loads. Discovery now mirrors that. Excluding `_org`
outright
would have been the opposite error -- it drops the active org's skills.
- **`doctor` and the wizard probed the default address.** Both took
`DEFAULT_EVEROS_BASE_URL` while the backend reads the configured
`base_url`, so
a user who moved everos off port 18791 was told it was not running -- by
the
checks added to make a degraded server visible.
- **An unbuilt multimodal role was reported by nobody.** The
section-to-capability
mapping had an entry both consumers skipped.
- **The USER.md progress line reached 100% before the last call.** Each
report
counted the call about to start; on a measured 9.4s run that left ~3s
sitting at
100%, the exact symptom the phase reporter was added to remove.
- **Registry-name collisions were only checked within one run**, so a
name an
earlier import or the user's own skill already claimed produced the
invisible
skill that `get(name)` never returns.
- **"All platforms" plus "run in background" could not work.** `import
run` has no
all-platforms flag, so the child reached its platform picker with
DEVNULL on
both streams and no terminal, after the wizard reported the import as
started.
It now runs in the foreground and says so.
The e2e tests this branch made dead are fixed too: identity moved to the
host, so
`config={"agent_id": ...}` is ignored, and the agent-track test wrote
under the
services default while querying the tag -- `hits` was empty, its per-hit
assertions vacuous, and an `xfail` absorbed it. The plugin manifest
moves to
1.1.0, which the upgrade SOP in this same diff asks for.
Not in scope: Codex, KimiCode and OpenClaw remain placeholders;
cold-start
import stays an EverOS-only path with no native fallback.
## Type
- [x] Feature
- [ ] Fix
## Verification
```
uv run --all-extras pytest -q 5405 passed, 30 skipped, 13 deselected
uv run ruff check . All checks passed!
uv run ruff format --check . 873 files already formatted
make check-large-files passed
```
Beyond the suite, the importer was run against a real Hermes install at
`--tier full`: memory files, conversations and skills all landed, EverOS
extracted agent cases from the imported conversations
(`quality_score=1.0` in
the server log), and a second run over the same data reported
`Submitted: 0, Skipped: 4`, confirming the checkpointing is idempotent.
The everos upgrade was verified against a live server holding real
imported
data: on 1.1.3 the agent track returns 500 and `/api/v2` returns 404; on
1.2.1
with this change the agent track returns an `agent_case` and the user
track is
unchanged at three episodes. Re-verified after killing the server and
cold
starting it, with the resolved binary printed to confirm which build
answered.
`raven doctor` and the wizard both report llm and embedding available
with
rerank absent against that server.
The suite was also run with HOME pointed at an empty directory, which is
how the
memory-probe and import-step tests were caught reading the developer's
own
configuration instead of their own fixtures. That pass also found the
test suite
waiting out `ensure_everos_server`'s 30s readiness timeout on every
machine
without a running server -- always, on CI -- which cost one file 34 of
its 35
seconds and is now stubbed.
The interactive flow was verified under a pty, comparing the two console
wirings directly, and each new assertion was mutation-tested: every
behavioural
change on this branch had its fix reverted and the covering test
confirmed red,
and only that test. Where a fix had a plausible wrong shape, that shape
was
mutated too -- excluding `_org` wholesale rather than token-gating it,
reporting
progress after the await instead of before, seeding the registry-name
check from
the pool without ordering it after the target resolution. Two of those
mutations
survived and were the more useful result: one showed a guard clause
could not
fire (`_target_for` only ever returns a path that does not exist, so
excluding it
from the pool lookup was dead code, now removed), the other showed the
wizard's
own confirmation sits below the returns it was supposed to cover.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
User-facing docs are unchanged: this adds a platform to an existing
documented
command rather than a new surface. The developer docs move with the code
--
`docs/memory-plugin-architecture.md` (the everos pin, and the upgrade
SOP now
stating that a one-way migration belongs in the release notes) and
`scripts/README.md` (two deleted scripts).
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The import writes to EverOS and to `user_memory/profile/user.md`, and
copies
skill directories into the local skill pool. EverOS has no delete
endpoint, so
an unwanted import is not undone by reverting this branch; the skill
copies and
the profile edits are plain files and can be removed by hand. Import
state
lives in `~/.raven/import_state.json` and can be deleted to start over.
Behaviour changes for existing users: the onboard wizard's import step
and
`raven import run` both look different (shared prompt style, skill
counts,
one summary block). `raven import run`'s interactive path changes from
"crashes immediately" to working. Rolling back restores the crash.
Three more, from the review round: a skills-only import now asks before
copying
(one extra prompt, skippable with `--yes`), an all-platforms import
chosen with
"run in background" runs in the foreground instead and says so, and
skills under
a stale `_org/` mirror are no longer imported -- Hermes does not load
them
either, but anyone who had them imported by an earlier build keeps them,
since
nothing here deletes.
Two consequences of the everos upgrade that operators need to know:
- **The index migration is one-way.** everos 1.2.1 migrates the LanceDB
schema
on first start and prunes older manifest versions, so once a machine has
run
this, its memory index can no longer be read by an older everos.
Reverting
the branch does not undo it.
- **A missing provider no longer aborts startup.** 1.2.1 boots with
`[llm]`
alone. A misconfigured embedding provider used to fail loudly; it now
degrades
to keyword search, and rows written in that state carry no vector until
`everos cascade backfill` is run. everos itself only logs one warning
line,
which is why the wizard, `raven doctor` and `backend.start()` all
surface it --
the last of those runs every session, so an expired key is reported
rather
than discovered.
- **Behaviour change for users who skip embedding.** Recall degrades to
keyword
matching instead of failing, and the wizard no longer stops them from
getting
there. That is the point of the change, but it means a user can now end
up with
a working memory that is measurably worse at recall than the previous
all-or-nothing setup would have allowed.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
File-based USER/PROJECT plugins ship their factory module inside the
plugin directory (~/.raven/plugins/<id>/), which nothing put on
sys.path. Discovery found the manifest but _resolve_factory's bare
importlib.import_module always failed — a self-contained plugin dropped
into the user dir could never load.
activate() now threads each DiscoveredPlugin's source and location into
_activate_one, which calls _ensure_importable before resolving
factories: for USER/PROJECT plugins it appends (not prepends, so
installed packages keep priority) the plugin directory to sys.path,
guarded for idempotency. BUNDLED (in-package) and ENTRY_POINTS
(installed) are untouched.
Add regression tests that write real on-disk factory packages (not
pre-seeded into sys.modules) under user/project dirs and assert the
backend/tool build end to end.
## Summary
<!-- What changed, and why? -->
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
<!-- List the exact commands you ran and the result. -->
- [ ] Relevant tests pass locally
- [ ] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- [ ] Security impact considered
- [ ] Backward compatibility considered
- [ ] Rollback path is clear for risky changes
Co-authored-by: libin.zhang <libin.zhang@shanda.com>
## Summary
Two focused lint cleanups off the whole-repo lint convention:
**Python (ruff N818)** — rename exception classes to the `*Error` suffix
so
they satisfy the N818 naming rule, and update every reference:
`_SocketClosed`, `MultimodalUnavailable`, `PluginConflict`,
`PluginNotFound`.
Pre-stable rename with no external consumers. The matching N818
per-file-ignores
are dropped from `pyproject.toml`; the CONTEXT glossary entry and the
registry
diagram are updated in step.
**TypeScript (eslint no-explicit-any, ui-tui)** — remove `any` from the
code and
ratchet the rule to error:
- Replace `any` in 6 rpc/config generic signatures with
`unknown`/`object`. The
default type stays the record shape; the generic constraint loosens to
`object` so concrete response interfaces satisfy it without an index
signature (and `object` is not `any`, so type safety holds).
- Remove dead shift/ctrl click-modifier branches in `thinking.tsx`: the
hermes-ink `ClickEvent` never carries modifier keys, so those branches
were
unreachable (confirmed by tracing the click pipeline); drop them and the
now-unused expand-all helpers.
- Ratchet `@typescript-eslint/no-explicit-any` to error, scoped to the
ui-tui
config layer; test files stay exempt.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [x] Refactor
- [ ] Other
## Verification
Run from the branch (rebased on latest `main`):
- `uv run ruff check .` — All checks passed.
- `uv run pytest tests/test_plugin_registry.py
tests/test_plugin_bootstrap.py tests/test_plugin_tools.py` — 43 passed.
- `npm run type-check` (ui-tui) — 0 errors.
- `npm run lint` (ui-tui) — 0 errors; no-explicit-any is now error with
0 violations.
- `npm test` (ui-tui) — 868 passed, 16 skipped, 0 failed.
- Full Python suite: no regressions vs the `main` baseline (the
remaining
failures are environment-only: an optional native dep not importable in
the
worktree venv, plus TTY/subprocess e2e that need a real terminal).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
The exception renames are a source-visible API change, but the project
is
pre-stable and the renamed exceptions have no external consumers. The
TypeScript
changes are behavior-preserving; the removed click-modifier branches
were proven
unreachable.
## Related Issues
N/A
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>
## Change description
> Whole-repo lint + pre-commit convention, CONFIG ONLY (no source
reformat in this PR). Python (ruff) and TypeScript (eslint + prettier)
share a 120-col margin via the committed pre-commit gate. This upgrades
main's existing basic ruff setup and adds the TS lint stack (none
existed on main).
>
> What this PR adds:
> - ruff: line-length 120; security rules
S101/S105/S106/S107/S506/S605/S607; policy per-file-ignores (tests +
accepted CLI deferred-imports + product asserts + N818, each commented);
ruff pinned <0.16.
> - eslint/prettier: shared base (`eslint.base.mjs` +
`prettier.config.mjs`); ui-tui extends it with React rules, bridge with
a Node-only config; hermes-ink vendor and generated RPC types excluded.
> - pre-commit: keeps main's hooks (conventional-commit,
detect-private-key, etc.), adds a top-level exclude and 4 local
eslint/prettier hooks; bumps the pre-commit dev dep.
> - 2 lint-surfaced fixes: PlannerContext import (F821) in the sentinel
runner; lower-cased file-local cron-heartbeat constants (N806).
(raven/config/raven.py's F821 was already fixed on main.)
>
> Sequencing: config only. `ruff check` is intentionally red on ~307
auto-fixables (I001/F401/F541/E701/E702); a SEPARATE reformat branch
runs `ruff --fix` + `ruff format` + eslint/prettier --fix to clear them
(100% auto-resolvable, zero manual). Enforcement (pre-commit install /
CI) turns on only after the reformat lands, so do not expect a green
tree from this PR alone.
>
> CLI-owned files (the reformat and several per-file-ignores touch
`raven/cli/*`) are under review by the CLI team. Judgment items (TS
no-explicit-any, no-unused-expressions, S101 convert-vs-keep, N818
rename, C90, mypy) are deferred to v2.
## Type of change
- [ ] Bug fix
- [x] New feature
- [ ] Document
- [x] Others
## Related issues (if there is)
> none
## Checklists
### Development
- [ ] Lint rules pass locally
- [ ] Application changes have been tested thoroughly
- [ ] Automated tests covering modified code pass
> config-only: `ruff check` is red on auto-fixables by design (the
reformat branch clears them); eslint/prettier configs load in both
ui-tui and bridge.
### Security
- [x] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines
> Only dependency change is the dev-only pre-commit tool plus the ruff
pin; the detect-private-key hook from main is retained.
### Code review
- [x] Pull request has a descriptive title and context useful to a
reviewer
- [ ] Pull request linked to JIRA ticket when applicable
---------
Co-authored-by: Sheng Zhao <sheng.zhao@evermind.ai>
Co-authored-by: Claude (claude-opus-4-8) <noreply@anthropic.com>