30 Commits

Author SHA1 Message Date
zhanghui
2b3cce70fa
feat(*): upgrade everos to 1.4.1, lift the windows gate, guard the embedding width (#791)
## Summary

EverOS 1.4.0 runs natively on Windows and 1.4.1 pins `openai` below 3,
so the memory plugin's exact pin moves from `everos[multimodal]==1.2.3`
to `==1.4.1`. The lock follows: `pyarrow` 24.0.0 -> 25.0.1 (EverOS's new
floor), `everalgo-boundary` 0.2.0 -> 0.2.1, `everalgo-core` 0.4.0 ->
0.3.0 (EverOS now pins its everalgo layer with `==`), and `msvc-runtime`
on `win32` only. `lancedb` stays at 0.34.0. Every internal everos symbol
the adapter reaches is present in 1.4.1 with the same signature, so the
adapter itself is unchanged. The plugin manifest and package version
move to 1.4.0.

**The Windows gate is gone.** `everos_platform_note` (#737) and its five
call sites, `ServiceState.UNSUPPORTED`, the import.scan refusal (#750),
the wizard's WSL notice and its zh catalogue line are removed;
`_everos_executable` looks for `everos.exe` on `win32`. Spawning,
probing and reusing the server were already portable. Identifying and
stopping a stale server was not: `_cmdline_of` asked `ps`, and the
marker `everos server start` never matched a Windows command line
(`...\Scripts\everos.exe server start`). The command line now comes from
WMI through PowerShell on `win32` and the marker accepts both shapes;
`_listening_port` asks the TCP table through PowerShell there, walking
the launcher's descendants: the socket belongs to the base interpreter
two launchers below `everos.exe`. The server is spawned in a process
group of its own (the Windows counterpart of `start_new_session`, which
also keeps a Ctrl-C at the gateway off it) and stopped with Ctrl-Break,
which uvicorn takes as a shutdown; one that ignores it for ten seconds,
or one no group can be addressed to, gets `TerminateProcess` as before.
And because Windows cannot replace a running executable, the upgrade
helper stops whatever still runs from under the tool environment before
it installs (the server outlives the gateway by design); without that,
`uv` failed on `Scripts\everos.exe` with os error 32. Recorded in
`docs/memory-plugin-architecture.md` section 7.4.

**Two guards, found while verifying against a copy of a real 1.2.x
store:**

- `set_embedding_endpoint` measures the model's vector width before
writing the pin and refuses anything narrower than the 1024-wide memory
index (`REQUIRED_EMBEDDING_DIMENSIONS`), but only where an EverOS
backend will read the pin: the `everos-memory` distribution is installed
and the config names `everos` as the memory backend (an absent key is
the schema default; an explicit `null` or another backend is not gated,
and a knowledge base sizes itself to whatever width the model returns).
The wizard's own check imports the same constant and probe. A
768-dimension model pinned through the settings page had left every
memory store and search answering 500 about a mismatched width, with
nothing on the page saying why. A probe that cannot reach the provider
is not a verdict: the pin is written and a warning logged. The two RPC
writers run the (now network-touching) writer in a thread.
- `ensure_everos_server` reads the running server's `/health` version
and, for a root raven owns, sends a mismatch with the installed everos
through the same precheck / stop / spawn chain a rotated credential
takes (`stale_reason`). Raven used to reuse whatever answered on the
port, so an upgrade left the old server serving until something
unrelated restarted it. A root the user manages is never touched.

**The wire contract is pinned.** Every request body the plugin and the
memory page send (`/add` with a tool exchange, `/flush`, the four
`/search` shapes, the four `/get` kinds) is validated against everos
1.4.1's own request models in `TestRequestBodiesMatchEverosModels`, so a
schema move on the next upgrade fails in the suite rather than as a 422
in a gateway log.

**A six-angle review then hardened the degraded paths** (turn survival
under every EverOS failure, Windows lifecycle, upgrade paths, the
embedding guard, the wire contract, concurrency). The rule: memory
degrades with a notice and never blocks a turn, a start or an upgrade.

- A gateway starts the server again when it finds nothing listening (or
a probe that timed out) and nothing holding the OME lock: only for a
root raven owns, never over a child of its own, at most once per thirty
seconds. The only spawn used to be in `start()`, so a server that went
away left a running gateway without memory until restarted by hand. A
stop that was sent and did not finish is not adopted (uvicorn closes the
port at once and finishes what it had), so the version-mismatch restart
after an upgrade cannot leave the gateway on a dying server.
- A command-line lookup that failed (no `ps`, PowerShell blocked, WMI
wedged, timeout) is distinct from a process that is gone: the stop keeps
waiting, the lock names nothing, and a settings save over a server that
answers but cannot be identified is reported as not applied. A losing
spawn no longer overwrites the live server's pidfile. `stop_pid` counts
wall time and takes a grace; on Windows a backend drains the server it
started at `stop()`.
- The upgrade helper asks again after `Stop-Process` and refuses to run
`uv` while anything from the environment survives (an elevated or
another user's process): `--force` removes the environment before
writing and would have left every file but the one that could not go.
- An embedding pin narrower than the index is measured at backend start
(once per pin per process) and withheld from the spawn: EverOS runs
keyword recall and keeps storing, and the notice names the model and
width. This covers a pin written around the write-time check (before
memory was on, unreachable at save time, edited by hand). The probe no
longer raises on an odd response, times out at ten seconds, honours
`plugins.disabled`; `migrate_roles` runs off the event loop it had put a
provider round-trip onto.
- The memory page uses the `/api/v2` routes (v1 is EverOS's legacy
alias), asks `/health` before a search the way the chat adapter does,
and shows the server's own sentence on a refusal. The recalled profile
is rendered as lines rather than a `namespace(...)` repr with its
evidence fields; a tool-call-only row stores empty content, not
`"None"`; `top_k` stays within 1..100; an empty query asks nothing; a
failed capability probe is not cached. The wizard accepts a model wider
than 1024 (EverOS keeps the first 1024, as the settings page already
allowed) and re-prompts on the host's refusal instead of a traceback.

`docs/memory-plugin-architecture.md` section 7 records the upgrade (7.4)
the way 7.3 recorded 1.2.1 -> 1.2.3.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Unit and RPC tests over every touched area:

```
env -u SERPER_API_KEY uv run --frozen --python 3.12 --extra dev pytest -q tests/test_everos_server.py tests/test_everos_backend.py tests/test_cli_onboard_commands.py tests/test_everos_discover.py tests/test_rpc_settings.py tests/test_everos_config.py tests/test_everos_plugin_discovery.py tests/test_cli_plugin_commands.py tests/test_core_plugin_stack.py tests/test_rpc_memory.py tests/test_rpc_import_sync.py tests/test_everos_http_adapter.py tests/test_memory_backend_protocol.py tests/test_memory_backend_contract.py tests/test_plugin_boundary.py tests/test_i18n_boundary.py tests/test_config_update*.py
# 1312 passed, 1 skipped (inotify is Linux-only) on the first commit; 960 passed after the review round; full suite 26214 passed, 2 failed, 120 skipped, the 2 failing on an untouched github/main checkout too (LibreOffice path, background child env)
uv run --frozen --python 3.12 --extra dev ruff check <changed files>   # All checks passed!
uv run --frozen --python 3.12 --extra dev ruff format --check <changed files>   # 20 files already formatted
```

Against a 46 MB copy of a store written by everos 1.2.x (568 episodes,
5528 atomic facts, seven LanceDB tables), never touching the live one:

- `everos server start` on 1.4.1 opens it with no schema complaint;
`/health` reports `version 1.4.1`, `cascade.healthy true`.
- The same four `/api/v2/memory/search` requests on 1.2.3 and 1.4.1
return the same ids in the same order; BM25 scores drift in the third
decimal place.
- `raven agent -m` on this branch spawns everos 1.4.1, a "remember this"
turn lands in `episodes/episode-2026-09-24.md` and `.atomic_facts/`, a
fresh one-shot session recalls it, and a third session recalls episodes
written under 1.2.x months earlier.
- With a 1.2.3 server left on the port, the next `raven agent -m` logs
`runs everos 1.2.3 while this raven installs 1.4.1; restarting`, the old
pid exits and `/health` reports 1.4.1. The 1.2.3 server had opened the
index 1.4.1 wrote with no complaint.
- Windows 11 box, this branch checked out and synced: `raven serve`
spawns `everos.exe` natively, the Memory page shows its four tabs
instead of the platform sentence, a chat turn lands as an episode
(`/add` 200, `/flush` 200, cascade `upserted=1`), and after a memory
role change the next start logs `holds credentials raven has since
changed; restarting`, the old everos pid exits and the new one answers
`/health` 1.4.1.
- The settings page refuses `BAAI/bge-base-en-v1.5` on deepinfra with
`returns 768-dimension vectors and the memory index is 1024 wide` (real
probe), and the pin stays unchanged.
- Adapter import smoke against 1.4.1: all 13 internal symbols present,
signatures unchanged.
- Windows 11 box, second round: with the server up, `uv pip install
--reinstall --no-deps everos==1.4.1` fails on `Scripts\everos.exe` (os
error 32, exit 2); after the helper's sweep (`Stopped what was still
running from the old install (pid ...)`) the same command succeeds and
the relaunched gateway spawns a fresh 1.4.1. A stop from the spawning
console runs the full uvicorn shutdown (`Shutting down` ... `Finished
server process`) in 3 s; a stop from another console falls back and the
process is gone in 2 s. `lock_holder(root).port` reads 18997 (launcher
-> venv python -> base python).
- `tests/test_everos_server.py tests/test_updates_upgrade.py`: 261
passed, 1 skipped; `tests/test_everos_backend.py -k RequestBodies`: 7
passed.
- Review round (`env -u SERPER_API_KEY uv run --frozen --python 3.12
--extra dev pytest` over the everos, config, settings, memory page,
import, onboard, plugin-stack, boundary, cycle-budget and contract
files): 1225 passed, 1 skipped; `test_everos_server.py` 124,
`test_everos_backend.py` 188.
- Windows 11 box, review round: with the gateway serving, the everos
launcher was terminated by hand (`Stop-Process`, nothing on 18997); the
next turn answered without memory (`recall failed ...
state=unresponsive`), and six seconds after it began the gateway logged
`started everos server` / `everos server ready`, the pidfile named the
new pid and `/health` answered 1.4.1. The first attempt did not fire
because a dead port there takes 2-4 s to be refused, longer than the 1 s
probe; the respawn now fires on a timed-out probe as well, guarded by
the lock holder. The memory page's four counts and a search on the Cases
tab went through the v2 routes.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- Windows installs that used to read "long-term memory is not available
on Windows yet" now spawn EverOS, and a stale server is identified and
replaced there too. The stop there is Ctrl-Break with a ten-second
fallback to `TerminateProcess`. An upgrade on Windows first stops every
process whose executable lives under the tool environment: raven's own
gateway, sub-agents and server, nothing outside that directory.
- An embedding pin narrower than 1024 dimensions is refused at the
settings page and the wizard, with the width in the message, only for an
install whose memory runs on EverOS (plugin installed, backend `everos`
or the default). Knowledge-only installs, memory off, and other backends
keep any width. Existing pins are not touched.
- An owned EverOS server whose version differs from the installed
package is restarted on the next session start. A root the user manages
is never restarted.
- A gateway may now start an EverOS server on its own when its probe
finds nothing listening and nothing holding the lock (owned roots only,
at most every thirty seconds). On Windows a backend stops the server it
started when it shuts down (Ctrl-Break, sixty seconds to drain), so a
settings change or an upgrade there restarts the server rather than
leaving it. An upgrade on Windows refuses to proceed while a process
from the tool environment cannot be stopped, and says which pid.
- An embedding pin narrower than 1024 that reached the config around the
settings check is no longer handed to EverOS: recall runs on keywords
with a notice naming the model, until a 1024-dimension model is pinned.
- Rollback: revert the commit and `uv sync`. `lancedb` did not move, so
an index written by 1.4.1 opens under 1.2.3 (exercised on the copy).

- [x] Security impact considered
- [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-fable-5-1) <noreply@anthropic.com>
2026-09-25 19:33:18 +08:00
Zuyi Zhou
34ed138cc7
fix(plugins): a plugin that fails to load no longer takes every other plugin with it (#703)
## 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>
2026-09-23 22:41:21 +08:00
zhanghui
93e1e1f027
fix(*): say long-term memory is not on Windows yet instead of reporting it unreachable (#737)
## Summary

On native Windows, EverOS cannot run: it is spawned, found and stopped
through POSIX tooling. Today a Windows install gets the worst possible
reading of that fact. The memory page shows four zeros, "everos
unreachable" and a retry button that cannot help, and changing a memory
model on the settings page runs a restart chain that can only fail.
Support is coming; until it lands, Raven should say so in one sentence
and stop trying.

One sentence in one place, `everos_platform_note()` in
`raven/core/plugin_stack.py` (beside the existing
`everos_plugin_missing_note()`), returns the note on `win32` and `None`
everywhere else. Three surfaces ask it first:

- `memory.stats` / `memory.list`: the page renders the answer as its
existing `note`, so the frontend needs no change.
- `precheck_spawn()` in the EverOS plugin: the settings-page restart
chain reads it before stopping anything and reports it through the
`memory.health` banner the page already shows.
- `EverosBackend.start()`: the session notice already gated Windows with
wording of its own; it now says the same sentence.

A second commit closes what the first left open, found by a real turn on
the shimmed gateway and by self-review:

- `EverosBackend.start()` used to leave `_state` at `UNKNOWN` on Windows
(before this PR too), so every turn's memory write came back as a failed
write: the host retried it for 52 seconds, logged `backend.store gave up
on a turn`, and after three turns raised the memory banner over a
service that was never going to exist. A new terminal
`ServiceState.UNSUPPORTED`, in both `_TERMINAL_STATES` and
`_NO_MEMORY_TO_LOSE`, makes the write a no-op and stops the probes.
- `EverosBackend.health()` said `server: not running (starts on demand)`
on Windows, which is false there; the importer's refusal and `raven
doctor` now carry the platform sentence instead.
- `_unavailable_note()` asked the platform before the configured
backend, so a Windows install whose memory runs on mem0 would have been
told it has no long-term memory. The sentence is now returned only where
the page would otherwise send the reader to EverOS.

Frontend untouched. Removing the gate when Windows support lands is
deleting the one function, its call sites and the `UNSUPPORTED` member.

## 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

```
uv run --frozen --python 3.12 --extra dev pytest tests/test_everos_backend.py tests/test_rpc_memory.py tests/test_everos_server.py tests/test_core_plugin_stack.py tests/test_plugin_boundary.py tests/test_rpc_import_sync.py tests/test_everos_backend_contract.py tests/test_memory_backend_contract.py tests/test_rpc_settings.py -q
# 485 passed, 1 skipped (the pre-existing Linux-only inotify case)
uv run --frozen ruff check <the 7 changed files> && uv run --frozen ruff format --check <the 7 changed files>
# All checks passed! / 7 files already formatted
uv run --frozen python scripts/check_source_language.py github/main
# exit 0
```

Reverse checks: with the platform test in `everos_platform_note()`
replaced by an unconditional `None`, the first three new cases fail (3
failed in 1.36s). With the `UNSUPPORTED` assignment, the `health()`
short-circuit and the note reorder removed, four of the five later cases
fail, and re-introducing the platform-first order fails the fifth (the
mem0 case). Every file was restored byte for byte.

Real-host check on macOS (no Windows machine was available): three
isolated `raven serve` instances, each with its own `RAVEN_HOME` and an
EverOS address pointing at an unused port, driven with playwright-cli. A
`sitecustomize.py` made `sys.platform` read `win32` only for the gate
file (and, for the baseline, the plugin's `backend.py`); every other
reader kept the real value.

- Baseline (GitHub `main` + shim): memory section shows four zeros,
"everos unreachable: All connection attempts failed" and a retry button;
gateway log has four `memory.stats: ... unavailable` warnings.
- This branch + shim: memory section shows the one-sentence note;
`memory.stats` logs the same sentence; no EverOS process appears.
Picking a different memory model writes the config and logs `everos
restart ... end: precheck refused, server left running`; the transcript
banner carries the sentence.
- This branch, no shim (macOS control): EverOS starts normally (`everos
server ready`), the page shows the empty store.
- This branch + shim, one real turn through the page (DeepSeek V4 Pro):
the reply arrives; the gateway log carries no `backend.store gave up`
line and no `memory.health` alarm 90 seconds later. The same turn
against main's own Windows gate (which leaves the state at `UNKNOWN`, as
the first commit still did) logged `backend.store gave up on a turn ...
after 5 attempts` 52 seconds after the reply.

Not verified: whether the `everos` package installs and `raven` starts
on a real Windows machine.

## Risk

- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

User-visible only on native Windows: the memory section and the
settings-save banner show the sentence instead of an unreachable-server
error, and no EverOS spawn is attempted from the settings page. No
change on macOS or Linux. Rollback: revert the commit.

## Related Issues

N/A

---------

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-23 21:40:20 +08:00
zhanghui
c9ea7c570c
fix(core): the memory service stops holding up the first session (#630)
## Summary

Two changes against the same symptom: the first session after an install
waits
on the memory service and then runs without long-term memory anyway.

**The wait is unnecessary.** A resident host awaited `backend.start()`
at boot,
so it held for the readiness budget -- 10s -- before serving anything.
The
backend already has a state machine for exactly that window: `store`
answers
False so the loop retries the record, and `recall` returns no hits for
that turn
and schedules a probe. Waiting for the service before serving the first
turn is
what the state machine replaced everywhere else.

`plugin_stack.start_backend_detached` is the same shape as
`warm_up_in_background` for litellm: a resident process starts the slow
thing
once and goes on serving, and the on-demand path reports a failure to
whoever
needs it. Three callers take it -- the gateway at boot and at a
generation swap,
and `raven a2a serve`. The other three keep awaiting, because for them
there is
no later turn to recover into: an import checks readiness immediately, a
sub-agent writes one record, and a one-shot turn exits. It is retired in
`Runtime.dispose`, the single point both resident hosts go through.

**The wait was also far longer than its budget.** uv does not compile
bytecode
by default, so the first process to import a module compiles it, and for
raven
that process is the EverOS service the first session starts. Measured on
a fresh
isolated install: 22s from spawn to ready, of which 18s elapses before
the
service writes its first log line. `UV_COMPILE_BYTECODE=1` in the
installer
moves that into the install, where the user is already watching a
progress line.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Measured on a throwaway install in an isolated `RAVEN_HOME` /
`UV_TOOL_DIR` /
`UV_TOOL_BIN_DIR`, built from this checkout:

- cold first start, as shipped today: 22s spawn to ready (readiness
budget 10s)
- second start against the same tree: 2.2s
- freshly scaffolded root, bytecode already compiled: 2.1s
- byte-compiling the rest of that tree: 13.9s for 16756 files, single
threaded,
  so the cost is compilation and it is paid once per machine

The detached start was read at the layer that owns the ordering, the
gateway's
own log. Before this change `Page:` cannot appear until after
`everos server ready`; after it:

```
17  EverosBackend.start
20  Page: http://127.0.0.1:18894
28  started everos server
31  everos server ready
```

The page is serving at line 20 and the child is only spawned at line 28.
The
interval this removes from the boot measured 5.5s on a machine whose
bytecode is
already compiled.

Commands:

- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_core_plugin_stack.py tests/test_core_runtime_swap.py
tests/test_cli_gateway_commands.py tests/test_cli_a2a_commands.py
tests/test_cli_import_commands.py tests/test_memory_backend_protocol.py
-q` -- 191 passed after the rebase onto main
- the same set plus `tests/test_everos_backend.py` and
`tests/test_core_runtime_eval_hooks.py` -- 364 passed
- `ruff check raven/ tests/` -- all checks passed
- `ruff format --check raven/ tests/` -- 1654 files already formatted
- `sh -n install.sh` -- clean

Each of the six new cases was mutated to confirm it can fail: dropping
the task
reference, dropping the done-callback, making the cancel a no-op, and
removing
the cancel from `dispose`. Every mutation turned the case that names
that
behaviour red, and the source was restored and hash-compared afterwards.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible change: a resident host now serves its first turn before
the memory
service has answered. A turn that arrives in that window gets no recall,
and its
record is retried rather than lost. Previously the host waited and, when
the wait
overran, that session had no memory at all -- so the window is narrower
than what
it replaces, not wider.

The installer now compiles bytecode, which makes an install slower by
roughly the
compile time and larger by the `.pyc` tree.

Rollback: both commits are independent and revert cleanly. Reverting the
first
restores the awaited start; reverting the second restores the uncompiled
install.

- [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>
2026-09-22 15:46:12 +08:00
zhanghui
e70a868e9c
refactor(*): seal the memory backend seam so a memory plugin needs no host edits (#414)
## 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>
2026-09-16 22:19:50 +08:00
0xKT
632562895a feat(ui-tui): tool cards open themselves, the strip marks here, ticker words split
## Summary

Three reader-facing changes to the TUI transcript and the instance strip.

**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.

The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.

Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.

**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.

**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.

`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on a worktree at this branch's tip, against the current main tip:

- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0

No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Three user-visible changes, all inside the terminal UI:

- a tool call that returned something now opens to a capped preview instead of
  staying shut. A reader who prefers it shut clicks once, and that decision
  holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
  has one column less for its name.
- the status ticker shows a different set of glyphs and words.

No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 12:42:09 +00:00
ethanwwwwwwww
c3822b77d2 feat(ui-tui): tool cards open themselves, the strip marks here, ticker words split
## Summary

Three reader-facing changes to the TUI transcript and the instance strip.

**A settled tool call opens itself.** A tool card had two states, shut and
full, and neither is what a reader wants by default: shut hides the result
that was the point of the call, full spends a thousand rows on a result five
rows would have answered. There are now three levels - shut, a preview capped
at `TOOL_PREVIEW_ROWS` result rows with a `+N` row standing for the
remainder, and full at `TOOL_FULL_ROWS`. The cap is what bounds the cost, so
a call that came back opens unasked and only a call that returned nothing
stays shut, its block being the argument the row above already shows. A
reader's own decision always wins over that default.

The `+N` row becomes its own two-way control: it reveals the rest, then folds
back to the cap, where the block's own click shuts the card outright. It used
to ride inside the output array, which made the one row announcing there was
more to see the row that collapsed the card.

Fold state moves out of the component that draws it into a store keyed by
tool call id. Held in the row's component state, a row that changed - a step
landing in a turn still running - unmounted and took the reader's decision
with it, so a card opened seconds ago closed itself. `useMainApp` now reads
that store when it measures: a resize drops every measured height because the
cache buckets on columns, so without the folds there, rows below the fold came
back at their default height and the transcript scrolled to the wrong place.

**The strip marks the row whose conversation is on screen.** The composer's
top border names the instance being typed to, and the strip listed every
instance without saying which of them that was. The active row now carries a
gutter bar in the strip's own leftmost column, where nothing else draws, so
the bar reads as a position and the bullet beside it goes on saying status
alone. The active row is exempt from every cap, and a line no click can switch
to - a graph line, a loose spawn - never carries it. An interrupted turn also
refreshes the instance registry now: `message.complete` already did, but the
manager moves the row on this path too, writing `cancelled` or `failed`, so
without the re-read an interrupted instance went on showing a filled bullet
while its view went on polling a turn that had ended.

**The censored ticker vocabulary splits from Raven's own.** Wrapped agents
render their status as a kaomoji plus a verb, some of it on the channel the
reasoning arrives on, and `cleanThinkingText` strips exactly that pair - but
it was reading its strip list off Raven's own `FACES` and `VERBS`. That made
the two one list, so a branding change silently changed what gets censored out
of a model's reasoning: rename a verb and the old word stops being stripped,
adopt a word another agent uses and Raven's own ticker starts eating itself.
`tickerNoise.ts` now holds that vocabulary, frozen and deliberately separate;
it describes other agents' output and changes only when one of them does.

`FACES` and `VERBS` are then free to move, and they move here: the kaomoji
become one bird wearing different expressions, and the verbs are ordered as
one round of work rather than by how close the words are in meaning, because
at one word every 2.5s a reader sees most of the list in a single turn. Each
emoji frame is a single code point on purpose - a ZWJ sequence or a variation
selector renders as two glyphs on terminals that do not compose it, which
shifts everything right of the ticker.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Run on a worktree at this branch's tip, against the current main tip:

- `npx vitest run` (ui-tui): 141 files, 2052 tests passed
- `npx tsc --noEmit -p tsconfig.json` (ui-tui): exit 0, no output
- `make check-source-language COMMIT_RANGE=origin/main..HEAD`: exit 0
- `make check-large-files COMMIT_RANGE=origin/main..HEAD`: exit 0

No Python source is touched, so no pytest selection applies. `ui-tui/CONTEXT.md`
is updated for the fold levels and the gutter bar; the tool-card work carries
its design note under `docs/plans/`.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Three user-visible changes, all inside the terminal UI:

- a tool call that returned something now opens to a capped preview instead of
  staying shut. A reader who prefers it shut clicks once, and that decision
  holds for the life of the call.
- the instance strip spends one leading column on the gutter bar, so every row
  has one column less for its name.
- the status ticker shows a different set of glyphs and words.

No RPC schema, config or on-disk format changes. Fold state lives in memory
and per transcript view, so nothing persists across a restart and there is
nothing to migrate. The split strip list only widens what is removed from
displayed reasoning text; it reads no new input and grants no new capability.
Rollback is a revert of the squash commit.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 12:42:08 +00:00
0xKT
6ff5cacdcf docs(memory_engine): the node brief carries the owner's scope as written
## What

Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.

## Why

On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:

- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
  from three classes outside the falsified list" (the falsified list named 18 specific
  hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".

The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.

## The three rules

1. The owner's words and scope go into every node's brief as written; the orchestrator's
   own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
   *not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.

## Checks

- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
  `tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
  144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
  identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
  adds later in the same file.
2026-09-10 12:39:43 +00:00
silverLXT
d28bb96163 docs(memory_engine): the node brief carries the owner's scope as written
## What

Adds one section to the DAG orchestration skill, `Write the brief as the owner gave it`,
placed after `When to use`. Docs only; no code, no schema, no node fields.

## Why

On the 2026-09-08 autoresearch run the orchestrator's briefs narrowed the search without
anyone deciding to narrow it:

- the owner allowed "training configuration, data mix, architecture, algorithm";
- the round-one brief added "the hyperparameters are exhausted, so gains can only come
  from three classes outside the falsified list" (the falsified list named 18 specific
  hyperparameter groups; batch size was not among them);
- the round-two brief to the experiment runner opened with "you change no case".

The runner changed no training setting in 26 scored runs. Tokens per step alone was worth
0.059 of the 0.072 gap to the best known result on the same task, and was never tried.

## The three rules

1. The owner's words and scope go into every node's brief as written; the orchestrator's
   own steer is marked as a suggestion, never as "gains can only come from".
2. A list of tried settings stays a list. Pass it as is and ask the node to check what is
   *not* on it before it picks directions.
3. Each role's brief states the whole of its role every round, not this round's chores.

## Checks

- `tests/test_segments.py`, `tests/test_skill_forge_loader_parity.py`,
  `tests/test_agent_loop_injected_skill_ids.py`, `tests/test_curator_context_engine.py`:
  144 passed. The one failure (`raven_everos` not installed in a fresh venv) fails
  identically on unmodified main.
- The section sits before `How it works`, so it does not overlap the two sections !573
  adds later in the same file.
2026-09-10 12:39:43 +00:00
0xKT
baac0a6c0f feat(ui-web): ask an agent whether it works, from its card
## Summary

The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.

It comes back as a section of the card, not a third verb on the row:

- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.

No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.

**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:

- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.

This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.

**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)

**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.

**Checked and deliberately not changed, for the reviewer:**

- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:

- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.

```
npm run test --prefix ui-web    101 files, 1550 passed
npm run test --prefix ui-tui    141 files, 2017 passed, 13 skipped
npm run gen:check  --prefix ui-web    generated client matches the contract (162 methods)
npm run type-check --prefix ui-web    clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui    23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py    pass over the branch
make build-ui                                          dist rebuilt and served
```

The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)

## Risk

User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.

- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 10:00:46 +00:00
Handsome-wzw
e4b1021d73 feat(ui-web): ask an agent whether it works, from its card
## Summary

The sub-agents page could say an agent was installed and never whether it worked. The probe answers "the command is on this machine"; the only way to learn whether Raven can actually delegate to it was to delegate and watch. `subagents.test` has answered that question since the probe design landed and the TUI roster has had the button all along -- the web page lost it when the five-button form (install / connect / enable / test / switch to) was replaced by two verbs on a row.

It comes back as a section of the card, not a third verb on the row:

- the last verdict with its age (`Worked, 3h ago`, and its zh translation), the reason under a failure, and a dot in the page's own three colours;
- **Run a test**, which becomes **Testing...** plus a **Stop** the moment it is pressed;
- for a `cli` agent only, the line saying the test dispatches it for real and spends its quota. An `acp` test reaches its verdict in the handshake and an `openai` one in the free `/models` probe, and warning about a bill neither of them sends is how a reader learns to ignore the warning on the one that does.

No server change: `subagents.test` / `subagents.test_cancel` are called exactly as the TUI calls them, and `SubagentsTestParams` is untouched.

**Where the button is deliberately absent.** `subagents.test` cannot answer for two kinds of row, so neither is offered one:

- built-in: `run_test` refuses it outright ("a built-in agent runs in this process; there is nothing to test") and the caller records the refusal, so the button could only ever put a permanent failure on the one agent that is demonstrably running;
- discovered (`vendored`): `_find` takes `config` or `preset`, and a product row is in neither pool. Reproduced against the real install rather than read: for `Raven-Code`, both sources answer `subagent_not_found`.

This is a gap, not a design. Those four rows (`Raven-Code`, `Raven-Design`, `Raven-Oncall`, `Raven-Research`) are exactly the ones whose startup warning says "launch config changed since its capabilities were measured; run a test to re-measure" -- the server asks for a test it then cannot perform. Closing it is a server change of its own shape (a `vendored` source through `_discovered_entry`, `_test_acp` recording the snapshot for it, and `_hot_apply` after), so it is not in this MR; this MR hides the button rather than shipping one that can only fail.

**The name is held for the length of the test.** `_RUNNING` (what `subagents.test_cancel` looks in) and `TestStateStore` are both keyed by the config name, so the name cannot move while a run is registered under it. Renaming mid-run left the card showing a row that matched neither: Stop vanished, Run a test came back and a second press started a second run under the new name, and the first went on for up to two minutes with nothing pointing at it and a verdict nothing would display. Reproduced through the store before fixing, then closed by rendering the name as plain text while running. The description keys nothing and stays editable throughout. (Raised as an inline blocker in review; fixed.)

**Why the running state is local as well as remote.** `subagents.test` holds the connection open for the whole run -- up to `TEST_TIMEOUT_SECONDS` (120) -- and answers with the verdict. The rows the call repaints from are therefore the first news that the test is over, and nothing before them says it began. So the store keeps the names it has a test in flight for, and the card reads the union with the row's own `test_running`: a test another client started is only ever on the row.

**Checked and deliberately not changed, for the reviewer:**

- The TUI's own test button has the same `configured ? 'config' : 'preset'` derivation and therefore the same vendored gap. Left alone: fixing it belongs with the server change above. Its name is not editable from the hub, so the rename-orphan path does not exist there.
- `migrate` while a test runs is reachable from the head and preserves the name, so the run stays cancellable -- but it is a remove-plus-add, and `TestStateStore.load` validates the stored verdict's `fingerprint(cfg)` against an entry whose transport has changed, so the verdict is discarded rather than shown. A lost measurement, not a lost run; raised in the review thread rather than folded in here.
- `runTest`'s `finally`: nothing throws through it today (`run` turns every rejection into a toast), and the comment says so. The path that does exist, a rejected call, has a case.
- The quota note has no real-machine proof: this install has no `cli` sub-agent, so that branch was covered by unit test and mutation only.
- Stale text swept for `test verdict|test button|five buttons|enable, test` across the whole tracked tree with no `--include`. Two hits were this MR's to fix and are in the diff; the server-side comments naming "the UI Test button" were true of the TUI and are now true of both.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Real machine, `raven serve` on the branch's own build against a real `RAVEN_HOME` (18 rows: 1 built-in, 4 vendored, 2 config, 11 presets), driven in headless Chromium:

- every card walked: the section is present on all 13 testable rows and absent on the built-in row and the four vendored ones; no console or page errors;
- `claude_code` pressed for real: `Never tested / led off` -> `['Stop', 'Testing...(off)']` -> `Worked, just now / led` within one poll, the verdict coming off the refetched row;
- the name control goes plain the moment the test starts and comes back when it settles (`nameCtl=editable -> plain -> editable`, description editable throughout);
- `subagents.test_cancel` round-tripped through `DS.xa.act('test_cancel', row)`: accepted, no error frame;
- the same card under `language: zh`: caption, verdict and button render from the zh catalogue.

```
npm run test --prefix ui-web    101 files, 1550 passed
npm run test --prefix ui-tui    141 files, 2017 passed, 13 skipped
npm run gen:check  --prefix ui-web    generated client matches the contract (162 methods)
npm run type-check --prefix ui-web    clean
npm run lint / lint:rpc / lint:i18n / type-check --prefix ui-tui    23 warnings, 0 errors (identical count on main)
scripts/check_commit_messages.py, commitlint, scripts/check_source_language.py    pass over the branch
make build-ui                                          dist rebuilt and served
```

The new tests are not theatre: 14 mutations were applied one at a time and the suite re-run against each; every one went red -- each half of `canTest` dropped separately; the missing-time guard in the verdict; each of the three age thresholds; `testCosts` true for every kind; `running` read from only the row or only the local flag; the failure detail shown on a pass; the second-call guard removed; `stopTest` sending `test`; the flag never cleared; the rename left live mid-test.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no user-facing docs cover this card; screenshots taken during verification, not shipped)

## Risk

User-visible: a new section on each testable agent's card. Pressing it dispatches the agent once (a `cli` test spends its quota; the card says so). No wire or config change; the two RPC methods already exist and are called as the TUI calls them. Rollback is reverting the single squash commit; the card returns to the description-only shape.

- [x] Security impact considered (no new data path; the test is looked up by name server-side, never by a caller-supplied command)
- [x] Backward compatibility considered (an older server without the test fields renders "Never tested"; `XaOp` gained two members read only by the two sources in this repo)
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 10:00:45 +00:00
0xKT
ab4a605eb5 fix(*): let read_skill serve hub bodies the skill menu advertised
## Summary

The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.

Key decisions:

- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
  the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
  `use_skill` and the segment builder's post-gate hydrate refuse exactly what
  they refused before. Reading is the weaker case because it installs nothing
  and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
  flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
  products rather than being one, so reporting the root refused a skill for
  mentioning XDG at all. The reported path now runs down to the segment naming
  the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.

`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.

- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
  tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
  3 skipped. The three skips are pre-existing and environment-bound (two
  `chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
  note `these instructions reference paths outside Raven (~/.config/mcporter,
  ~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.

The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.

The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.

Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.

## Related Issues

N/A
2026-09-10 09:47:05 +00:00
LivXue
2088cb4eae fix(*): let read_skill serve hub bodies the skill menu advertised
## Summary

The scent menu advertises hub skills by id and closes with "Read one with
read_skill(id)". It screens candidates on the operator blocklist and the safety
score only. `read_skill` then applied `refusal_for_detail` -- the install-time
policy, whose body lint refuses a hub skill naming another product's home
dotdir -- so a skill flagged by nothing but that lint was recommended by id and
could never be read. Seen on an A-share earnings skill whose body mentions
`~/.config` and `~/.openclaw`: the menu offered it, the read answered
`Error: refusing to read hub skill: ... references external home directories`,
and the turn spent its remaining calls on detours.

Key decisions:

- The policy now has two strengths. `refusal_for_read` keeps the blocklist and
  the safety bar and drops the body lint. `refusal_for_detail` is untouched, so
  `use_skill` and the segment builder's post-gate hydrate refuse exactly what
  they refused before. Reading is the weaker case because it installs nothing
  and hands the body back wrapped as untrusted data.
- The lint still speaks on the read path, as a note above the body naming the
  flagged paths so they are not followed.
- The lint itself was too coarse. A generic root such as `~/.config` hosts other
  products rather than being one, so reporting the root refused a skill for
  mentioning XDG at all. The reported path now runs down to the segment naming
  the owning product (`~/.config/openclaw`), and `~/.config/raven` passes.

`read_skill`'s own description already tells the model to call it "for any skill
listed by description alone". The code contradicted that sentence; this makes it
true rather than changing it.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Six tests written first and watched fail; the catch-22 one reproduces the
production message verbatim before the fix.

- `pytest tests/test_skill_hub_policy.py tests/test_skill_hub_tools.py
  tests/test_context_scent.py tests/test_skill_segment_builder.py` -- 121 passed
- `pytest` over every skill / scent / context test file (36 files) -- 673 passed,
  3 skipped. The three skips are pre-existing and environment-bound (two
  `chmod 000` cases that do not block root, one fetched-not-tracked template).
- `ruff check` and `ruff format --check` over the changed files -- clean
- `lint-imports` -- 9 contracts kept, 0 broken
- `python scripts/check_source_language.py origin/main...HEAD` -- exit 0
- `python scripts/check_commit_messages.py origin/main..HEAD` -- exit 0
- End to end against the skill that was refused: the body now returns with the
  note `these instructions reference paths outside Raven (~/.config/mcporter,
  ~/.openclaw)`, while `refusal_for_detail` on the same metadata still refuses.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

Behaviour change, stated plainly: a hub skill whose body names a foreign home
dotdir is now readable. It was already advertised by id, and a read installs
nothing and returns the text as untrusted data, so what changes is that the
model can see what it was told to look at. The paths are named in a note above
the body so they are not followed silently.

The install and inject paths keep the old gate. `use_skill` and the segment
builder still call `refusal_for_detail`, and the test that pins `use_skill`
refusing an `~/.openclaw` body is unchanged and still passes.

The lint narrowing does reach the install gate as well, and this is the one
place the change is a relaxation rather than a split: a body mentioning bare
`~/.config`, or `~/.config/raven`, previously refused the install and now does
not. A body naming another product under a generic root is still refused, now
reported by the segment that names it. This was the false positive the change
is for, but it is a widening of what may install and is called out here rather
than buried.

Rollback is a revert of the whole change; the two commits are independent of
anything else on the branch.

## Related Issues

N/A
2026-09-10 09:47:05 +00:00
0xKT
35563457d2 fix(ui-web): three ways the title editors leave a conversation nameless
## Summary

Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.

**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.

**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.

**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.

**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.

The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.

Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Branch and base run in separate worktrees, both at the same base, same interpreter.

- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
  1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
  introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
  `unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
  need `--localstorage-file` for `localStorage` to exist on this box at all, and with
  it the store no longer refuses, so the refusal each asserts does not happen. Both
  reproduce on the base, and neither file imports anything this change touches. A
  second environment settles it: review ran the same head and reported 1,536 tests
  passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
  `check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
  full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
  `lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
  `renamed` call, a missing export, a missing harness verb, and the pre-edit title.
  The ordering one is driven through the real `rpc.onReconnect` rather than
  `openLiveSession`, because the ordering is between the two and a test that calls the
  inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
  forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
  on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
  editor gone, button back, zero title calls, no page error. Reconnect with the editor
  open, forced by closing the socket from the page: before, `Cannot read properties of
  null (reading 'textContent')` with the input stranded and no session reload; after,
  heading restored, editor gone, reload done, no page error. Reconnect with a name
  typed into an open editor: heading and rail row both settle on the committed name,
  no page error. That probe renamed a real conversation, so its title was put back and
  the stored metadata checked byte-identical afterwards.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible, all of it in the same direction: a title that used to vanish stays put.

- Ending an editor on a conversation switch commits what was typed, which is what
  leaving the field already did. It cannot reach a different conversation than the one
  it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
  only case that changes is a name being generated, where the heading is empty and the
  row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
  shape or a schema.

Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.

## Related Issues

N/A
2026-09-10 09:46:25 +00:00
LivXue
13252ea0e2 fix(ui-web): three ways the title editors leave a conversation nameless
## Summary

Four defects in the conversation title editors, found while debugging one report:
double-clicking a rail row, pressing Enter without changing the name, and watching
the title disappear.

**The reported one.** The rail's editing box and the line it goes back to being are
both spans in one child slot, so React reconciles them onto a single DOM node and
resets every prop. Scroll offset is not a prop: it is state the browser keeps on the
element. That box is a scroll container on purpose (the stylesheet clips it with an
ellipsis and its own note says a long name scrolls inside itself), so focusing and
selecting the field scrolls it to the caret -- 316px for a forty-codepoint name in a
222px row. The finished title, drawn into that same node, inherited the offset and
rendered at x=-298, and `text-overflow: ellipsis` on a scrolled box paints nothing at
all. Any exit from the editor did it, changed name or not; only a remount or a reload
cleared it, and a store redraw did not. Distinct keys make the three states three
elements, so no browser-held state can cross between them.

**Commit once.** Committing with Enter replaces the focused input with the heading,
and Chrome fires a blur for that removal, so the whole commit ran again on a node
already off the tree: two title calls for one edit, two toasts on a refusal, and a
`replaceWith` throw from inside the first call's own mutation. The heading came back
only because the nested call had already put it there. One flag closes it, replacing
the Escape branch's `inp.onblur = null`, which was the same intent written for one
path.

**The stranded editor.** The top-bar editor stands in place of `h1#title`, so while it
is open that id resolves to nothing -- and the live layer reaches the heading through
it on both paths that change which conversation is open, plus on the reconnect that
reloads the open one. That reconnect read it unguarded, so with an editor up the
handler threw on its first line and took down everything after it: the conversation
was never reloaded and never re-subscribed after a socket gap, the reader was never
told the connection was back, the extension surfaces stayed empty for the life of the
tab, and the input sat in the top bar with the heading gone and the rename button
hidden, unrecoverable without a reload. A null check alone would be worse than the
crash -- the editor would stay open over a different conversation and its next commit
would rename that one to the name typed for the old one -- so the invariant is that no
title editor survives a conversation switch, and ending one commits to the row it
captured.

**Where that teardown has to sit.** The reconnect is the only caller that builds a
detached `{ id, title }` for `openLiveSession`; every other one hands over the live
row, whose title the commit mutates in place. So it was the only one that could read a
title, have the teardown inside `openLiveSession` commit a different one underneath
it, and then paint the value it had captured -- the rail redrew with the typed name
while the top bar went back to the pre-edit one and stayed there until the
conversation was opened again. It ends the editor before the lookup instead. The call
inside `openLiveSession` stays, being idempotent and covering the callers that do not
come through here.

The reconnect needs no heading at all in the ordinary case: the row carries the title,
and the heading was the wrong first source twice over, holding the plain form with any
leading icon stripped and holding nothing while a name is being generated. It stays
behind the row as the last resort for a current conversation absent from the list.

Every live-layer touch of the heading is now either preceded by that teardown or
null-guarded.

## Type

- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

Branch and base run in separate worktrees, both at the same base, same interpreter.

- `npx vitest run --no-file-parallelism` (ui-web): branch 1534 passed / 2 failed of
  1536; base 1529 passed / 2 failed of 1531. Failing-ID sets diff empty -- 0
  introduced, 0 fixed. Exit code, failure count and unhandled-error count all read:
  `unhandledErrors` is 0 on both sides.
- The two failures are `deskStore` and `palette`'s "when storage refuses" cases. They
  need `--localstorage-file` for `localStorage` to exist on this box at all, and with
  it the store no longer refuses, so the refusal each asserts does not happen. Both
  reproduce on the base, and neither file imports anything this change touches. A
  second environment settles it: review ran the same head and reported 1,536 tests
  passed at exit 0, so the pair is local to the machine this was authored on.
- `scripts/check_commit_messages.py`, `check_source_language.py`,
  `check_large_files.py` over `origin/main..HEAD`: pass.
- `npm run gen:check`, `npm run type-check`, `node scripts/check-page.mjs` (after a
  full two-step page build): pass.
- Not run, with the reason: `lint-python` and `lint-imports` (no Python in the diff),
  `lint-tui` and `lint-bridge` (no files in either tree).
- Each of the five new tests was proven red before its fix: node identity, a second
  `renamed` call, a missing export, a missing harness verb, and the pre-edit title.
  The ordering one is driven through the real `rpc.onReconnect` rather than
  `openLiveSession`, because the ordering is between the two and a test that calls the
  inner one cannot see it; the live harness now compiles that handler too.
- Driven in headless Chrome against the built page, on a real conversation with a
  forty-codepoint name. Before: glyph run at x=-298 with the box at x=18; after: x=18,
  on Enter, Escape and clicking away. Top-bar Enter on an unchanged name: heading back,
  editor gone, button back, zero title calls, no page error. Reconnect with the editor
  open, forced by closing the socket from the page: before, `Cannot read properties of
  null (reading 'textContent')` with the input stranded and no session reload; after,
  heading restored, editor gone, reload done, no page error. Reconnect with a name
  typed into an open editor: heading and rail row both settle on the committed name,
  no page error. That probe renamed a real conversation, so its title was put back and
  the stored metadata checked byte-identical afterwards.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed

## Risk

User-visible, all of it in the same direction: a title that used to vanish stays put.

- Ending an editor on a conversation switch commits what was typed, which is what
  leaving the field already did. It cannot reach a different conversation than the one
  it was typed over: the editor captures its row when it opens.
- The reconnect now prefers the row's title and keeps the heading behind it, so the
  only case that changes is a name being generated, where the heading is empty and the
  row is right.
- Rollback is per commit; each stands alone and none changes a stored title, a wire
  shape or a schema.

Checked and deliberately not fixed: the demo layer has the same three unguarded
heading writes, and no path to them -- it has no reconnect, and every other route
blurs the editor first, which commits it. And a source removed from under an open
editor would throw out of the new teardown, which the old code would also have thrown
on; an editor cannot exist unless the source did, and the live layer never removes it.

## Related Issues

N/A
2026-09-10 09:46:25 +00:00
0xKT
44309dde3a feat(cli): raven agents new scaffolds a complete agent end to end
## Summary

raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.

Key decisions:

- **Templates are real code, fire-tested before templating.** The eleven
  files under raven/templates/agents_scaffold/ pass ruff and py_compile
  like any source, ride the wheel, and their content was proven live
  before landing: discovery, handshake, and plugin tool/hook injection
  all green on a hand-assembled probe in a disposable home. A dedicated
  spike also proved the placement is invisible to the import-linter
  contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
  target is the raven home's agents/ tree, discovery's first root: a
  scaffolded folder is on the roster without any registration.
  --register mirrors the generated install.py through the same pinned
  write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
  manifest, re-parses the plugin manifest, compiles every generated
  file, and really scans discovery; smoke spawns the launcher for one
  initialize frame. Three smoke outcomes are told apart: GREEN, the
  launcher's loud no-key refusal (fail-closed design, passed through
  verbatim), and FAILED with the scene preserved. Display names are
  fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
  renders schemas/subagent.schema.json (a discriminated union on kind)
  and schemas/raven-plugin.schema.json from the pydantic models; a
  contract family holds the on-disk files byte-equal to a fresh render
  and validates every real manifest on the tree against them. Editors
  get instant validation with two settings lines, documented in the
  guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
  the from-zero developer guide (gold standard: a developer who never
  read the source reaches a green handshake in ten minutes); CONTEXT.md
  renames the category entry to Discovered agent -- agent the thing,
  harness the mechanism, subagent the protocol seat -- with product
  absorbed into Avoid; the charter gains the scaffold entry and the
  engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
  project in the working directory (pip install -e territory); --here
  lands it on the plugins-dist shelf. The launcher adopts the official
  ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
  is missing; the doctor reports that row as disabled by design with
  the install cure printed. No plugins/ directory ships beside an
  engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
  hostile lenses (filesystem edges of a command that writes into real
  raven homes; template quality as the file set every future agent
  copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
  pin an enabled row that cannot start, the name fence ignored the
  discovered tree, one installed engine wheel rode the host's and every
  sibling's turns through a fixed tool name, and crash residue was
  discovered as a hidden live agent. All fourteen close in a
  dedicated hardening commit, each with a regression test built from the review's own
  reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
  Nothing under raven/contracts/ or the agent loop changed. The branch
  carries exactly two narrow runtime fixes exposed by the review:
  discovery now skips dot-directories (crash residue is never an
  agent), and the config schema gains an engine round-trip field
  (declared as a field-level neutral seam; merge and readiness
  semantics untouched).

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Every commit landed through a full-suite rehearsal on a clean bench
  before touching the branch; tails over the original base's 19953
  passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
  smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
  expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
  every step a pure addition, +65 tests net. The branch diff is
  fingerprint-stable across the rebase (git patch-id --stable verified
  pairwise across two clean rebases); the branch closes at 20094 passed
  / 137 skipped / exit 0 on the current main base, +80 tests net over
  whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
  end: one command scaffolds into ~/.raven/agents, the four-segment
  card runs all green, and a genuine LLM turn has the agent's own model
  call its own scaffolded hello tool through the permission gate and
  relay the exact output; the probe was then removed without touching
  the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
  four doctor lines, readiness ready, and a live ACP initialize
  handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
  passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
  tampered file each turn the family red); all six subagent manifests
  and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
  make check-large-files, make check-source-language: green at every
  step; wheel build carries all seventeen template files and none of
  schemas/.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.

## Related Issues

N/A
2026-09-10 07:07:15 +00:00
0xKT
a577cae8f4 feat(cli): raven agents new scaffolds a complete agent end to end
## Summary

raven agents new scaffolds a complete, working agent on the installed
raven: eleven fire-tested template files land in the raven home's agents/
tree (discovered with zero registration), a four-segment health card
examines the result (atomic write, doctor, a real ACP handshake smoke,
next steps), and --engine-wheel grows the same scaffold into the
wheel-shaped harness the shipped engines use. The developer guide ships
with it, in-repo and editor-checkable.

Key decisions:

- **Templates are real code, fire-tested before templating.** The eleven
  files under raven/templates/agents_scaffold/ pass ruff and py_compile
  like any source, ride the wheel, and their content was proven live
  before landing: discovery, handshake, and plugin tool/hook injection
  all green on a hand-assembled probe in a disposable home. A dedicated
  spike also proved the placement is invisible to the import-linter
  contracts and needs exactly one coverage-gate exclusion line.
- **Home-first landing, registration as an explicit act.** The default
  target is the raven home's agents/ tree, discovery's first root: a
  scaffolded folder is on the roster without any registration.
  --register mirrors the generated install.py through the same pinned
  write door; --here lands in the checkout for in-repo agent work.
- **The scaffold examines its own work.** Doctor re-validates the
  manifest, re-parses the plugin manifest, compiles every generated
  file, and really scans discovery; smoke spawns the launcher for one
  initialize frame. Three smoke outcomes are told apart: GREEN, the
  launcher's loud no-key refusal (fail-closed design, passed through
  verbatim), and FAILED with the scene preserved. Display names are
  fenced so no input can corrupt the generated manifest.
- **Schemas derive from the models.** scripts/export_agent_schemas.py
  renders schemas/subagent.schema.json (a discriminated union on kind)
  and schemas/raven-plugin.schema.json from the pydantic models; a
  contract family holds the on-disk files byte-equal to a fresh render
  and validates every real manifest on the tree against them. Editors
  get instant validation with two settings lines, documented in the
  guide.
- **The lexicon follows the terminology ruling.** agents/BUILDING.md is
  the from-zero developer guide (gold standard: a developer who never
  read the source reaches a green handshake in ten minutes); CONTEXT.md
  renames the category entry to Discovered agent -- agent the thing,
  harness the mechanism, subagent the protocol seat -- with product
  absorbed into Avoid; the charter gains the scaffold entry and the
  engine-ownership line.
- **--engine-wheel lands both shapes.** User mode drops the engine
  project in the working directory (pip install -e territory); --here
  lands it on the plugins-dist shelf. The launcher adopts the official
  ENGINE_PACKAGE convention and refuses loudly pre-exec when the engine
  is missing; the doctor reports that row as disabled by design with
  the install cure printed. No plugins/ directory ships beside an
  engine-shaped agent, matching the shipped engines.
- **A pre-push adversarial review hardened the whole surface.** Two
  hostile lenses (filesystem edges of a command that writes into real
  raven homes; template quality as the file set every future agent
  copies) found 3 HIGH / 6 MED / 5 LOW -- among them: --register could
  pin an enabled row that cannot start, the name fence ignored the
  discovered tree, one installed engine wheel rode the host's and every
  sibling's turns through a fixed tool name, and crash residue was
  discovered as a hidden live agent. All fourteen close in a
  dedicated hardening commit, each with a regression test built from the review's own
  reproduction.
- **Near-zero kernel touch, and the two touches are the review's.**
  Nothing under raven/contracts/ or the agent loop changed. The branch
  carries exactly two narrow runtime fixes exposed by the review:
  discovery now skips dot-directories (crash residue is never an
  agent), and the config schema gains an engine round-trip field
  (declared as a field-level neutral seam; merge and readiness
  semantics untouched).

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

- Every commit landed through a full-suite rehearsal on a clean bench
  before touching the branch; tails over the original base's 19953
  passed / 137 skipped: 19980 (templates + command), 19993 (doctor +
  smoke + gold tests), 20010 (schemas), 20010 (docs, count-identical as
  expected), 20018 (engine wheel) -- exit 0 and 137 skipped throughout,
  every step a pure addition, +65 tests net. The branch diff is
  fingerprint-stable across the rebase (git patch-id --stable verified
  pairwise across two clean rebases); the branch closes at 20094 passed
  / 137 skipped / exit 0 on the current main base, +80 tests net over
  whatever base it sits on -- re-measured in full after every rebase.
- A real-machine pass on the live raven home closed the loop end to
  end: one command scaffolds into ~/.raven/agents, the four-segment
  card runs all green, and a genuine LLM turn has the agent's own model
  call its own scaffolded hello tool through the permission gate and
  relay the exact output; the probe was then removed without touching
  the roster.
- Gold tests spawn for real: scaffold into an isolated home, assert the
  four doctor lines, readiness ready, and a live ACP initialize
  handshake GREEN (~3s, zero tokens); a keyless twin pins the refusal
  passthrough and an engine twin pins disabled-as-designed.
- Schema contract: mutation audits both directions (tampered model and
  tampered file each turn the family red); all six subagent manifests
  and all eight raven-plugin.toml files on the tree validate.
- make lint-python, uv run lint-imports (9 contracts kept, 0 broken),
  make check-large-files, make check-source-language: green at every
  step; wheel build carries all seventeen template files and none of
  schemas/.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

New command surface only: no existing agent, roster row, or runtime path
changes behavior. The generated .env stays untracked and the wheel
builder still refuses secrets. The one gate change is a coverage-gate
exclusion declaring templates non-production. Rollback: revert the
squash commit; scaffolded agents already created keep working, since
they run on the installed raven like any discovered folder.

## Related Issues

N/A
2026-09-10 07:07:15 +00:00
KevinHuSh
97dbf04cc0 feat(provider): tag models with capabilities and rebuild the provider model manager
## Change description

> ## Summary
>
> Expand provider and model metadata across the backend, RPC contract, TUI, and web UI. Providers now expose curated catalogs, homepages, native endpoints, and capability metadata. The web settings flow supports catalog browsing and manual model management, provider branding, homepage links, and green-only connected status indicators. MiniMax CN and NVIDIA onboarding remain available through their built-in provider flows.
>
> ![image.png](/uploads/5245ee6e91f17dfabdda152adac16257/image.png){width="478" height="324"}
>
> ![image.png](/uploads/fd2d7e372895b1adbad4154cdbeeecef/image.png){width="501" height="338"}
>
> ## Type
>
> - [ ] Fix
> - [x] Feature
> - [ ] Docs
> - [ ] CI / tooling
> - [ ] Refactor
> - [ ] Other
>
> ## Verification
>
> - [x] Relevant tests pass locally
> - [ ] Relevant lint / type checks pass locally
> - [ ] User-facing docs or screenshots are updated when needed
>
> Exact commands and results:
>
> - `uv run pytest tests/test_provider_catalog.py tests/test_provider_registry_data.py tests/test_rpc_model.py tests/test_providers_factory.py -x` - 234 passed, 4 skipped
> - `npm test -- --run src/shell/provider-mark.test.tsx src/features/model/ModelPicker.test.tsx src/features/onboard/OnboardPage.test.tsx src/features/settings/SettingsPage.test.tsx` - 133 passed
> - `git diff --check` - passed
>
> The full web type-check was not marked as passing because the current test tree contains unrelated existing TypeScript errors in `SettingsPage.test.tsx`.
>
> ## Risk
>
> Provider registry data and model-selection behavior change across backend and frontend surfaces. Existing provider IDs and stored configuration remain supported. The change can be rolled back by reverting this merge request.
>
> - [ ] Security impact considered
> - [x] Backward compatibility considered
> - [x] Rollback path is clear for risky changes
>
> ## Related Issues
>
> N/A

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [ ] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
2026-09-10 07:06:55 +00:00
KevinHuSh
140a2cdeed feat(provider): tag models with capabilities and rebuild the provider model manager
## Change description

> ## Summary
>
> Expand provider and model metadata across the backend, RPC contract, TUI, and web UI. Providers now expose curated catalogs, homepages, native endpoints, and capability metadata. The web settings flow supports catalog browsing and manual model management, provider branding, homepage links, and green-only connected status indicators. MiniMax CN and NVIDIA onboarding remain available through their built-in provider flows.
>
> ![image.png](/uploads/5245ee6e91f17dfabdda152adac16257/image.png){width="478" height="324"}
>
> ![image.png](/uploads/fd2d7e372895b1adbad4154cdbeeecef/image.png){width="501" height="338"}
>
> ## Type
>
> - [ ] Fix
> - [x] Feature
> - [ ] Docs
> - [ ] CI / tooling
> - [ ] Refactor
> - [ ] Other
>
> ## Verification
>
> - [x] Relevant tests pass locally
> - [ ] Relevant lint / type checks pass locally
> - [ ] User-facing docs or screenshots are updated when needed
>
> Exact commands and results:
>
> - `uv run pytest tests/test_provider_catalog.py tests/test_provider_registry_data.py tests/test_rpc_model.py tests/test_providers_factory.py -x` - 234 passed, 4 skipped
> - `npm test -- --run src/shell/provider-mark.test.tsx src/features/model/ModelPicker.test.tsx src/features/onboard/OnboardPage.test.tsx src/features/settings/SettingsPage.test.tsx` - 133 passed
> - `git diff --check` - passed
>
> The full web type-check was not marked as passing because the current test tree contains unrelated existing TypeScript errors in `SettingsPage.test.tsx`.
>
> ## Risk
>
> Provider registry data and model-selection behavior change across backend and frontend surfaces. Existing provider IDs and stored configuration remain supported. The change can be rolled back by reverting this merge request.
>
> - [ ] Security impact considered
> - [x] Backward compatibility considered
> - [x] Rollback path is clear for risky changes
>
> ## Related Issues
>
> N/A

## Type of change

- [ ] Bug fix
- [x] New feature
- [ ] Document
- [ ] Others

## Checklists

### Development

- [x] Lint rules pass locally
- [x] Application changes have been tested thoroughly
- [x] Automated tests covering modified code pass

### Security

- [ ] Security impact of change has been considered
- [ ] Code follows company security practices and guidelines

### Code review

- [x] Merge request has a descriptive title and context useful to a reviewer. Screenshots or screencasts are attached as necessary
- [x] Merge request linked to JIRA ticket when applicable
2026-09-10 07:06:54 +00:00
Tchen
63b56ea887 feat(*): the deck's image tool rides the host's image_generate
## Summary

The ppt-engine plugin's `ppt_generate_image` carried its own HTTP transport and was assembled without any config: the base was always OpenRouter, the model always gpt-image-2, the proxy empty, and the key came only from the `OPENROUTER_API_KEY` that LiteLLM happened to export. `tools.media.image` had no effect on it, `PPT_IMAGE_API_KEY` in `.env.example` was misleading, reference images were impossible, nothing was recorded as usage, and on an OpenAI-compatible gateway the size table asked gpt-image for frames it refuses (`1536x864`).

Host side:
- `ServiceLocator` gains three grants: `media_config(kind)` (the host's `tools.media.<kind>`, read live and resolved exactly as `image_generate` resolves it, OpenRouter key borrowing included), `media_proxy`, and `web_config()` (the host's `tools.web`). `RuntimeHandles` gains `usage_recorder` (the loop's image-usage recorder). The contribution ledger records each grant and the power it hands over; `CONTRACTS_VERSION` moves to 15 and the surface digest is repinned.
- `raven/contracts` stood at exactly 2,500 lines on main against a 2,500 ceiling. The four fields fit by condensing the plugin surface paper's prose (the digest ignores prose, so the pin holds); the ceiling stays at 2,500 and no addendum is needed.
- The default image model moves to `openai/gpt-image-2.5-sunburst` (tool, schema note, Settings presets, launcher log). A chat-routed image model (Nano Banana and its kind) is asked for the requested frame through OpenRouter's `image_config.aspect_ratio`; before, the host dropped the ratio for any family outside the Images API list and such a model answered 1408x768 whatever was asked.
- `images_api_size` maps the gpt-image family to the three frames it draws (`1536x1024`, `1024x1536`, `1024x1024`, nearest by orientation) and keeps the pixel table for other families; OpenRouter still takes `aspect_ratio`. Both `/images/generations` and `/images/edits` use it.
- A contributed tool may declare `configured() -> bool` (documented in `raven/contracts/plugin_surface.py` beside `bind_runtime`, and named in CONTEXT.md's Admission entry as the tool's optional fifth authored member). `admit_tool` refuses a `configured` that is not callable and dispenses the callable on the frozen `ToolSpec`; the registry exposes it through `spec_of`, and `_unconfigured_tool_names` reads it there, per assembly, withholding a False answer for the turn. The built-in media tools answer it for themselves, and `effective_quality` is the one place a call's quality is resolved.
- The ledger test's digest is now the same on every supported interpreter: `ast.dump` on 3.13 omits empty optional fields by default, so the test renders with `show_empty=True` wherever the parameter exists, and 3.12 and 3.13 agree byte for byte (verified on both interpreters for this branch's papers and for main's, whose existing pin becomes valid under 3.13 too). `PINNED_CONTRACT_SURFACE` is repinned to that digest.

Engine side (`plugins-dist/ppt-engine`):
- `PptGenerateImageTool` is now a thin wrapper over the host's `ImageGenerateTool`: any model the host configured (Images API families or chat-routed models such as Nano Banana), `references` (figure ids, source file names or paths, up to six) sent as `input_references`, the host's eight aspect ratios and `low`/`medium`/`high` quality, usage recorded where the host records it, the reply carrying the `width` and `height` that came back, any returned format converted to PNG. Green-screen keying, the cache (model + quality + ratio + reference digests + prompt) and the sources ingest stay the deck's own.
- The tool is always assembled and declares `configured()`, which the loop's withheld axis asks live per tool-array assembly: it is withheld while the host's section names neither a key nor a model (an ambient `OPENROUTER_API_KEY` alone does not offer it) and offered the moment the section does, in both directions and without a restart, the same reversible lane and rule `image_generate` applies to itself. The first revision decided this once at assembly, which the review showed missing both transitions. The cache is keyed on the quality the host actually sends (`ImageGenerateTool.effective_quality`: Settings' value where one is set), and a cache hit reports `width` and `height` too. The slice's `webProxy` and `imageSearch.apiKey` become overrides of the host's `tools.web` (vendor slot first, legacy leaf after).
- Template overfitting: the tool description and the `ppt-script-authoring` skill no longer describe one house style (the "flat blue-yellow-black Shanghai skyline" wording written for the bundled illustrated templates). The author reads the slot in the render, describes the style actually seen there, and passes the template's own illustration as a reference, so a user-uploaded template is served the same way as a built-in one. Design decision D33 in `plugins-dist/ppt-engine/docs/ppt-raven-design.md`.

Launchers:
- `agents/raven-ppt/run.py` keeps main's `configure_image_generation` (from !578), run after both LLM branches: the host's whole `tools.media.image` and `tools.media.proxy` are inherited, the inherit branch borrows the chat key for pictures toward OpenRouter only, and `selectionConfig` follows the host live only where the host file answers. `PPT_IMAGE_API_KEY`, `PPT_IMAGE_API_BASE` and `PPT_IMAGE_MODEL` pin the product's own account, endpoint or model, and any such pin keeps the section as rendered. The copy into the plugin slice is gone; the slice's `image` key stays as an operator override of the grant. `raven-design` shares the `inherit_media_image` helper; its behaviour is unchanged.

## Type

- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other

## Verification

```
uv run --frozen ruff check <touched files> && uv run --frozen ruff format <touched files>
# 0 errors

uv run --frozen pytest tests/test_ppt_engine_generate_image_tool.py tests/test_ppt_engine_plugin.py \
  tests/test_ppt_engine_assembly.py tests/test_media_gen_tool.py tests/test_agents_ppt_launcher.py \
  tests/test_agents_design_launcher.py tests/test_config_product_render.py tests/test_core_plugin_stack.py \
  tests/test_cli_agent_loop_wiring.py tests/test_kernel_budget.py tests/test_contracts_two_tier_ledger.py \
  tests/test_plugin_contribution_ledger.py -q
# 278 passed, 1 skipped (after the rebase onto main)

uv run --frozen pytest -q tests/test_agents_ppt_launcher.py tests/test_contracts_two_tier_ledger.py \
  tests/test_kernel_budget.py tests/test_media_gen_tool.py tests/test_plugin_contribution_ledger.py \
  tests/test_ppt_engine_assembly.py tests/test_ppt_engine_generate_image_tool.py tests/test_ppt_engine_plugin.py \
  tests/test_tool_capabilities.py tests/test_agent_loop_web_tools.py
# 245 passed (second revision, after the review fixes)

uv run --frozen pytest -q <the ten files above> tests/test_tool_admission.py tests/test_subagent_dag_control_tools.py
# 319 passed (third revision: admission of configured(), version-stable digest)

uv run --frozen pytest tests --ignore=tests/integration -q
# 6653 passed, 16 skipped; the only failures were tests/test_cron_tool.py::test_add_naive_at_with_tz_anchors_to_that_zone
# and tests/test_cli_cron_commands.py::test_list_shows_jobs, which fail identically on an untouched checkout
# (this machine has no system zoneinfo); unrelated to this change
```

Driven for real through the deck's `ppt_generate_image` against OpenRouter (host key, `low` quality), one call per ratio, dimensions read from the returned PNG:

| model | 16:9 | 9:16 | 1:1 | 21:9 | usage recorded |
|---|---|---|---|---|---|
| openai/gpt-image-2 | 1536x864 | 864x1536 | 1024x1024 | 1536x656 | yes |
| openai/gpt-image-2.5-sunburst | 1536x1024 | 1024x1536 | 1024x1024 | - | yes |
| bytedance-seed/seedream-5-0-lite | 3642x2048 | 2048x3642 | 2048x2048 | - | yes |
| bytedance-seed/seedream-5-0-pro | 2048x1152 | 1152x2048 | 2048x2048 | - | yes |
| google/gemini-3.1-flash-image (chat route, after the fix) | 1376x768 | 768x1376 | 1024x1024 | 1584x672 | yes |

gpt-image-2 behind two OpenAI-compatible gateways answered 1536x1024 / 1024x1536 for 16:9 / 9:16 (the frames the family draws). A `references` call on gpt-image-2 consumed the picture (1321 input tokens) and produced a new one.

```
cd ui-web && npx vitest run src/features/settings/SettingsPage.test.tsx
# 50 passed
```

- [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: a deck deployment whose host has no `tools.media.image` (and no `OPENROUTER_API_KEY` in the environment) no longer sees `ppt_generate_image` at all; previously the tool appeared and every call failed. A host that configured a non-gpt-image model now gets that model for deck pictures too.
- Plugins built against the previous `ServiceLocator` keep working: the new fields default to `None`, and the engine reads them with `getattr` fallbacks.
- Rollback: revert the squash commit (three commits on the branch); no data migration is involved. `CONTRACTS_VERSION` and the surface pin go back together.

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A
2026-09-10 06:17:40 +00:00
Handsome-wzw
7b45527b5b fix(tools): an array sent as its own JSON is still an array
## 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.
2026-09-09 15:42:36 +00:00
forrestjgq
f01231fef6 fix(cli): overhaul trajectory browser interaction ux (#379)
## 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>
2026-09-05 23:58:20 +08:00
0xKT
2f862d8ca2 feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## 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.
2026-09-05 17:09:13 +00:00
hylarucoder
c703db6ffd feat(build): RAVEN_WHEEL_SLIM switch for a headless cloud wheel
## 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.
2026-09-05 17:09:13 +00:00
0xKT
6f309a40bb feat(contracts): the wake-scheduling grant reaches plugins by namespace
The organ verbs landed with the keyed-wake partition; this puts the
grant on the papers. A new contract-tier paper declares the
WakeScheduler face; RuntimeHandles grows the grant field; the loop
mints one namespaced instance per contributed tool at bind time, the
namespace taken from the identity the plugin build stamps on the tool
-- a namespace a plugin could choose for itself would be a namespace
it could steal. A holder's keys can neither see nor move another
plugin's wakes, nor any plain reminder, which lives outside the keyed
partition entirely; a host with no scheduler grants None and a binder
declines, the discipline the handles have always carried.

CONTRACTS_VERSION moves 3 -> 4 with the surface digest repinned; the
ledger admits WakeScheduler to the contract tier.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-09-02 15:52:04 +08:00
0xKT
e2807f39bc fix(plugins): the everos move's install face closes
One wave back the backend left the wheel; the registry path degraded
loudly and everything else did not. Seven host surfaces imported the
plugin package directly -- 25 function-level imports, none guarded -- so
an install without the distribution turned raven doctor, onboard,
import, the memory RPC methods and the sub-agent trace writer into
tracebacks instead of the loud degrade the ruling requires. And no
install path carried the distribution at all: install.sh built only the
root project and the release published only its wheel, so a released
raven upgraded straight into the degraded state its own default config
names.

The host now asks one question, everos_plugin_installed -- a spec lookup
that executes no plugin code, so an installed-but-broken plugin stays a
visible bug instead of reading as an absence -- and each surface answers
in its own register: doctor reports plugin_missing as the fault it is,
onboard names what to install, the RPC returns its own error shape, the
trace writer logs once. install.sh carries the distribution on both its
paths with a degrade ladder that never blocks the install, the release
builds and uploads the sibling wheel, and the diff-coverage gate's
pathspec follows the code it had lost sight of. The absence tests take
the package away for real (a sys.modules sentinel) rather than stubbing
the guard they exist to prove.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-31 06:09:43 +08:00
0xKT
dc8438993d refactor(plugins): everos leaves the wheel and installs like any other plugin
The memory backend shipped inside the raven package and was discovered
through the bundled directory -- the one source that no third party can
use. It is now its own distributable beside the host wheel,
plugins-dist/everos-memory, declaring itself in the raven.plugins
entry-point group: the same door a user's own plugin comes through. The
group was empty until now, so this move is what puts the first plugin on
the path every other plugin must take.

A workspace member reaches an environment only through a dependency, so
the dev group takes it and uv.sources resolves it to the member rather
than an index; without that the entry point would exist on disk and
nowhere in the environment, and everos would quietly vanish from the dev
tree. The default configuration is unchanged: memory.backend stays
"everos", and a missing plugin degrades loudly and keeps the agent
booting, which is what the assembly already did.

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-31 04:46:47 +08:00
0xKT
602ce94967 feat(plugins): the service locator lends plugins the connection's provider
A plugin hook or tool that needs a judgement -- a draft reviewer, a
sufficiency check, a page digest -- had no model to ask: the locator
carried workspace, the two identities and notify. Building a provider
from the config inside the plugin would be a second credential and a
second pool that a model switch never reaches. The grant is the loop's
own provider, handed through build_plugin_tools and build_plugin_hooks
by the assembly root; optional, None where the host has no model to
lend (a CLI listing plugins, a test building a locator). The first
RuntimeServices field, admitted by a demonstrated demand.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-31 02:43:16 +08:00
0xKT
a0a98dc9f4 feat(plugins): a product names its own plugin roots with plugins.dirs
The host scanned four fixed sources: the bundled dir, <home>/plugins,
./.raven/plugins and the raven.plugins entry-point group. A product that
ships a plugin beside its own config had no checked-in place for it:
.raven/ is git-ignored, the user dir is the operator's, and an entry
point means a wheel. plugins.dirs names extra roots, each scanned like
the project dir (same <root>/<id>/raven-plugin.toml layout, same PROJECT
priority, so a user drop-in of the same id still shadows it). The CLI
table and the console's ext.list read the same config, so what they show
is what boots.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-31 02:36:54 +08:00
0xKT
3160da8c22 test(*): test files named for retired homes take the names of what they test
Six test files still carried the address their subject lived at before the
assembly root and the market existed: cli/_cron_handler, cli/_*_stack,
cli/_plugin_stack, core.helpers and plughub. Renamed to the package they
exercise today (core.cron_stack, core stacks, core.plugin_stack,
providers.factory, market); contents unchanged, the two docstring pointers
were already corrected.

Audit ref RES-15, ruled: rename.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
2026-08-30 03:01:12 +08:00