495 Commits

Author SHA1 Message Date
Handsome-wzw
615256bf90
fix(*): show a machine's switched-off agent entries, and reconnect them from its sheet (#1019)
## Summary

Reported by the owner on 2026-10-20, on the first day with #1007 on
their site: the Ravenx card said
"No agent connected here yet" while the machine's connect form greyed
Claude Code as "already connected
on this machine". Both were telling the truth by different rules. The
card counted connected entries
only (`agents_on_machine(only_enabled=True)`); the form, and
`subagents.add`'s duplicate rule, counted
every entry of the preset on the machine, switched off or not -- and the
owner had just switched
`Claude Code@ravenx` off. So a switched-off entry was counted nowhere on
the card, blocked the form,
and had no way back from the machine's side.

What changes:

- `machines.list` rows carry `agents_off_here`, the entries on the
machine that are switched off
(the connected ones stay in `agents_here`; both empty when the agents
section or the config file
cannot be read). The card line and the sheet field show them marked
*switched off*.
- `subagents.presets` now means by `on_machines` the machines a
*connected* entry runs on, and adds
`off_on_machines` (machine + entry name) for the switched-off ones. Both
additive.
- The connect form keeps greying a preset the machine has connected, but
offers one it has switched
off back under its own entry -- each switched-off entry as a choice of
its own, by name, since a
machine may hold several explicitly named ones: the option says
*switched off*, the working-directory
field is left out (the entry keeps the one it had), and the button reads
**Reconnect**, which runs the
agents page's own `subagents.toggle enabled=true` on that entry -- same
proof ping, no second entry. The
add is offered only while the machine holds nothing of the preset (the
server refuses it otherwise). The
Reconnect goes through the agents page's own `act`, so the row is marked
joining for the length of the
ping: that page draws it pending and cannot press its own Connect
meanwhile, and the form, reading
`joining` too, greys the entry the other way round -- one ping whichever
side pressed. The card line and
the sheet field read *N on this machine* / *Agents on this machine*,
since they list switched-off
  entries as well. The
write is guarded like the add (opening generation, drawer still current)
and marked pending so a
form reopened meanwhile does not offer it twice; a refusal stays on the
form in the agent's words.
- Docs: machines guide (en + zh), CHANGELOG, CONTEXT.

## Type

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

## Verification

- `pytest tests/test_rpc_machines.py tests/test_rpc_schema_match.py
tests/test_rpc_registration.py -n 4`: 580 passed; `pytest
tests/test_rpc_subagents.py tests/test_ops_connection_add.py
tests/test_raven_config_tool.py -n 4`: 365 passed. The two extended
cases (`agents_off_here` listed apart; `off_on_machines` carries the
entry name while `on_machines` leaves it out) fail with the two handler
changes stashed.
- `ruff check` / `ruff format --check` on the changed Python files:
clean.
- ui-web: `vitest run src/features/extAgents scripts/gates`: 483 passed
(5 new page cases: the third for two switched-off entries of one preset
on one machine, each reconnectable in turn; the fourth and fifth for a
toggle in flight from either side -- the agents page offers no Connect
while the machine's Reconnect runs, and the form greys the entry and
says why while the agents page's Connect runs -- both fail with the
previous store/form; the switched-off preset is pickable and labelled,
no directory field, Reconnect toggles the existing entry and lands back
on the sheet with the lists re-read; a refused Reconnect stays on the
form in the agent's words -- both fail with
`MachineCards.tsx`/`store.ts` stashed; the card/sheet case extended with
a switched-off entry). `tsc --noEmit`, `eslint` on the changed files,
`gen:check` clean; `ui-tui` `lint:rpc` / `lint:i18n` clean.
- `pytest tests/test_docs_site.py`: 16 passed; `mkdocs build --strict`:
clean.
- Full suite: see the comment on this PR.
- Real page: see the comment on this PR.

## Risk

- [x] Security impact considered: the new fields carry entry names
already shown on the agents page; Reconnect is the existing toggle, with
its proof ping and refusals.
- [x] Backward compatibility considered: `agents_off_here` and
`off_on_machines` are new fields (the page maps both defensively);
`on_machines` narrows to connected entries, which only this page reads.
- [x] Rollback path is clear for risky changes: revert the commit;
nothing stored changes shape.

## Related Issues

N/A (follow-up to #1007, from the owner's report on 2026-10-20)

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-20 16:48:09 +08:00
Handsome-wzw
2e390adff6
feat(*): say the next step on a ready machine and connect an agent from its sheet (#1007)
## Summary

Follows #1005, which is now on main; main was merged in after it landed,
so the diff against main is this change alone.

A registered machine whose node is up left the owner with nothing to do:
the card said
"Link up, no agent" and the Agents tab did not mention the machine. The
way to connect
an agent on it (the preset sheet's *Runs on*) is hidden exactly where it
is needed most:
a preset already connected on this computer is withheld from the roster,
and a preset not
installed here shows only install instructions. Measured on the owner's
own setup
(2026-10-19): two machines registered from the page, both reached and
with the node,
and no path on the page to put Claude Code on either.

What changes:

- `machines.list` rows carry `agents_here`, the connected agent entries
that run on the
machine (`agents_on_machine(only_enabled=True)`; a malformed agents
section lists none).
The card says "N connected here: ..." or "No agent connected here yet";
the state line
now reads "Link up, no agent running", so "running now" and "connected
here" are two lines.
- A ready machine's sheet says the next step and offers **Connect an
agent on this machine**:
a form in the same drawer with the preset, its working directory there,
and Connect. It
calls the existing `subagents.add` with `machine`, `remote_cwd` and the
name fixed to
`<preset name>@<machine id>`, so the proof ping and every refusal are
the add's own.
- New read-only `subagents.presets`: the presets a machine's node can
start (acp, cli),
listed whether or not an entry already holds them, with `connected_here`
and
`on_machines` so the form greys the one this machine has and says when
this computer
has it too. Built-in agents, Mirasim shims and openai endpoints are not
listed.
- The Agents tab's "not installed" sheet also offers *Runs on* when ssh
machines are
registered, with a Connect button once a machine is picked: running on a
machine does
  not need the agent on this computer.
- New read-only `machines.local_keys`: the private keys this computer
has, as `~/.ssh/<name>`
(ssh's default identities in ssh's order, then any file with a `.pub`
beside it). The
register form fills the key path with the first and offers the rest,
instead of a
placeholder naming `id_ed25519` to an owner whose key is `id_rsa`; with
none found it
  says so and points at the password login.

- One preset once per machine, held by the server whichever way the add
arrives: `subagents.add`
without a `name` now refuses a preset the machine already has (judged on
preset + machine, before
the ping), naming the entry there and whether it is connected or
switched off; a named add is a
second entry on purpose (two working directories, say). The page's
connect form leaves the name to
the server's default (`<preset>@<machine id>`) rather than fixing its
own spelling, so the page and
a chat can no longer put one agent on one machine twice between them
(the owner's setup had the two
  routes spelling the default differently, 2026-10-19).

Contract (`rpc-schema/openrpc.json`), models, both generated clients and
`i18n/messages.json`
are updated; the offline fixture library answers the two new methods and
the new field, and refuses
the duplicate the way the server does.
Docs: the machines guide (en + zh), CHANGELOG, CONTEXT.

**Fifth round, after the review draft on LivXue's board (four findings,
all reproduced) and the bot's inline note.** `machines.list` read the
agents section for every row and caught only the pydantic error, so a
`config.json` that does not parse at all (a `//` comment, a trailing
comma) failed the whole listing with `internal_error` while the gateway
ran on: `_agents_here` now treats the loader's `ConfigReadError` the
same way (nothing listed; the agents page says why), and the test is a
real unparseable file. The register form proposed `id_ed25519` before
`id_rsa` and called that ssh's order; `ssh -G` lists `id_rsa` first on
OpenSSH 8.9, 9.6 and 9.9, so an owner with both was proposed the key ssh
itself tries second: `DEFAULT_IDENTITIES` follows the measured order, a
test pins it against the ssh of the computer running it, and the guide's
two sentences say so. A row that exists, switched off, with its command
missing here, was offered **Connect on <machine>** from its sheet while
the press sent the row's own `toggle`, which carries no machine: only a
preset not yet on the roster is offered one, as the other *Runs on*
already did. An add still running on a machine was unknown to a form
opened again on that machine, so the preset could be pressed twice (a
second proof prompt, then the duplicate refusal, a toast saying
connected and a form saying not): the adds in flight are kept by the
name each lands under (`mconnectPending`) and the form greys that preset
(*being connected on this machine right now*). The contract's
`subagents.presets` description names the add's default
`<preset>@<machine id>` now, as the bot noted. The branch also carries
#1005's fourth commit (merged) and main up to #1001.

**Sixth round: merged onto #1005's head (`9dbef0874`) and LivXue's F1
fixed.** The merge had three conflicts, all the same shape -- this PR's
addition beside what #1005 changed (the `auth` field in the machine
sheet, `agents_here` in the fixtures, the new register assertions) --
and keeps both sides; the superseded password-used-once code
(`generate_key`, `install_public_key`, `revoke_public_key`,
`forget_key`, the remote scripts) is gone from the diff, so a review of
this PR no longer grades that design. F1: a connect form open across a
write reads `presets` again when the add lands -- whichever opening it
is -- so a preset just connected on that machine reads as taken instead
of inviting a second add the server refuses; the case that pinned the
wrong end state moved with it. F2 (four ui-web files reformatted to the
root prettier style) is withdrawn in 1834c68ee: each file is the #1005
text with this PR's own hunks replayed onto it (a three-way merge of the
base, the base formatted the way the reformat had been, and this
branch's head; ten overlaps resolved by hand, the maintainer edits'
lines included), so what remains in them is this PR's change -- the four
files' lines against #1005 go from 173/211/281/1694 to 137/44/206/590.
Check used: formatting the result with the root config reproduces the
previous head except where that head itself kept hand style, so nothing
but wrapping changed.

Verification, sixth round: related Python `1068 passed` over the twelve
files this PR touches or affects, diff coverage 96.13% (348/362
executable changed lines); full suite `-n 6` 33386 passed, 3 failed --
the LibreOffice case and the two simulation cases this Mac always fails
(run before the F1 commit, whose change is ui-web only); ui-web `vitest
run` 4121 passed (250 files, gates included), `tsc --noEmit` and
`eslint` clean, `gen:check` 247 methods; ui-tui `lint:i18n` and
`lint:rpc` clean; the three range gates over `origin/main..HEAD`.

**Also merged: #1005's c0c822294** (Oncall campaigns run on a password
machine through trunk's askpass; the helper answers a password prompt
only; `--password-stdin` implies `--auth password`) and the three
maintainer edits on this branch (68ea01189, e5884ddf1, dac563aab), all
clean.

**Seventh round: two findings from the review of 91952baed.** (1) A
configless Raven held a kept machine password unscrubbed: `held_secrets`
returned early when `config.json` was missing, before it read
`keys/<id>.password` -- and those live under the Raven home
independently of any config, so a tool printing that file passed the
password to the model verbatim (gloryfromca, inline). An absent config
is now an empty config-credential set rather than the end of the call;
the case is pinned with no config file at all, and the existing "no
config holds nothing to scrub" case still holds for the config's own
credentials. (2) CI shard 3/4 failed on
`tests/test_node_stderr_replay.py::test_a_reason_written_on_stderr_while_the_link_was_down_reaches_the_run_watching_it`
("did not happen in time", then a leftover agent in its teardown) and
`tests/test_subagent_cli_remote.py::test_...` -- both stand-in-machine
timing cases this branch does not touch, the same class as the ones
recorded for #965/#979/#983; 135 passed over those three files locally
in one run, and the job passes on rerun.

Verification: `tests/test_held_secrets_machine_passwords.py` and
`tests/test_security_untrusted_context.py` 42 passed; the other three
files that read the scrubber 223 passed; `ruff check`, `ruff format
--check` and `ty check` clean on the two changed files; the three range
gates over `origin/main..HEAD`.

## Type

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

## Verification

- `pytest tests/test_rpc_machines.py tests/test_ops_connection_add.py
tests/test_rpc_subagents.py tests/test_rpc_schema_match.py
tests/test_rpc_registration.py -n 4`: 768 passed (7 new: `agents_here`
incl. the malformed-section case, `local_keys` order and exclusions at
both layers, `subagents.presets` membership and placement).
- Full suite `pytest -n 6`: see the last comment on this PR for the
count (run at the head).
- `ruff check` / `ruff format --check` on the changed Python files:
clean.
- Duplicate-on-machine refusal: 2 new cases in
`tests/test_rpc_subagents.py` (default-named second add refused before
any ping, naming the entry and its state; named add allowed; another
machine allowed; switched-off entry named), both fail with the handler
change stashed; related groups 928 passed after it.
- ui-web: `vitest run` 4006 passed (250 files, page gates included; 7
new page cases: the card line and the sheet's next step, the connect
form end to end incl. a refusal and the nothing-to-connect case, key
prefill with and without keys, an absent agent connected onto a machine
from its own sheet, and no machine offered when none is registered);
`tsc --noEmit` clean; `eslint` clean on the changed files; `gen:check`
matches the contract.
- ui-tui: `gen:rpc` and `gen:i18n` regenerated; `pytest
tests/test_docs_site.py` 16 passed; `mkdocs build --strict` clean.
- Real machine, isolated gateway (own Raven home and registry copy,
channels off, the branch's node installed in its own directory on the
test machine), real browser: the ready machine's sheet shows the next
step and the button; the form lists 12 startable presets; Connect of
Claude Code on the machine landed in 9 s and the card then reads "1
connected here: Claude Code@<id>"; the register form was prefilled with
this computer's `~/.ssh/id_ed25519` with `id_rsa` as the other choice;
an agent absent here (OpenClaw) connected onto the machine from its own
sheet was refused in 1 s with the agent's own sentence ("the agent's
command was not found on machine ...") shown in place. Gateway stopped
by pid, the node directory and daemon on the machine removed afterwards.
- Previews of the five surfaces were shown to the owner before the
change and approved.
- Fifth round, red before and green after: `machines.list` over a real
`config.json` that is not JSON lists the machine with no agent
(`test_list_lists_no_agent_over_a_config_file_that_does_not_parse_rather_than_failing`;
through the real `Dispatcher` with a scratch home and registry, the
previous handler answered `-32603 internal_error`, this one `[('box',
[])]`); `local_keys` order at both layers, plus
`test_the_default_identities_are_in_the_order_this_computer_s_ssh_offers_them`
against `ssh -G -F /dev/null` (this Mac, OpenSSH 9.9: `id_rsa, id_ecdsa,
id_ecdsa_sk, id_ed25519, id_ed25519_sk, id_xmss, id_dsa`; the same on a
registered Linux machine, OpenSSH 9.6); the page: a configured,
switched-off, missing row gets no machine field and no *Connect on*
(`offers a row that exists no machine...`), and a form opened again on a
machine while an add still runs there greys the preset, keeps the other
one pressable and sends no second add (`greys a preset whose add on the
machine is still running...`) -- both fail with the three page sources
stashed. The six Python files 821 passed, diff coverage of the changed
lines 97.50%; ui-web `vitest run` 4119 passed (page gates 216 included),
`tsc`, `eslint` on the feature, `gen:check` (247 methods), `npm run
build` with both boot goldens; ui-tui `gen:rpc`/`gen:i18n`, `lint:i18n
-- --check`; `ty check` on the changed modules; `pytest
tests/test_docs_site.py tests/test_living_docs.py` 18 passed, `mkdocs
build --strict` clean; the three range gates; full suite (`-n 6`) 33353
passed, 4 failed: the three this Mac always fails (a LibreOffice case,
two simulation cases) and one stand-in-machine timing case in
`tests/test_subagent_cli_remote.py` (the record not yet written when the
test reads it) that passes 3 of 3 runs alone and touches no file this
branch changes.

## Risk

- [x] Security impact considered: `machines.local_keys` returns key
*paths* on this computer, to this computer's own page, never key
material; `subagents.presets` carries no credential; nothing new leaves
the host. The connect form reaches the machine only through the existing
`subagents.add` and its proof ping.
- [x] Backward compatibility considered: `agents_here` is a new required
field on `machines.list` rows (the page maps it defensively); the two
new methods are additive; an older page against this server ignores
both.
- [x] Rollback path is clear for risky changes: revert the commit; no
stored data changes shape.

## Related Issues

N/A (follow-up to #983 and #1005, from the owner's walkthrough on
2026-10-19)

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: MiniMax (minimax-m3.1-flash-free) <noreply@minimax.io>
2026-10-20 14:24:04 +08:00
Handsome-wzw
7376de6828
feat(*): a machines hub tab, and registering a machine with a password Raven keeps (#1005)
## Summary

Add a Machines tab to the Agent Hub and let owners register an SSH
machine with either a key or a password.

- The Machines tab reuses the existing machine cards, details and
registration form. The hub remembers the last selected module. Machine
details show the login method, and removal explains that the locally
stored password is deleted.
- Password registrations keep a 0600 credential file under the Raven
home's 0700 keys directory. Registration, node installation, file tools,
tunnels and Oncall use the shared SSH askpass transport. Passwords are
excluded from command lines, registry rows and responses, and included
in held-secret scrubbing.
- Password connections authenticate independently, disable inherited
jump hosts, and answer only the registered account's password prompts.
Oncall cannot redirect a stored password to another endpoint. Windows
rejects this mode before creating credentials because its OpenSSH cannot
execute Raven's POSIX helper. Key authentication remains supported as
before.
- Concurrent registrations preserve the successful request's password.
Each probe uses its own temporary 0600 credential file, which is
scrubbed and removed afterwards. Password writes receive a file
identity; cleanup checks ownership under the writer's lock. Successful
registration checks duplicates again and publishes its password with the
registry row under that lock. Both completion orders, RPC cancellation
and CLI aborts are covered.

The RPC contract adds optional `MachineRow.auth` and password
registration parameters. English and Chinese machine documentation, the
runtime context and changelog describe the resulting behavior.

## Type

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

## Verification

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

After rebasing onto the latest main:

```bash
uv run --no-sync pytest tests/test_ops_connection_add.py tests/test_ops_connections.py tests/test_ops_transport.py tests/test_cli_ops_connection_commands.py tests/test_rpc_machines.py tests/test_held_secrets_machine_passwords.py tests/test_acp_remote.py tests/test_node_client.py tests/test_rpc_schema_match.py tests/test_rpc_registration.py tests/test_import_cycle_budget.py -q -n 0 --tb=short --cov=raven.ops.connection_add --cov=raven.ops.transport --cov=raven.cli.ops_connection_commands --cov=raven.rpc.methods.machines --cov-report=json:/tmp/pr1005-fix-coverage.json
```

Result: 932 passed, 6 skipped. The skipped cases require zsh, tcsh or
csh, which are absent on this Linux host.

- `uv run --no-sync python scripts/coverage_gate.py --coverage-json
/tmp/pr1005-fix-coverage.json diff --base-ref HEAD^ --threshold 99`:
100% (94/94 executable changed lines) for the concurrency fix.
- `uv run --no-sync pre-commit run --from-ref HEAD^ --to-ref HEAD`:
passed, including formatting, file checks and private-key detection.
- `uv run --no-sync ty check raven/ops/connection_add.py
raven/ops/transport.py raven/cli/ops_connection_commands.py
raven/rpc/methods/machines.py`: passed.
- `uv run --no-sync lint-imports`: all 10 contracts passed.
- `uv run --no-sync python scripts/check_source_language.py
origin/main..HEAD`, `uv run --no-sync python
scripts/check_commit_messages.py origin/main..HEAD`, `make
check-large-files`, and `git diff --check origin/main...HEAD`: passed.

The original RPC failure/cancellation and CLI-abort reproductions failed
before the fix. Additional regressions cover the reverse completion
order, probes with competing passwords, temporary-secret scrubbing,
duplicate registration and failed registry writes. The complete rebased
source was compared with the original PR plus main, and the concurrency
fix retained its patch identity.

## Risk

- [x] Security impact considered: stored and temporary passwords are
owner-readable and scrubbed from tool output. Unknown SSH host keys are
accepted on the first connection, as before; the guides explain
verifying the host from a terminal first on an untrusted network.
Passwords shorter than six characters or containing CR/LF are rejected.
- [x] Backward compatibility considered: key registration remains the
default and `MachineRow.auth` is optional. Password publication and
cleanup now use file locks and atomic replacement; temporary probe files
are removed when the probe ends.
- [x] Rollback path is clear: revert this PR to restore the earlier
registration flow. Removing a machine deletes the password stored under
its id. Existing password rows require migration to key authentication
if reverting the feature.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
Co-authored-by: MiniMax (minimax-m3.1-flash-free) <noreply@minimax.io>
Co-authored-by: Codex <noreply@openai.com>
2026-10-20 12:23:40 +08:00
江国庆/Forrest
55c145ceb8
feat(*): probe the bug report receiver and gate uploads with a challenge (#1015)
## Summary

Adds two things to bug reporting, on the Bug Report Receiver and on the
Raven clients that send to it.

**A hello probe.** The receiver answers `GET /v1/hello` with its service
name and protocol version, and Raven asks it before a report starts, so
a person learns that the receiver is down (or that the URL leads to
something else) before spending a redaction review on the report:

- `raven trajectory report-bug` and the trajectory browser's *Report a
bug* probe before collecting anything. On a TTY without `--yes` they ask
whether to continue (default no; declining collects and pins nothing).
With `--yes` they say they are continuing and keep the package if the
upload then fails. Without a TTY and without `--yes` the existing rule
still refuses first.
- The WebUI's *Report a problem* wizard asks the new RPC
`bugreport.probe` when it opens. When the receiver does not answer, the
report does not start: the wizard shows the reason and *Check again*,
and the primary button becomes *Continue anyway*, so going on is the
reader's explicit choice and never a dead end. A start pressed while the
check runs waits for it (at most 8 s) and then checks the form again.
- The probe runs under one deadline for the whole exchange (5 s), does
not follow redirects, and the new requests never echo credentials or
query tokens from a redirect target.
- `/healthz` stays as the operator's liveness check. It was not reused
for the probe because anything alive answers ok there, and it is not
under a base URL's path prefix.

**An upload challenge.** The receiver now takes only uploads that answer
its Upload Challenge: the client gets a challenge from `POST
/v1/challenge` and sends back an HMAC, under a constant built into
Raven, of the challenge and the package's report id, sha256 and size.
Key decisions:

- Shallow by design. The goal is that an HTTP client that is not Raven,
written without reading Raven's source, cannot upload. The constant is
published with the (public) source and is not configurable, so there are
no credentials to manage. The docs say so, with a table of what the gate
stops and what it does not.
- Stateless. Challenges are sealed with a per-process random key, are
valid for 300 s and are not consumed; a restart retires them all.
Replaying a captured upload as it was only re-delivers the same package,
which the receiver already answers as a duplicate; replaying it with
another package fails because the answer is bound to the package.
- Checked from the headers alone, after the existing header checks and
before the daily budget is reserved: a refused upload gets 401
(`unauthorized` or `challenge_expired`) with `WWW-Authenticate:
Raven-Challenge`, writes nothing, and still spends a rate-limit token.
Package checks, rate limits, budgets and timeouts are unchanged.
- The client fetches the challenge inside the upload's existing total
deadline. A 404 there means a receiver older than this Raven; a 401 is
retryable only when the challenge expired.

Uploading has not shipped in a release yet (it is under `Unreleased` in
the CHANGELOG), so no released client breaks. A receiver deployed from
main must be upgraded together with its clients, and a proxy in front of
it must forward all of `/v1/`; the docs and the CHANGELOG entry say so.

Commits, in order: the hello route and the client probe; the challenge
end to end (new `raven/trajectory/receiver_auth.py`, and the Upload
Challenge term in `CONTEXT.md`); the CLI probe; the WebUI probe (RPC,
wizard, i18n, regenerated ui-web and ui-tui bindings); a fix that checks
the form again after the wizard waits on the probe; the docs in both
languages; integration tests against real processes.

## Type

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

## Verification

- `uv run --no-sync pytest tests/test_trajectory_receiver_auth.py
tests/test_trajectory_receiver.py tests/test_trajectory_upload.py
tests/test_rpc_bugreport.py tests/test_cli_trajectory_commands.py
tests/test_cli_trajectory_browse.py
tests/test_trajectory_report_session.py tests/test_rpc_schema_match.py
-q --idle-ceiling-strict --cov=raven --cov-branch
--cov-report=json:coverage.json`: 1190 passed.
- `make coverage-diff COVERAGE_BASE_REF=origin/main`: 99.53% of changed
lines (213/214), threshold 90%.
- `uv run --no-sync pytest
tests/integration/test_bug_report_upload_e2e.py
tests/integration/test_web_bugreport_e2e.py -m integration -n 0 -q`: 10
passed, three runs in a row.
- `uv run --no-sync pytest tests/ -q`: 102 failed, 33527 passed. All 102
are in 14 files this PR does not touch (code tools, code flow, subagent
probe and backends, a2a, whatsapp, provider config and rates, security
network, everos, tracing command), and the same 102 fail on the base
commit (checked on a worktree of `main`; the two failure sets are
identical).
- `make lint-python`, `make lint-imports` (10 contracts kept), `deptry
raven`: pass. `make lint-types`: only two `pyflakes.checker` unresolved
imports in
`agents/raven-code/plugins/code-flow/code_flow/tools/diagnostics.py`,
because pyflakes is not installed in the local environment (CI installs
all extras); every changed Python file passes `ty check`.
- `mkdocs build -f docs-site/mkdocs.yml --strict`: pass.
- ui-web: `gen:check`, `lint` (0 errors), `type-check`, `npx vitest run
--maxWorkers=8` (251 files, 4176 tests), `build` + `build.py` +
`check-page` / `check-css` / `check-class-namespace`: pass.
- ui-tui: `lint`, `lint:rpc`, `lint:i18n`, `type-check`, vitest (2242
tests), `build`: pass.
- `make check-source-language check-large-files check-commits`: pass.
- Manual, on real processes: a receiver plus curl (hello and challenge
answer; an upload without an answer, or with a forged one, gets 401 and
nothing is stored); the CLI (an upload while the receiver runs; while it
is down, the warning, continuing and the kept package; declining on a
TTY leaves nothing); a real gateway walked with Playwright in English
and Chinese at 1280 and 360 px (the warning while the receiver is down,
Check again after it starts, a report through to its receipt, no page
errors, no overflow).

- [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:

- With an upload URL configured, `report-bug` and the browser's *Report
a bug* start with a probe of at most 5 s, and ask one more question when
the receiver does not answer. The WebUI wizard shows a warning and
*Continue anyway* in that case.
- The receiver refuses uploads that do not answer the challenge. A
receiver deployed from main must be upgraded together with its clients
(no released client uploads yet). A proxy that only forwarded
`/v1/bugreports` must forward all of `/v1/`.
- No change to package formats, `record.json`, or anything stored on
either side.

Rollback: revert the squash commit; there is nothing to migrate.

- [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-10-20 10:22:53 +08:00
knqiufan
ba3a3f8c54
fix: initialize the web composer with its configured model (#840)
## Summary

The web composer initially displayed hardcoded `minimax-m3` until a full
provider catalogue finished loading, even when another model was
configured. Read the actual model/provider selection immediately after
the gateway handshake, independently of catalogue building and provider
probes when the gateway supports it.

- Add optional `model.options.include_providers` with its existing
full-catalogue behavior as the default. Advertise selection-only support
through `system.hello.server_capabilities`; older strict gateways
receive their original parameters and share one full catalogue request.
- Show loading, empty and retry states. Permit sending once the
selection arrives, and keep a known selection usable during background
refreshes of the same view. First reads and navigation to another
session or a new draft still wait for that view's selection.
- Allow settings role pickers to use their available rows while the
composer's provider catalogue refreshes. Keep New Task available during
selection loading or failure, retain provider-setup redirects, and clear
catalogue loading state if a gateway call throws synchronously.
- Preserve session bindings, forced default providers and staged draft
picks. Ignore responses superseded by navigation or a local pick, and
prevent slow catalogues from overwriting the selection.
- Update fixtures, generated web/TUI contracts, bilingual messages and
user-facing documentation.

Maintainer follow-up on top of the author's commits (no history
rewritten):

- Restored the design comment in `model_options` that explains why a
catalogue read warms the rate catalogue (the picker's context windows
come from it and nothing else on the page refreshes it), and said why a
selection-only read skips it. The handler and module docstrings now
describe `include_providers`.
- Restored the comment in `loadProviders` that explains why a late
catalogue answer is dropped, now also naming a later refresh of the same
view.
- Reverted the remote CLI test change
(`tests/test_subagent_cli_remote.py`), which was unrelated to this fix.
The final diff no longer touches that file. The race it addressed is
real and still open on main (see Risk), so it should land as its own
change; the original commit remains in this branch's history.
- A draft promoted to a conversation keeps its known selection. The
promotion takes no new view ticket, so the first same-view re-read of
the new conversation (a settings-changing tool result, a provider or
default-model write, a typed id) used to drop the chip to "Loading
model..." and refuse sends until that read answered. The promotion now
hands the draft's selection to the session it minted, but only when that
selection was read under the ticket the promotion began on; a reader who
opened another conversation or a new draft during the create keeps that
view's own selection, and a draft whose selection never arrived or
failed still waits. The README says so.
- Named the provider list as `ui-web/CONTEXT.md` does: the two keys this
change added are now `gui.model.provider_catalogue_loading` and
`gui.model.provider_catalogue_failed` (texts unchanged, generated TUI
catalogue regenerated), and the `ModelSource` comment, the README and
this change's test titles say provider catalogue instead of the bare
word, which the existing `gui.model.catalogue_*` keys use for a vendor's
model list.

## Type

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

## Verification

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

Maintainer verification on Linux, Python 3.12 (`--all-extras`), Node 26,
in isolated worktrees with their own virtualenv and `npm ci`. "Merged
tree" means this branch merged into the latest main without committing;
it merges cleanly.

Branch head:

- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_rpc_model.py tests/test_rpc_schema_match.py
tests/test_rpc_system.py -q`: 772 passed (238 in
`tests/test_rpc_model.py` after the wording change).
- `npx vitest run --maxWorkers=6 --testTimeout=20000` in `ui-web` (with
`NODE_OPTIONS=--localstorage-file=...`, which this Node version needs):
4004 passed, 0 failed.
- The promotion regression, `src/state/session/runtime.promote.test.ts`
"the model chip across a promotion": eight cases on the real registry,
promotion, chip source and store with only the transport faked, each run
with and without the selection-only capability. The first-re-read case
fails on the previous head (status `loading`, send refused) and passes
with the fix. Removing the hand-off call fails exactly those two cases
(179 of 181 model and promotion tests still pass); removing its ticket
guard fails exactly the two cases where the reader left during the
create.
- `npm run type-check`, `npm run gen:check`, `npm run lint` in `ui-web`:
pass, lint 0 errors and 4 existing warnings in untouched files. `npm run
lint:rpc` and `npm run lint:i18n` in `ui-tui`: pass.
- `scripts/check_commit_messages.py`, `scripts/check_large_files.py`,
`scripts/check_source_language.py` over the branch, and `commitlint
--from origin/main`: pass.

Merged tree, this head on the latest main (as of #985), merged without
committing:

- Full `ui-web` vitest run as above: 4158 passed, 0 failed.
`type-check`, `gen:check` and `lint` pass; `python ui-web/build.py`
passes both boot snapshots (365 and 364 nodes).
- `tests/test_rpc_model.py`, `tests/test_rpc_schema_match.py`,
`tests/test_rpc_system.py`: 788 passed. `ui-tui` `lint`, `lint:rpc`,
`lint:i18n`, `type-check`: pass. `ruff check`, `ruff format --check`,
`lint-imports` (10 contracts kept), `deptry raven`, `ty check`: pass.

Earlier merged-tree runs, before this round's two follow-up fixes (which
change only web code, the README, i18n keys, test titles and one Python
comment):

- Full Python suite on the merge with main as of #1002, `uv run --frozen
--python 3.12 --all-extras pytest -q`: 33222 passed, 102 failed. Rerun
on bare main on the same machine, exactly those 102 test ids fail there
too (this machine's environment), so no failure is introduced by this
branch. An earlier full run of the merge, against main before #1002,
also errored in the remote CLI cancel test; that test file is identical
to main's, and whole-file runs of it on bare main failed 1 of 5 with the
same race (see Risk).

Real page, before this round's fixes, isolated gateways (own RAVEN_HOME,
loopback only), headless Chromium, configured model
`deepseek/deepseek-chat` with a dummy key, recording the chip text and
the page's own `model.options` frames:

- Main's page on main's gateway: the chip reads `minimax-m3`, enabled,
from 198 ms until the full catalogue answers at 986 ms. This is the
reported bug.
- This page on this gateway: "Loading model..." (disabled) until the
selection-only read answers about 100 ms after the handshake; the chip
shows `deepseek-chat` at 593 ms while the 55-row catalogue answers at
1817 ms.
- This page on main's gateway (no capability): only the legacy `{}` read
is sent, no validation error, and the chip goes from "Loading model..."
to the configured model when that read answers (706 ms).

Earlier verification by the author on Windows, before the follow-up
commits: `tests/test_rpc_model.py` and `tests/test_rpc_schema_match.py`
665 passed; the hello/ping/version/dispatcher subset of
`tests/test_rpc_system.py` 26 passed; `ui-web/build.py` boot snapshots
matched; `ui-web` `npm test` 3,278 passed across 215 suites,
`gen:check`, `type-check`, `build` and `lint` passed; `ui-tui`
`lint:rpc` and `lint:i18n` matched.

## Risk

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

The new read mode is read-only and returns no provider credentials.
Existing RPC callers (the TUI picker and the ACP config options) omit
the field and keep full provider catalogue responses; web clients
negotiate support before sending it. A failed selection read requires a
retry, while a pending refresh of a known selection, including the first
re-read after a draft becomes a conversation, allows sending. Settings
role pickers and task navigation no longer inherit the composer's
loading restriction.

Known behavior, not changed here:

- Every navigation, including the boot's own switch to the draft view,
waits for that view's selection, by design and as tested. On the real
page this shows "Loading model..." again for about 90 ms right after the
first selection appears. Against an older gateway each such wait lasts
as long as the full provider catalogue read.
- With the remote CLI test change removed,
`test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`
and its cancel sibling keep main's race: they wait for the pid file,
then read the run record that may not be written yet. A parallel local
run of the three RPC files plus that test file on this branch hit it
once. It is the same flake main has today.

Roll back by reverting this change and rebuilding the served web page;
no configuration migration is required.

## Related Issues

Fixes #819

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Dizhan Xue <xuedizhan17@mails.ucas.ac.cn>
2026-10-19 21:50:30 +08:00
Dizhan Xue
1b9cbf85e5
feat(*): let a dag decision node choose which of its branches run (#1001)
## Summary

A sub-agent DAG node can now decide which of its downstream branches
run. Before this, a background run could not turn on a result: every
node ran, and choosing a path meant the host winding the run down and
starting another.

How it works:

- A node that declares `routes` (route name to condition) is a decision
node; `select` is `"one"` (the default) or `"many"`. Raven's per-node
judge, the existing verdict call, picks the route or routes the node's
answer satisfies. The node's own text never selects a route. A route
that cannot be determined fails the node, with no fallback route.
- A downstream node carries `when`, a guard over `<node>.<route>` and
`<node>.done` atoms joined with `not`, `and`, `or` and parentheses,
evaluated with three-valued logic: a route of a decision node that was
never executed is unknown. Every decision node in a node's `depends_on`
must appear in its `when`; such graphs are refused at submission
otherwise, along with guards that can never hold and a route named
`done` in any letter case. Validation keeps negation parity and the
surrounding boolean expression: a double-negated `done` and a
disjunction with a satisfiable arm are accepted, without expanding
disjunctions into combinations.
- A node that does not run is `not_executed`, with a reason:
`when_false`, `when_unknown` or `upstream_not_executed`. A node whose
dependencies all went unexecuted is not executed either; a failed or
skipped dependency still skips its dependents first.
- A merge node reads a missing upstream as a fixed sentence, `<This task
is not executed and the output is missing, please go on without this
output.>`, written outside every untrusted-content fence, plus a note
listing the inputs that may be missing. A file reference to the files of
a node that may not execute is refused at submission however its path is
spelled: `@nodes/`, an absolute path into the node root, or a workdir
path that lands there, symlinks followed. Windows case, separator and
drive-relative aliases are recognized, and the advice keeps the declared
node ID.
- Node judgement is always on: the `subagentDag.verdictEnabled` switch
is retired. Config migration 14 removes it with a notice, and drops it
again on every later load should an older build sharing the config write
it back. `raven playbook run` now judges its nodes too, on the same
`subagentDag` settings and a pinned `verdictModel`'s own provider; with
nobody there to answer, a node judged not to have accomplished its task
fails on the judge's reason. A host with no judge at all refuses graphs
that declare routes.

Where it shows:

- Run events, the manifest, `dag.get`, `tasks.list` and
`dag.run_completed` carry `reason`, `selected_routes` and
`route_evidence` per node, and `routes`, `select` and `when` from the
graph. The instance registry's DAG-node rows (and `InstanceRow`) carry
the outcome too, so a client that reloads before the run finalizes shows
what a branch decided. `TaskCounts.not_executed` is a new counter.
- TUI: a not-executed node shows a hollow marker and its reason in
words; a decision node shows its selection on the node's second line,
and the guard and route evidence in the detail and in `/dag <node>`. The
Agents Overlay and the live agents strip leave not-executed nodes out,
as the backend's agent lists do.
- Web: the desk's tasks tab names not-executed steps and shows the same
fields.
- Playbooks pass the three fields through, namespace guard atoms with
the run prefix, and keep them through compilation.
- The `run_subagent_dag` schema, the DAG orchestration skill and the
docs site (English and Chinese) describe routes, guards and the merge
rule; CHANGELOG has the entries.

A graph with no `routes` and no `when` behaves exactly as before: the
same judge requests, events, records, summary and finish text.
`route_evidence` is a quote the judge picks from the sub-agent's output;
it is cut at 500 characters, keeps a lone surrogate from a malformed
escape as the escape's own text, and never enters model-facing text
(finish text, `dag_status`, exception reports). When a judge answer does
not report a usable route, the judge is asked again at most twice, each
time with one correction. The shared instance registry drops its cache
when a write fails on the data rather than the disk, so a row the file
cannot hold fails its own write and no other.

Two Windows CI steps run the alias and finish-text regressions; the
latter exposes the installed Git `cat` executable required by the
existing fixture.

## Type

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

## Verification

Linux, Python 3.12.13, on this revision rebased onto the current main
(`$CHECKS` is a temporary evidence directory):

```sh
uv run --frozen --no-sync pytest -q -n 4
# 23 failed, 33229 passed, 162 skipped, 1 xfailed, 3 errors
uv run --frozen --no-sync pytest $(git diff --name-only origin/main...HEAD -- tests/) -q -n 4 --idle-ceiling-strict --cov=raven --cov-branch --cov-report=json:$CHECKS/coverage.json
# the 20 test files this branch changes: 2622 passed, 1 skipped (a POSIX permission case that does not apply to root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json "$CHECKS/coverage.json" diff --base-ref origin/main --head HEAD --threshold 90
# Diff coverage: 99.48% (764/768 executable changed lines), passed the 90.00% threshold
```

The full run's 23 failures and 3 errors are 25 tests. 24 of them fail
the same way on the current main in this environment: the venv lacks
`nltk` and `datrie` (16), a proxy is set in the environment (5), this
box has its own `npm` in `/usr/bin` (1 install-script case), LibreOffice
writes no `.xls` here (1), and the run is root (1). The 25th,
`test_a_cli_run_left_on_the_machine_when_this_computer_stops_is_picked_up_by_the_next_start`,
failed with its teardown in the full run and in one of two runs of its
file, and passed in five runs on its own: it reads the remote-run record
the moment its pid file appears, a race in code this branch does not
change (#840 makes that test wait for both). The four uncovered changed
lines are the gateway's `_verdict_provider` body, whose helper is tested
on its own; a guard atom over a node that did not complete, which the
runner never evaluates because it reads a guard only once every
dependency completed or was not executed; and the cut of an over-long
terminal output.

Ruff check and format, `ty check` over the changed modules, the import
contracts, `deptry raven`, commitlint, and
`scripts/check_commit_messages.py`, `check_large_files.py` and
`check_source_language.py` over this branch's commits pass. ui-web:
`vitest run src/features/tasks/BoardCard.test.tsx scripts/gates` passes
50 files and 244 tests, and `tsc --noEmit` is clean. In Chromium a
not-executed title whose first word is wider than the room beside its
status now breaks that word instead of starting under a blank line, and
every other tasks-board card renders pixel-identical, English and
Chinese, light and dark. Firefox still starts such a title under a blank
line and cuts it without an ellipsis. CI's `TUI checks` covers ui-tui.

Mutation checks: removing any one of these makes its own test fail: the
every-load strip of the retired switch, the quote's escape before the
cut, the registry's cache drop, the node-root check in the tool, the
runner and the replan path, the physical path through a symlink, the
CLI's judge, its settings and its no-answer failure, and the pinned
judge provider. A model reading only the DAG skill's catch-all paragraph
answers that without a catch-all route the judge may pick the nearest
route or fail the node; an earlier wording led it to answer that the
graph always stops.

A live run on `openrouter/z-ai/glm-5.3-flash`, two graphs with synthetic
messages, selected the expected route at each decision node, left the
unselected branch `not_executed` with `when_false`, and put the fixed
sentence outside the fences. Earlier revisions of this change passed the
native Windows selections (aliases, finish text, guards; Windows build
26300, Python 3.13.12). The final revision has not been rerun on native
Windows or macOS.

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

Security: sub-agent text stays fenced or out of model-facing text on
every new path. The routes block in the judge request sits after the
last untrusted fence and is labelled as the graph author's; the
missing-output sentence is written outside every fence; `route_evidence`
is bounded and reaches records, events, the registry and the UIs only.
In the TUI, route evidence is drawn through the same path as a node's
error text; neither strips terminal control sequences, which this PR
leaves as it is.

Behaviour changes: a config that set `subagentDag.verdictEnabled: false`
now gets judged nodes; migration 14 removes the key and says so once.
`raven playbook run` judges every node, one more model call per node,
and a node judged not to have accomplished its task fails there instead
of completing. New wire fields are optional except
`TaskCounts.not_executed`, which is always present (0 when nothing
branched). `InstanceRow` gains three optional fields, and a decision
node's registry row now also stores its selection and up to 500
characters of route evidence.

Conditional-artifact validation matches node IDs using the session
namespace's case-insensitive identity on every host, including macOS.
This conservatively rejects case-only spellings even on case-sensitive
filesystems. Separator and drive normalization remain native, and
unconditional file resolution keeps its existing behaviour.

Rollback: revert the squash commit. A config already stamped 14 loads
unchanged on the previous build, since the stamp only gates migrations;
a user who had set `verdictEnabled: false` can set it again there, and a
later build drops it again on load.

## Related Issues

Related, found while building this and not changed here: #998, #999,
#1000. Follow-ups from its review, not changed here: #1008.
2026-10-19 15:17:04 +08:00
江国庆/Forrest
e9b5a5196e
feat(*): pin a details tab in the trajectory view (#989)
## Summary

The trajectory view's details pane opens an entry on the overview, or on
the tab last chosen for that entry, so a reader checking the same aspect
of many steps (relations, usage, parameters) has to pick that tab again
for every step. This adds a pin for the tab:

- A pin button in the details pane's head, just left of the close button
(or "Back to list" when the pane covers the list on a narrow area). It
pins the tab on screen and reads as pressed while that tab is the pinned
one; on any other tab it offers to pin that tab instead, replacing the
previous pin. The glyph is hollow and faint until pressed, then solid in
the colour the selected tab is underlined in.
- Whenever the pane arrives at an entry (a new selection, or the pane
reopened), it opens on the pinned tab if that entry's strip has it.
Otherwise the entry shows what it would without a pin: the tab the
reader last chose for it, or the overview. A reread of the entry on
screen, a tab click or a click on the row already open is not an
arrival, so the reader is never pulled off a tab mid-read.
- The pinned tab carries a small solid pin in the strip, named "Pinned"
so the tab's accessible name says so, which shows what is pinned while
the reader is on another tab.
- On an arrival the selected tab is shown whole. The strip's overflow
arrows appear only after the strip has first been scrolled to the
selected tab, and they take 44 px from it; the keep-in-view step now
runs again when they come or go, so a pinned tab at the far right no
longer arrives half hidden under the right arrow.
- Pins are per conversation. They live in memory, so switching to
another conversation and back always restores them, and they are
mirrored to the browser tab's sessionStorage through the existing
`lib/persist.ts` slot, so they survive a reload. A tab opened fresh
starts with no pin; a duplicated tab, or a page opened from this one
with an opener, starts with a copy, the same as the page's other per-tab
view state.

Key decisions:

- `visibleTabs()` in `detailStore.ts` is now the one definition of the
strip's tabs, shared by the strip and the pin rule, so "the entry has
the pinned tab" and "the strip shows it" cannot drift apart.
- The storage slot has no cap. The default cap of 20 would evict a
conversation's pin while switching back to it still promises the pin.
Each entry is one tab id written only by the reader's click.
- Front end only: no gateway, RPC or Python change. `ui-web/CONTEXT.md`
defines the pinned tab. The three new catalogue entries regenerate the
TUI copy.
- The docs site (`docs-site/docs/webui.md`) is not changed: its
trajectory section is a three-line overview that does not go into the
details pane's tabs, and the button carries its own tooltip. Walk
screenshots were checked locally and are not committed, per the
repository asset rule.

Four commits: the store semantics; the control, the tab mark, the
catalogue entries and the term; the fix that keeps the selected tab
whole once the strip's arrows appear; and a test follow-up that makes
that fix's regression test nudge the strip for real.

## Type

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

## Verification

- `cd ui-web && npx vitest run --maxWorkers=8`: 249 files, 3968 tests
passed. 18 tests are new (12 in `detailStore.test.ts`, 3 in
`Details.test.tsx`, 3 in `Tabs.test.tsx`); the slowest new one takes
27.5 ms.
- In `ui-web`: `npm run gen:check` (240 methods match), `npm run lint`
(0 errors; the 4 warnings are already on main), `npm run type-check`:
pass.
- In `ui-web`: `npm run build && uv run --no-sync python build.py &&
node scripts/check-page.mjs && node scripts/check-css.mjs && node
scripts/check-class-namespace.mjs`: pass.
- In `ui-tui`: `npm run lint`, `npm run lint:rpc`, `npm run lint:i18n`,
`npm run type-check`, `npm test -- --maxWorkers=8` (2106 passed, 13
skipped), `npm run build`: pass.
- `UV_NO_SYNC=1 make check-source-language check-large-files
check-commits`: pass.
- Browser walk of the offline page (`index.html?stub=1`, Playwright with
Chromium): 33 of 33 checks pass. It covers pin and unpin, another entry
opening on the pinned tab, an entry without that tab keeping the tab the
reader chose, a reopened pane, a pinned muted tab, two conversations
each restoring its own pin, a reload, a page opened fresh (no pin), a
page opened with `window.open` (a copy, independent afterwards), and the
narrow overlay, in light and dark themes. A second walk pins `raw`,
`relations` and `overview` in turn and opens all 8 entries for each,
measuring the selected tab against the strip: 11 of 24 arrivals were
clipped by up to 44 px before the fix, none after.
- Mutation checks: restoring the default cap of 20 fails the
25-conversation test; dropping the in-memory pins on a conversation
switch fails the storage-unavailable test; running the keep-in-view step
only on a tab change fails the new arrows test.

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

## Risk

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

- User-visible changes: a pin button in the details head, a pin mark on
the pinned tab, and the tab an entry opens on once something is pinned.
With nothing pinned, the pane behaves exactly as before.
- sessionStorage gains one key, `raven.gui.view.trajectory.pin`, holding
one tab id per conversation that has a pin; unpinning deletes that
conversation's entry. Nothing leaves the page.
- When sessionStorage is unavailable (private mode, quota), pins still
work for the page's lifetime, including conversation switches, but do
not survive a reload.
- Rollback: revert this PR. No data migration; the leftover
sessionStorage key is never read and goes away when the browser tab
closes.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-19 10:36:04 +08:00
Handsome-wzw
edb00f54f5
feat(*): machines tab in the Agent Hub: register, install the node, remove (#983)
## Summary

The machine registry behind a page. The Agent Hub gets a **Machines**
tab:

- every registered machine as a card, with the state of this computer's
link to it (`NodePool.status`) and its Raven node (live version while a
link is up, else the one recorded on the row), and the register card at
the end;
- **Register a machine**: name, id, address, port, user, private-key
path and work directories; the server reaches the machine once (the same
`connection_add.probe` as `raven ops connection add`), writes the row
and its ssh alias, and a refusal comes back with its kind (unreachable,
login refused, changed host key, timeout, no ssh here, duplicate id,
invalid field, registry file) so the page says in the reader's language
what to do, with the server's sentence under it;
- **Install node** / **Update node**: `node_install.plan` + `install`
run in a background task; `machines.list` reports it on the row
(`install.running/ok/detail`) and the page polls until it ends; the
sheet's *Install into* field is the command's `--dir`;
- **Remove machine** (after a confirmation): refused while an agent
entry names the machine (the entries are listed) or agents run on it
over the link; otherwise the row and the managed `Host <id>` block go,
the link is closed, the node on the machine stays;
- **Test link** (`machines.list refresh=true id=...`) and **Check**
(`machines.doctor`);
- a preset's sheet picks where it runs (*Runs on*) among the machines
with this Raven's node, with the working directory there for acp/cli,
and the connect carries `machine` / `remote_cwd` to `subagents.add`.

Nothing a row or a refusal carries is the way onto the machine: no
address, account or key path (the pool's and the probe's sentences are
scrubbed of them).

Also: `raven ops connection remove <id> [--yes] [--force]` as the
command behind the removal; `install-node` and the page record the node
they put on, or found on, the machine as `node_install` on the row,
which is how a listing says a machine has this Raven's node without
reaching it. New RPC group
`machines.{list,add,install_node,doctor,remove}` in the contract, the
Python models and both generated TS clients. Docs: machines guide
(en/zh) sections for the page and the removal, CHANGELOG, CONTEXT.

## Type

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

## Verification

- `pytest -n 6` (full suite): 32094 passed, 174 skipped, 3 failed -- the
same three that fail on main on this Mac (libreoffice absent, two
simulation tests).
- `pytest tests/test_rpc_machines.py tests/test_ops_connection_add.py
tests/test_cli_ops_connection_commands.py tests/test_update_subagents.py
tests/test_rpc_registration.py tests/test_rpc_schema_match.py
tests/test_docs_site.py tests/test_living_docs.py -n 0`: all green (632
+ 18).
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`:
94.29% of changed lines (the uncovered lines are since covered by one
more CLI test).
- `ruff check`, `ruff format --check`, `ty check` on the touched files,
`lint-imports` (10 kept, 0 broken), `tests/test_import_cycle_budget.py`,
`pre-commit run --files ...`: all pass.
- ui-web: `vitest run` 3959 passed (249 files), including the new
machines-tab tests and the five page gates (fixture shape, i18n
namespace, store shape, class namespace, domain registration); `tsc
--noEmit`; `eslint .` (0 errors, 4 pre-existing warnings in
SubagentsPage); `npm run gen:check`; `npm run build` with the boot
golden OK. ui-tui: `gen:rpc`, `gen:i18n`, `tsc --noEmit`.
- Real machine, from the page of an isolated gateway on this Mac (own
RAVEN_HOME, channels off), against one registered ssh machine:
registered through the form (probe + row + alias, no address shown
afterwards), node installed from the sheet (background task, card
reported the end, `node_install` recorded on the row, node directory
present on the machine), link tested (idle), Claude Code connected onto
the machine from its preset sheet with a working directory (entry
`claude_code@ravenx2` written, agent started there by the node), removal
refused while that entry was connected (the refusal named it), and, once
the entry was disconnected from the Connected tab, removed from the
sheet: the row is gone from the registry, the managed `Host` block is
gone from `~/.ssh/config` with the owner's own lines untouched, and the
node directory is still on the machine.
- The tab, the two sheets, the confirmation, a refused register (type
the id `locked`, `down`, `changed` or `slow`) and a refused removal (the
row agents run on) can all be walked through offline: build the page and
open `ui-web/dist/index.html?stub=1`.

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

- Follow-up commit 3248a83cb, after the Windows review: the fixtures
that set `HOME` around the ssh-alias
helpers set `USERPROFILE` too, through `tests/_home.py`, and a test pins
the Windows reading of `~` with
`ntpath` on every platform (it fails against a `HOME`-only fixture). The
three files: 113 passed on macOS;
  native Windows was not run here.
- Follow-up commit e9b150bc6, after the agent review's F1: the suite's
autouse `_no_real_raven_home` sets
`USERPROFILE` beside `HOME` through the same helper, so the two
ssh-alias CLI tests that bring no home of
their own (`store` and `reached` only) stop writing `Host gpu` into the
operator's `~/.ssh/config` on
Windows; `tests/test_conftest_no_real_home.py` pins the Windows reading
of `~` from a test without a home
fixture (red against the `HOME`-only fixture). The Windows reading
emulated on macOS (`os.path.expanduser`
-> `ntpath.expanduser`, outer `USERPROFILE` at an emptied sentinel, over
the three files): the two tests
wrote into the sentinel before, none after. Full suite on this Mac (`-n
6`): 32113 passed, 3 failed, the same three that fail on main here (a
LibreOffice case and two simulation cases). Native Windows was not run
here.
- Merge commit b58a6048d brings in main up to #971, whose family picker
lives in the same ext-agents page
files as the machines tab: five files conflicted (`ExtAgentsPage.tsx`,
its test, `source.ts`, `store.ts`,
`styles.css`), all resolved by keeping both sides. The tab strip counts
cards for the agent tabs
(`entries`, a family counts once) and registry rows for the machines
tab; `connect` carries `model` next to
`machine`/`remote_cwd`; the agent sheet, the machine sheet and the
family picker share the one drawer, so
opening any of the three clears the other two and `sheetDismissed` drops
all three. Checks on the merged
tree: ui-web `vitest run` 3997 passed (250 files), `tsc --noEmit`,
`eslint` on the feature, `gen:check`,
`npm run build` with the boot golden; the offline page (`?stub=1`) shows
the five tabs with their counts
and the machines tab as before; Python: the machines, connection,
contract and subagents files 366 passed,
the full suite (`-n 6`) 32480 passed, 5 failed: the three above plus two
`tests/test_acp_mirasim_uicli.py` cases that fail the same way on a
pristine `origin/main` checkout on this Mac (`mirasim ui-cli agents` did
not answer within 4s).

## Risk

- [x] Security impact considered -- the page never receives an address,
an account or a key path: the row is `connections.shown`-style data, the
probe's and the pool's sentences are scrubbed of the row's host,
user@host and key, and the register form's fields travel once in
`machines.add`. The install's package index stays on the step's stdin as
before. Removal needs a confirmation and is refused while entries or
running agents depend on the machine.
- [x] Backward compatibility considered -- new RPC methods and one new
optional registry field (`node_install`); `install-node` records it as a
warning-only step, every existing row and command keeps working,
`connections.shown` is unchanged.
- [x] Rollback path is clear for risky changes -- revert the commit; the
registry rows keep an extra `node_install` key that nothing else reads.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-17 21:08:46 +08:00
Dizhan Xue
547c1aba5e
feat(*): reach Mirasim's agents as ACP sub-agent presets (#971)
## Summary

Connect the coding agents Mirasim runs as Raven ACP sub-agents, with one
bundled preset per agent and no separate adapter download.

- Serve Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok
  Build, DSH, Pi and ZCode CLI through `mirasim ui-cli`. The adapter
  runs on Raven's interpreter, so a Mirasim preset is not offered on a
  registered machine, and a stored row whose interpreter is gone is
  pointed at the running one when the config is next read. It withholds
  session MCP because ui-cli does not accept per-session servers. The
  boot capability backfill asks Mirasim once which agents it has
  installed and handshakes only those.
- Read model and effort choices from Mirasim. Offer the own models of
  Claude Code, Codex, Kimi Code and ZCode CLI on both their own-account
  and Mirasim platform routes. Persist conversation bindings and switch
  routes before continued turns. A menu read that fails is tried again
  after a short pause rather than kept for the cached copy's lifetime,
  an effort the menus in hand do not offer is read again before it is
  refused, and a failed menu read still reports the agents installed
  since the last one. A connect or test whose handshake could not read
  the menus keeps the ones already measured, and connecting an agent
  with a model refuses one its measured menu does not offer, as editing
  one already did.
- Retain the last model catalog when a refresh fails. Deleting a session
  prevents later writes, prompts, loads and route switches, waits for an
  already-running store write, and does not wait for unrelated catalog
  work. A turn, and its cancel, uses the catalog in hand instead of
  queueing behind another session's read.
- Relay questions and tool approvals through ACP. Content returned by
  another agent retains that agent's redaction policy, including values
  matching Raven's configured credentials. The rule covers Mirasim,
  shared sub-agent records and announcements, delegated tool results,
  A2A replies, logs, main-agent context, live ACP updates and session
  replay. Provenance is decided per result: a tool's declaration admits
  it to carrying another agent's content, and each result that does
  claims it, so a delegating tool's own errors, receipts and status
  lines stay Raven's text under the local scrub, and no result can claim
  provenance its tool never declared. Forwarding through `tool_call`
  carries a result whole for every tool, so a refusal reached that way
  ends the turn as a direct call does. The contract surface version is
  incremented for the added provenance fields. Local tool-result
  protections, outbound credential handling, permission checks and
  untrusted-content fencing retain their existing roles.
- Group unconfigured Mirasim presets into one card. Connect each member
  with its selected model in one write. Missing members open the
  existing installation and recheck flow, and a member whose handshake
  was refused for want of a sign-in is named in the drawer as it is on
  its card. A family whose members sit in two sections of the agents
  page draws one card in each. Narrow drawers keep the agent name and
  place the model and action on a second row.
- Guard command processes and clean up their descendants on
  cancellation, including ones a tool starts in a session of its own
  while the agent ignores SIGTERM: on Linux the guard adopts them as a
  child subreaper, and the process tree is read again before SIGKILL. A
  guard that outlasts its drain no longer replaces the command's own
  error with a shutdown traceback. Stage oversized prompts within the
  full Windows command-line budget, counting the venv launcher's second
  launch, refuse a `mirasim` that resolves to a `.bat` or `.cmd` shim,
  and preserve percent escapes and UNC authorities in file attachments.
  The guard starts without the ACP package, polls its command's exit
  quickly at first and then slowly, and the adapter's stderr log carries
  no local variables.
- Share the existing ACP stdin reader with the adapter, and update the
  integration docs, domain vocabulary, translations and agent-mark
  attribution.

## Type

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

## Verification

Rebased onto current main and reran validation on Linux with Python
3.12.13 and Node 22.23.2. The isolated interpreter resolves this
checkout even when a subprocess clears PYTHONPATH. Existing dependencies
were reused without changing their declarations or lockfile. In the
commands below, `$CHECKS` denotes the temporary result directory used
for the run. Both Python selections use the same
`COVERAGE_FILE=$CHECKS/post-rebase.coverage`.

```sh
uv run --frozen --no-sync pytest tests/test_agent_loop_*.py tests/test_acp_mirasim_*.py tests/test_tool_registry_*.py tests/test_subagent_acp*.py tests/test_subagent_activity.py tests/test_subagent_history.py tests/test_subagent_manager.py tests/test_subagent_probe_state.py tests/test_security_untrusted_context.py tests/test_tool_admission.py tests/test_tool_search.py tests/test_cli_log_file.py tests/test_acp_journal.py tests/test_a2a_client_tool.py tests/test_subagent_mirasim.py tests/test_subagent_probe.py tests/test_subagent_third_party.py tests/test_ui_agent_marks.py tests/test_acp_replay.py tests/test_acp_updates.py tests/test_rpc_console.py tests/test_rpc_system.py -n 0 -x -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml --junitxml=$CHECKS/post-rebase-python.xml
# 2871 passed
uv run --frozen --no-sync pytest tests/test_contracts_*.py tests/test_tool_admission.py tests/test_tool_registry_execute.py tests/test_security_untrusted_context.py tests/test_config_loader.py tests/test_raven_config_tool.py tests/test_rpc_subagents.py tests/test_subagent_name_vocabulary.py tests/test_tool_refusal_continuation.py -n 0 -q --tb=short --show-capture=no --cov=raven --cov-branch --cov-append --cov-report=json:$CHECKS/post-rebase-coverage.json --cov-report=xml:$CHECKS/post-rebase-coverage.xml
# 487 passed, 1 skipped (POSIX directory permissions are not enforced for root)
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $CHECKS/post-rebase-coverage.json diff --base-ref origin/main --head HEAD --threshold 90
# 93.33%, 1594/1708 executable changed lines; passed
```

The full Python suite, `uv run --frozen --python 3.12 --all-extras
pytest -q`: 9 failed, 32315 passed, 176 skipped, 2 xfailed. Each failing
id is then run by id against a clean archive of the merge base, through
the same interpreter and extras and with the imported `raven` checked to
resolve inside the archive; every id that fails here also fails there.

The catalog-only failure and resumed-session deletion regressions failed
before their fixes. Additional tests exercise deletion during catalog
reads, store writes and route lookups. The content-policy tests failed
against the former redaction behavior and now check exact content
through direct calls, tool_call, the main provider, recorded frames,
persisted transcripts and ACP replay. Local file reads and outgoing
credential records remain covered by controls.

In ui-web:

```sh
npm test -- --no-file-parallelism
# 250 files, 3977 tests passed
npm run gen:check
npm run type-check
npm run lint
npm run build
# passed; lint has four warnings in unchanged files
```

Chromium checks used the actual page and styles with synthetic agent
rows. Model selection travels in the connect request; Escape closes only
the picker; missing members reach the download link and Check again. At
390px and 320px the name columns measure 252px and 182px, respectively,
with no horizontal overflow in the drawer. No page errors were reported.

```sh
make check-commits check-large-files check-source-language
# passed
npm run lint:i18n --prefix ui-tui
npm run lint:rpc --prefix ui-tui
# passed
uv run --frozen --no-sync python -m pre_commit run --from-ref origin/main --to-ref HEAD
```

The full-PR pre-commit run passes except prettier (ui-tui), which flags
`src/components/newInstancePicker.tsx` and
`src/components/subagentsHub.tsx`. Both files are byte-identical to
main; running the formatter against their main contents fails too. The
fixes do not touch either file. Commit-scoped hooks for the new changes
pass. Ruff check and format, ty on changed production files, all ten
import contracts, and whitespace checks pass. Every replayed commit
retains its patch, and the PR title and body pass the repository's ASCII
and commit-message grammar checks.

The earlier native Windows verification covers prompt launch limits and
file-URI conversions. This follow-up has no new native Windows, real SMB
or live vendor/provider run.

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

Credential authorization and scope belong at the point where access is
granted. Redacting a later reply cannot revoke access the receiving
agent already has. Under this product policy, Raven preserves returned
content unchanged and leaves redaction decisions to the sending agent.
Credentials an agent includes in its reply can therefore remain in
Raven's retained logs and transcripts.

Agent-returned content is preserved according to the sender's policy
across all supported delegation paths. The adapter returns each reply
when the turn settles rather than streaming it. Short prompts use
command-line arguments; oversized prompts use temporary attachments.
Connecting an agent probes it: with a model chosen, on that model's own
route, so the pick a connect carries is proved before the row is stored;
with none, on the agent's default. Compatibility was originally measured
against Mirasim 0.0.465; older CLI versions have not been verified.

A stored Mirasim row whose interpreter no longer exists is rewritten in
the config file, once, by the first Raven to read the config after that
interpreter is gone. A row naming another interpreter that still exists
is left as written, so two installs reading one config do not rewrite it
back and forth.

Rollback is a revert. Configured Mirasim rows then need removal because
their bundled adapter is no longer present, and until they are removed
Raven refuses to load the config at all: an unknown preset name fails
validation, so the host does not start and the file has to be edited by
hand.

## Related Issues

N/A
2026-10-17 14:31:43 +08:00
Dizhan Xue
ccf1e2d08e
feat(*): let a failed turn's row open to its whole error (#978)
## Summary

A failed turn's Web row can expand to the provider's full diagnostic
text, up to 8,000 characters, while the existing bounded reason stays
unchanged. The optional `full_detail` field travels through the runner,
lane, RPC event and session marker, so live display and replay expose
the same account. Copy includes the expanded account. Quiet runtime
notices use "Show details" instead of the error label.

Failure details and call-record bodies remove known credential shapes
before the final cap. An unterminated private-key block is removed
through the end of the input, including when an earlier scan or call
record cut away its closing armour. Known cut boundaries also remove
incomplete JWTs, vendor tokens, URL passwords and labelled credential
tails; each of those patterns is searched only from behind the run of
its own value's characters that ends the input and the label in front of
it, so the scan stays linear whatever the text holds and still reads a
label gap of any width. The authorization and JWT patterns avoid
repeated backtracking, and the turn path and outer runner reuse the
computed detail. Attachment and lane reads use the base exception's
instance storage, so a foreign read-only property or throwing getter
cannot replace the scrubbed value or swallow the terminal failure event.

The optional fields are mirrored in the RPC schema and both generated
clients. The design document separates this delivery from the subsequent
Turn Continuation feature; Retry still starts an ordinary turn.

## Type

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

## Verification

The automated suites and static/build checks below were re-run after
synchronizing with main, using the existing local dependencies. The
independent behavioral and timing probes were measured before that
synchronization. The last three commits change only
`raven/security/redact.py`, two test files and the design document; on
that final tree the Python suite, the ui-web tests, the type, generation
and lint checks, `ty`, the import contracts, the range gates and
pre-commit were run again, and the ui-web build checks were not, since
none of their inputs changed.

- `uv run --no-sync pytest -q tests/test_agent_loop_failure_text.py
tests/test_llm_call_record.py tests/test_agent_loop_broken_turn.py
tests/test_agent_loop_llm_error_patience.py
tests/test_agent_loop_run_emit.py tests/test_spine_scheduler_lane.py
tests/test_spine_events.py tests/test_rpc_spine.py
tests/test_rpc_schema_match.py tests/test_kernel_budget.py
tests/test_acp_redact.py tests/test_security_untrusted_context.py -x
--tb=short --show-capture=no`: 904 passed.
- From `ui-web`: `npm test -- --no-file-parallelism
src/features/transcript/TranscriptPage.test.tsx
src/state/session/pipeline.events.test.ts
scripts/gates/i18n-keys.test.mjs`: 225 passed.
- From `ui-web`: `npm run type-check`, `npm run gen:check`, `node
../ui-tui/scripts/gen-i18n.mjs --check`, `node
../ui-tui/scripts/gen-rpc-types.mjs --check`, and `node
node_modules/eslint/bin/eslint.js
src/features/transcript/TranscriptPage.tsx
src/features/transcript/TranscriptPage.test.tsx`: passed.
- `uv run --no-sync lint-imports`: 10 contracts kept. `uv run --no-sync
ty check raven evolver agents plugins-dist scripts`: passed. Ruff check
and format check passed on the 20 Python files this PR changes.
- From `ui-web`: `npm run build`, `uv run --no-sync python build.py`,
`node scripts/check-page.mjs`, `node scripts/check-css.mjs`, and `node
scripts/check-class-namespace.mjs`: passed, including both boot
snapshots.
- `UV_NO_SYNC=1 make check-large-files check-source-language
COMMIT_RANGE=origin/main..HEAD`: passed. `PYTHONPATH=. uv run --no-sync
python scripts/check_commit_messages.py origin/main..HEAD`, commitlint
over the same range and `git diff --check origin/main...HEAD`: passed.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref
HEAD`: all applicable hooks passed except the whole-TUI Prettier hook,
which reports `newInstancePicker.tsx` and `subagentsHub.tsx`. Both files
and the formatter config are unchanged from main; an isolated main-file
control with the same locked Prettier version reproduces both failures.
`node ui-tui/node_modules/prettier/bin/prettier.cjs --check
ui-tui/src/i18n/messages.generated.ts`: passed.
- Regression coverage includes truncated private keys, incomplete JWT
and credential tails, terminal-event delivery with foreign exception
attributes, scan reuse and CPU cost, the cut-tail scan's cost on
label-shaped runs and long gaps, its agreement with a whole-text search,
a label gap of any width, the JWT boundary and private-key END rules,
and quiet-notice expansion. The five independent boundary probes passed
before the base synchronization; the committed regression suite above
passed again afterwards.
- On the same 32,267-character synthetic crash input, the queued
event-loop callback delay fell from 15.351 seconds to 0.00951 seconds.
The regression checks use thread CPU time with a 0.5-second ceiling.
- Cut-tail scan: a failed turn whose crash text holds 31,000 spaces
before its last two words took 32.6 seconds while the region came from a
regex search for the last whitespace, and 0.016 seconds now; 64,000
characters of `pwd=` ending in a comma took 10.8 seconds through the
whole-text tail search and 0.003 seconds now, and a 300,000-character
call-record body of either shape takes under 0.3 seconds. These and the
figures below were measured with the machine's load average between 36
and 132. Across 3,728 timed texts, every label or prefix unit repeated
to 64,000 characters behind a cut and to 300,000 past the scan cap, the
slowest measured alone took about 0.2 seconds against about 0.1 seconds
on the base revision, and a text past the cap takes the same time at
twice the size. Searching the whole text again turns six timing cases
red; a smaller name room, a skipped gap or scheme step, or any value
class narrowed below its pattern's turns the property or gap test red,
as does removing the JWT boundary or restoring the END-only private-key
rule. On 12,008 generated texts with gaps up to 5,000 characters, the
output equals the whole-text version's.
- Chromium with synthetic local data: full text retained and HTML
escaped, expanded tooltip removed, internal scrolling and Retry
preserved, neutral notice label displayed, no page errors. No live
vendor call or native Windows rerun is claimed for these fixes.

- [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: the long text is scrubbed of
recognized credential shapes before persistence and publication. It
remains diagnostic text and may contain hostnames or paths. Model
history and chat-channel replies keep their existing bounded content. A
session export can include the long text. `raven.security.redact` is
also the scrubber for every ACP surface (tool titles, result previews,
permission prompts, replay, error messages) and for the outbound
client's permission log, so two of its rules reach those surfaces too: a
private-key header without END hides the rest of that text, and a JWT
glued to a preceding word character, such as `/verify-eyJ...`, is left
unredacted. Tests pin both.
- [x] Backward compatibility considered: the new fields are optional,
older markers fall back to their bounded reason, and the TUI can ignore
the extra field. Incomplete private-key blocks are conservatively
removed to the end, which can also omit trailing diagnostic text. Custom
runners attach long details in the exception's instance dictionary;
descriptors are ignored.
- [x] Rollback path is clear for risky changes: revert the squash
commit. Older code ignores the optional marker field.

## Related Issues

N/A

---------

Co-authored-by: Codex <noreply@openai.com>
2026-10-17 14:28:35 +08:00
Dizhan Xue
3c5b47421d
fix(*): offer the host's folder dialog only where the gateway has one (#970)
## Summary

The working-directory picker used a loopback URL to decide whether to open
the gateway host's native folder dialog. A headless gateway reached through
VS Code port forwarding, SSH, Docker or WSL can also appear at localhost,
so choosing a folder failed instead of opening the in-page browser.

- The gateway announces `folder-dialog-v1` in `system.hello` when it knows a
  native dialog command: macOS and Windows, or Linux with zenity/kdialog on
  PATH and `DISPLAY` or `WAYLAND_DISPLAY` set.
- The page offers the native picker only when the gateway announces that
  capability and the page is served at a loopback address. Otherwise it
  browses the gateway's folders through `fs.dirs`.
- After a reconnect handshake, an open folder menu redraws so its label
  follows the new capability list. The staged directory and popover state
  are preserved; the label and click action stay in step in both directions.
- Dialog detection lives in a stdlib-only module shared by the handshake
  and filesystem handlers, avoiding an import cycle.

## Type

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

## Verification

Linux, Python 3.12, after rebasing onto current main. Commands below ran
against the final code; build and browser checks used an isolated archive.

- `uv run --no-sync pytest tests/test_rpc_console.py tests/test_rpc_system.py tests/test_import_cycle_budget.py -q -x -n 0 -p no:cacheprovider --basetemp <isolated-directory>`:
  233 passed.
- From `ui-web`, `node node_modules/vitest/vitest.mjs run --no-file-parallelism scripts/gates src/app/install.test.ts src/state/workdir.test.ts src/rpc/capabilities.test.ts src/rpc/wsTransport.test.ts src/rpc/fixtureTransport.test.ts src/state/session/registry.test.ts src/state/session/runtime.streams.test.ts`:
  54 files, 336 passed, 0 failures or unhandled errors.
- From `ui-web`, `node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json`,
  `node node_modules/eslint/bin/eslint.js .` and
  `node scripts/gen-rpc-client.mjs --check`: passed; ESLint has 0 errors and
  4 existing warnings in unchanged files.
- From `ui-web`, `node node_modules/vite/bin/vite.js build`,
  `uv run --no-sync python build.py`, `node scripts/check-page.mjs`,
  `node scripts/check-css.mjs` and `node scripts/check-class-namespace.mjs`:
  passed, including both boot snapshots.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD`,
  `UV_NO_SYNC=1 make check-large-files check-source-language check-commits`
  and `uv run --no-sync lint-imports`: passed; 10 import contracts kept.
- Both new reconnect cases failed before the fix. Removing the redraw or
  moving it before the handshake made both cases fail again, without
  unhandled errors. The fixed source was restored after each probe.
- Real Chromium against an authenticated, isolated gateway exercised the
  actual handshake and filesystem RPC handlers. Headless browsing selected
  a folder two levels down; a controlled native-command stand-in returned
  the chosen folder. Keeping the menu open across capability loss and gain
  updated its label and called `fs.dirs` and `fs.pick_dir`, respectively.
  All four scenarios had no page errors. Unrelated RPC answers were fixtures;
  interactive macOS/Windows dialogs were not exercised in this run.

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

Existing wording is reused; no user-facing documentation change is needed.

## Risk

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

The capability remains an optional string in the existing handshake list;
authentication, directory validation and the RPC schema are unchanged.
Older pages ignore the capability. A newer page with an older gateway uses
the in-page browser. The terminal UI does not consume this capability.

The announcement identifies an available command and, on Linux, a display
environment; it does not verify that a display server is reachable. A remote
desktop reached through a forwarded port can still open its dialog on the
remote screen. Revealing files and opening external applications still use
the existing loopback-address check and are outside this change.

Rollback: revert the squash commit.

## Related Issues

N/A
2026-10-16 14:25:18 +08:00
Dizhan Xue
b5110646f9
fix(ui-web): let the desk palette reach down to the composer card (#980)
## Summary

The desk palette (the floating palette hanging under the launcher at the
chat's right edge) stopped at a fixed 480px height, set twice: in
`ui-web/src/features/desk/geometry.ts` and as the stylesheet's
max-height. Pulling its corner down therefore ended wherever 480px
happened to land; in an ordinary window that is level with a message
bubble and well short of the composer below it.

The lowest the palette's bottom edge goes is now the composer card's
bottom edge, measured when the geometry is clamped (`deskBottomLimit`).
Where no dock is drawn, as on an imported conversation, the window's 8px
gutter is the limit, as before. The width keeps its 480px cap, renamed
`DESK_MAX_WIDTH`.

Where the composer card runs under the anchored palette's column,
reaching the card's bottom edge would put the palette on the field and
the send button. That happens on the landing page, which keeps the dock
free of the reserve's inset, and in a chat too narrow for the reserve.
There the anchored palette stops 12px above the card's top edge
(`DESK_COMPOSER_GAP`). A detached palette keeps the bottom-edge limit
wherever the reader put it.

That stop limits what is drawn, not the height the reader sets. The card
moves without the palette rendering: it grows upward with a long draft,
and slides under the palette or out from under it as the reserve comes
and goes. So `DeskPalette` measures how far the anchored palette may
reach (`anchoredRoom`) whenever the dock's box changes or the window
resizes, and draws the lesser of that and the stored height. A visit to
the landing page or a long draft takes nothing from a tall palette; the
height comes back once the card moves away. A resize starts from the
drawn height, and letting go stores what was drawn, so a pull past the
stop does not grow back by itself later.

Two related changes:

- Resizing holds the top edge. Left to the clamp, a detached palette
pulled past the limit climbed instead, its top edge moving up while the
hand pulled down; the 480px cap bounded that before, and without the cap
it would be unbounded.
- Moving a detached palette down stops at the composer card's bottom
edge rather than 14px below it at the window gutter.

Four comments explained the reserve's inset by the palette never
reaching the composer: the `deskReserve` docstring, two in `page.css`
and one in the reserve gate. Each keeps its measurement, scoped to the
default height, and says what the inset does once the palette is pulled
down. A new gate, `ui-web/scripts/gates/desk-height-css.test.mjs`, pins
that the stylesheet caps the palette's height by the window alone, since
happy-dom applies no stylesheet and no rendering test can see a fixed
cap there. The existing test `opens larger than it can be shrunk to, on
both axes` loses its default-height-against-the-cap line, as there is no
fixed height cap left to compare against; its width and minimum lines
stay.

## Type

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

## Verification

Run from `ui-web/` at the head of this branch:

- `npx vitest run src/features/desk/ scripts/gates/`: 56 files, 463
tests passed.
- `npx vitest run --maxWorkers 4` (whole suite, both test roots): 249
files, 3946 tests passed, no unhandled errors.
- `npx tsc --noEmit -p tsconfig.json`: clean.
- `npx eslint .`: 0 errors; its 4 warnings are in `ConnectionsPage.tsx`,
`CronPage.tsx` and `SubagentsPage.tsx`, which this change does not
touch.
- Every new test was seen to fail, either before the code it covers
existed or under the mutation it guards. 21 single-construct mutations
of the change each fail a test written for them, among them the bottom
limit, the column test and its edge-to-edge boundary, the gap's sign,
the room at the palette's own width, the drawn height, the resize
starting from the drawn height, the store on release, the detached
exemption, the dock observer (and observing the chat instead), the
window listener, the 480px stylesheet cap, the held top edge and the
move bound.

From the repository root: `scripts/check_source_language.py
origin/main...HEAD`, `scripts/check_large_files.py origin/main...HEAD`,
`scripts/check_commit_messages.py origin/main..HEAD` and commitlint on
each commit pass, each beside a control that fails; `pre-commit run
--from-ref origin/main --to-ref HEAD` passes and modifies nothing.

In Chromium, served with the offline fixtures (`index.html?stub=1`) at
1508x749 unless noted, pulling the corner all the way down:

- conversation: the bottom edge ends at y=727, the composer card's
bottom edge (before: 534, height 480, 193px short);
- landing page: 583, 12px above the card's top at 595, send button
clear;
- conversation at 1100x749, where the reserve stands aside: 583, clear
of the card;
- pulled down in a conversation, then New task, then back: 727, 583,
727;
- 1100x749, an eight-line draft: the card's top moves 595 to 439, the
palette 583 to 427, and both return when the draft is cleared.

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

No user-facing documentation describes the palette's height, so none
changes.

## Risk

User-visible: the palette can be pulled taller; resizing a detached
palette no longer moves it up; a detached palette moved down stops at
the composer card's bottom edge, 14px higher than before; and where
widening the palette makes the reserve stand aside and the composer
slides under it, the palette's drawn height drops to stop above the
card.

Left as they are:

- Shrinking the window still lowers the stored height, and growing it
back does not restore it, as before this change; only the composer's
stop is kept apart from the stored height.
- A sheet docked above the composer (a question or an approval card) is
not part of the limit, so where the card runs under the palette, the
palette can still reach over a tall sheet.
- The `.desk-palette[data-anchored="true"]` comment in `page.css` names
the placement's file as `deskGeometry.ts`; it is `geometry.ts`. Not
touched here.

The stored geometry keeps its localStorage key: a height stored before
is clamped by the new limit when the palette is next drawn, and an older
build reading a taller height clamps it back to 480. Rolling back is
reverting this commit.

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

## Related Issues

N/A
2026-10-16 14:01:44 +08:00
江国庆/Forrest
c18278b8af
feat(*): import exported and reported conversations to read on the web page (#960)
## Summary

The web page can now import a Trajectory Export, a Bug Report Package or
a trajectory report and read it as a read-only conversation, transcript
and trajectory both. It is meant for developers reading a bug report
they received, and for looking at a conversation from another machine.
It builds on #948 (export package v1, the trajectory view on by default,
and the conversation menu's availability predicate).

- **Import store** (`raven/trajectory/imported_package.py`,
`imported.py`). Three kinds are accepted: a `raven_trajectory_export` v1
export, a `bug_report_package` v1, and a `raven trajectory report`
tarball. A file that is not gzip is "not a package Raven can import", an
unknown version asks for an update, anything else is "damaged or
unsafe". Packages are unpacked member by member on `package_check`'s
bounded layer, with one budget shared by both layers: 100 MiB per
package, 1 GiB unpacked for an export and 256 MiB for the report kinds,
100k members; traversal, absolute names, backslashes, symlinks, hard
links, devices, FIFOs, sparse members, repeats, directories with data
and oversized extended headers are refused, and every file is created
with `open(..., "xb")`. The package's session record is held to 32 MiB
and 50,000 records before anything reads it (the import and every open
load it whole), or the package is refused as `transcript_too_large`. The
result is normalized into one trace store: export v2 shells stay as they
are, report v1 model inputs become v2 shells that resolve to exactly the
original payload (so long conversations read whole), and a pointer that
maps to nothing in the package becomes null and reads as not recorded.
Each import lives in `<raven home>/imports/<uuid>/` with a `meta.json`
(source file name, import time, title, kind, sha256); it is unpacked
under `.staging/` and renamed into place, removed whole on failure or
cancel, and stale staging is swept at startup. Default titles: an export
takes the original conversation's title or its first user input, a bug
report the first line of its description or its report id, a trajectory
report the original title or its id. One import runs at a time on a
dedicated worker thread that owns the slot; there is no queue, a closed
page does not free the slot early, and gateway shutdown stops and waits
for it.
- **RPC and server-side guard.** New `imported.upload` (base64, under
the same 100 MiB limit as `fs.upload`) answers `imported` or `duplicate`
(by sha256), and imports another copy with `force`. New error codes:
-32029 `imported_read_only`, -32030 `imported_package_invalid`
(`data.reason` carries a stable refusal code), -32031 `imported_busy`.
An Imported Conversation's key is `imported:<uuid>`. `session.list`
appends imported rows when asked for the `imported` channel (never in
the archived list); `session.resume`, `session.title` and
`session.delete` read and write `imports/` directly and never touch the
SessionManager. A dispatcher guard allows only a vetted list of read
methods on an imported key (any of the four session parameter names, or
`channel: imported`) and refuses every other method with -32029,
including methods added later. The SessionManager refuses to save or
fork an imported key and `/file` answers 404 for one, so an imported
conversation never lands in `<workspace>/sessions/`. The trajectory
methods read an import from its own trace store; the indexer registry
gains an LRU cap (four foreign stores), idle eviction covers every
indexer, and deleting an import drops its indexer.
- **Web page.** "Import conversation" in the left menu picks a file and
uploads it; while it runs the button shows the file name and is
disabled, every refusal has its own message, and a repeated package
offers "Open existing" or "Import anyway" (the confirm dialog gains an
optional second action). An "Imported" group below Recent (hidden when
empty) lists the imports with only Rename (inline) and Delete, and the
source file name in the tooltip; search mode matches, and "delete all"
in settings leaves imports alone. An open import is read-only: no input
box (and no transcript mask left behind for it), no title editing in the
header, no Branch, the conversation menu hidden with its slot kept, no
working-directory tag. Sub-agent panes, DAG runs, attachments, delivered
files and generated images show as unavailable without sending requests
the server would refuse; a package without a transcript says so and the
trajectory view still opens; `[REDACTED:...]` placeholders are shown as
they are.
- **Docs and tests.** The webui page (English and Chinese) gains "Import
a conversation"; `CONTEXT.md` (Imported Conversation) and
`ui-web/CONTEXT.md` define the term. Unit tests cover every refusal of
the unpacker, normalization, meta and titles, duplicates and `force`,
runner admission and cleanup, the guard (checked against every
registered method), and the imported branches of `session.*` and
`trajectory.*`; vitest covers the import entry, the rail and the
read-only mode. A new integration test imports packages made by the real
writers into a second raven home and reads them back, and covers
duplicates, rename, delete, refused writes, and damaged or hostile
packages (an oversized upload and a decompression bomb built at the
shipped limits).

## Type

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

## Verification

- The branch merges the current `main` (merge commits, no conflicts; the
generated RPC bindings and i18n catalogue still match their sources);
everything below ran on the merged tree unless noted.
- `uv run pytest tests/ -q` (full suite): 10 failed / 31918 passed / 188
skipped. All 10 (proxy environment, IPv6 prefix resolution, node
runtime) also fail on `main` on this machine; none is introduced by this
branch.
- `uv run pytest -m integration
tests/integration/test_imported_conversation_e2e.py
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_web_bugreport_e2e.py -q`: 16 passed.
- Changed-line coverage over the feature's tests (before the merge),
`scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`:
97.75% (955/977).
- `uv run ruff check`, `uv run ruff format --check`, `make
lint-imports`, `make lint-types`: pass.
- ui-web (the merge touches no frontend, i18n or RPC contract file):
`npm run gen:check` (240 methods), `npm run lint`, `npm run type-check`,
`npx vitest run` (248 files / 3923 passed), `npm run build` and `python3
ui-web/build.py` (both boot snapshots match), `check-page.mjs`,
`check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint`, `npm run lint:rpc`, `npm run lint:i18n`, `npm
run type-check`, `npm test` (144 files / 2111 passed), `npm run build`:
pass.
- `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`:
pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium against a real gateway (`raven web --foreground` on
a fresh raven home, at 1280 and 360 px): imported a real export and a
real bug report through the page, opened both read-only, read a
122-message model input to its end in the trajectory view, used both
duplicate choices, renamed and reloaded, deleted, and uploaded a text
file; no page errors. The same flow on the built page with offline
fixtures.

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

## Risk

- `imported.upload` takes untrusted archives. The unpacker is bounded
and refuses unsafe members, the guard is an allow-list, and the
SessionManager refuses imported keys as a backstop; the import directory
is under the raven home, which `fs.*` and `/file` already refuse to
serve.
- An export is not redacted, so importing someone else's export gives
you its raw contents; the docs say so.
- Two processes sharing one raven home (for example `raven serve` and
`raven web`) do not see each other's import slot, so importing the same
package in both at once can leave two copies; the extra one can be
deleted.
- Rollback: revert the squash commit. Imported data stays in `<raven
home>/imports/`, which older versions ignore and which can be removed by
hand.

- [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-10-16 06:54:34 +08:00
Handsome-wzw
a71b488e6f
feat(*): show the registered machine on the page's agent cards and the TUI's rows (#958)
## Summary

An agent entry that names a registered machine (`machine` on an acp, cli
or openai row) ran there without the page or the TUI saying so:
`subagents.list` already carries `machine` on every row, and both
clients typed it, but neither drew it.

- **Page, agent cards** (`ui-web/src/features/extAgents/`): a card whose
row runs on a machine carries a small chip -- a monitor glyph and the
machine's registry id -- at the head of the line about the agent, with
the tooltip "On the registered machine {id}". It leads that line rather
than sitting on the name row, which is too narrow on a card to carry
both the name and the id whole. The wizard's agent rows (`SectionBlock`,
a wider layout) carry the same chip after the name. The whitelist mapper
`extAgentRowOf` now carries `machine`; a row that runs here, or a server
that predates the field, draws nothing new.
- **TUI, sub-agent hub** (`ui-tui/src/components/subagentsHub.tsx`): the
row's name column gains the id as a third field, after the preset and
separated the way the name and the preset already are.
- **TUI, new-instance picker** (`newInstancePicker.tsx`): the kind
column gains the id after the kind the same way. Its name and kind
columns are now fixed (`flexShrink={0}`, `truncate-end`): a box shrinks
by default, and the default name of an agent on a machine,
`<preset>@<machine>`, was long enough to be folded onto a second screen
line by a long description.
- One catalogue entry, `gui.agent.on_machine`, in both languages; the
TUI's generated catalogue regenerated. The offline fixture library gains
one row on a machine, so the fixture-shape gate's "never sent" list
drops `machine`.

What is shown is the machine's registry id, the name given at `raven ops
connection add` and the only thing the row carries: the address, port,
user and key stay in the registry, as the Machine entry in CONTEXT.md
requires. No RPC contract change.

## Type

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

## Verification

macOS, Node.js 22, Python 3.12, from a worktree on current `main`.

- Tests first, on the code before this change: the six new cases fail
there (`ExtAgentsPage`, `AgentsBody`, `source` on the page;
`subagentsHub` x1, `newInstancePicker` x2 in the TUI) and pass with it.
- `ui-web`: `npm run type-check`, `npm run lint` (0 errors, the 4
warnings are main's), `npm run gen:check`, `npx vitest run` -- 246
files, 3871 tests; `npm run build` + `python ui-web/build.py` -- boot
snapshot OK.
- `ui-tui`: `npm run type-check`, `npm run lint` (0 errors), `npm run
lint:i18n`, `npm run lint:rpc`, `npx vitest run` -- 144 files, 2114
tests.
- `pytest tests/test_i18n_sensitive_notes.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py tests/test_config_self_surface.py` -- 141
passed.
- Real browser: a gateway started from this worktree on its own home and
port, with one acp row on a registered machine beside the ordinary rows;
the agents page draws the chip on that card only, and the console is
clean. The TUI's two panels were rendered through their own renderer
with the same rows.

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

Display only. The id is the one value the row already carried; nothing
from the registry beyond it reaches a client. A server that predates the
field sends nothing, and both clients draw the rows as before.

## Related Issues

N/A

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-15 21:05:46 +08:00
Dizhan Xue
74614a4f14
fix(*): let raven's own agents be disconnected, and keep the switch through edits (#961)
## Summary

Raven-Code and Raven-Research could not be disconnected: the web sheet
and the onboarding rows hid Disconnect for any `vendored` row, and the
TUI filed them as un-added presets ("is only a preset - press Enter to
add it"). The rule keyed on how a row is stored, not on whether it is
the built-in loop, so Raven-Design and Raven-Oncall, which an install
can register as config rows, could be disconnected while the other two
could not.

What changes:

- Web: every row but the built-in loop can be disconnected, from the
sheet and from the onboarding rows. This reverses the rule #751
introduced for the onboarding walk (Raven's shipped specialists were
never disconnected); a reader can now take one of Raven's own agents off
the roster, the way the server already allowed.
- TUI: a discovered agent is filed with the configured agents (`[on
]`/`[off]`, not `[new]`), space switches it, 't' tests it by `source:
"vendored"` (it sent `"preset"`, which the server answers with "no
preset sub-agent"), and Enter opens the edit form (it opened an add
form, which the server refused as an unknown preset).
- Onboarding step: Raven's own agents are grouped and counted by
ownership (`isOwnRow`), not by `vendored`, so a specialist an install
registered as a config row no longer counts as an external agent or
marks the step done.
- Server, switch rows. Measured before this change: after
`subagents.toggle` switched a discovered folder off, `subagents.list`
reported it as `configured: true, vendored: false, own: false`, because
any config row of its name made it a config row, the switch row
included. The TUI then offered a delete, which dropped the switch row
and put the agent back on the roster past the enable gate, and a Test by
`source: "config"` was handed the switch row, whose command is empty. An
edit was written onto the switch row and never reached the table, and a
rename moved the switch off the folder, which also re-enabled the agent.
Now:
- `subagents.list` keeps a switched-off folder discovered. A switch row
is told apart by `_is_switch_row`, the predicate `subagents.toggle`
already uses; a real override (an `install.py` row, a hand edit) still
lists as config.
- `subagents.update` on a folder whose stored row is only the switch
stores the folder's entry with the change and keeps it off, refuses a
rename there, and writes nothing for an edit that changes nothing (a
form saves every field, and a stored copy would outlive the manifest it
was taken from).
- `subagents.remove` of a folder's row that is off leaves the switch row
behind, so the agent stays off; removing a switch row removes nothing;
an override that is on is dropped whole as before.
- `CONTEXT.md` (Discovered agent) and `ui-tui/CONTEXT.md` (Subagents
Overlay) describe the switched-off and edited states.

Existing assertions that encoded the #751 rule were flipped, not
deleted: the onboarding row of a shipped specialist had no control (two
tests), and its sheet offered Test only. They now expect Disconnect.

## Type

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

## Verification

Measured on `origin/main` 916761ed4; the branch is rebased onto the
current main before it is pushed.

- `uv run --frozen --python 3.12 --all-extras pytest -q` (proxy
variables unset): 31691 passed, 164 skipped, 2 xfailed, 4 failed. The
four are environment-dependent on this box and unrelated to the change:
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
`test_knowledge_parser_excel.py::test_a_legacy_workbook_is_converted_and_read`,
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(fails as root), and
`test_cli_agent_commands.py::test_an_empty_message_file_is_a_usage_error`
(the CLI's boxed error message is cut short under the longer xdist temp
path). Run on their own with `-n 2`, the same four give 3 failed / 1
passed both on `origin/main` (extracted with `git archive`) and on this
branch.
- The six test files that drive `subagents.update`, `subagents.remove`
or `subagents.toggle`: 590 passed.
- New server tests (8), on a real `agents/` tree: a switched-off folder
still lists as discovered; a written override still lists as config; an
edit while off lands and stays off; a rename while off is refused; an
edit that changes nothing stores nothing, on or off; removing an off
override keeps it off; removing an override that is on drops it whole;
removing a switch row removes nothing. The six that cover new behaviour
were red before their fix; the other two guard what had to stay as it
was. Six single-construct mutants of the server change were each killed
by at least one of them (switch rows ignored by update, the no-op skip
dropped, remove always dropping the row, remove treating a switch row as
an override, an edit while off turning the agent on, remove keeping a
"no" for a row that is on).
- `ui-web`: `npx tsc --noEmit -p tsconfig.json` clean; `npx eslint
src/features/extAgents/` clean; `NODE_OPTIONS=--localstorage-file=<file>
npx vitest run --no-file-parallelism`: 246 files, 3872 tests passed, no
unhandled errors (the second test root under `scripts/gates`, including
the import-direction gate, is part of that run). The wizard grouping and
`isFound` were each reverted on their own, and the new tests went red.
- `ui-tui`: `npx tsc --noEmit -p tsconfig.json` clean; eslint on the
changed files clean; `src/__tests__/subagentsHub.test.tsx` 110 passed.
The full suite (`npx vitest run`): 2092 passed, 13 skipped, 11 failed.
Nine are in four files that fail on this box because the suite resolves
`@hermes/ink` to an older local build that has no `dumpScreen`, and none
of them imports the code this branch changes; the other two (the
`subagentsHub` test "'d' then 'n' does not trap the overlay" and an
`agentsOverlayComposer` steer test) failed under load and pass 5 of 5
when their files run alone.
- The sheet's Disconnect / Connect round trip for Raven-Research was
clicked through in Chrome on the offline stub data; the change was not
driven against a running Raven gateway.
- `ruff check` and `ruff format --check` clean;
`scripts/check_source_language.py`, `scripts/check_large_files.py` and
`scripts/check_commit_messages.py` over `origin/main..HEAD` exit 0, each
beside a control that fails; `commitlint` passes each commit message.

- [x] Relevant tests pass locally (the four Python failures above are
this box's; run alone, they give the same result on `origin/main` as on
this branch)
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
(`CONTEXT.md` and `ui-tui/CONTEXT.md`; no user documentation states the
old rule)

## Risk

- [x] Security impact considered: an edit to a switched-off folder now
stores the folder's entry in the config file. A discovered entry carries
no `env` and no key (checked for the five that ship), and credentials
stay in each folder's own `.env`, so nothing secret is copied.
- [x] Backward compatibility considered: the wire shape is unchanged. A
switched-off folder now lists as `vendored: true, configured: false`,
which is what the `vendored` field description already promised, and
which the web client already draws as a discovered row that is off. Rows
an older install wrote stay readable: a switch row, an override and a
stale definition are all shapes the table merge already handles.
- [x] Rollback path is clear for risky changes: revert the squash
commit. Config rows written meanwhile (switch rows, overrides of a
folder) remain valid for the previous code.

Checked and deliberately left as they are:

- `raven onboard`'s prune of rows that shadow a folder lists a switch
row as one of them, flagged "removing it would re-enable this agent". It
asks first and backs up the list, so this change leaves that flow alone.
- A stored definition whose launcher is gone or whose kind changed still
lists as config, while the table merge uses the folder.
`subagents.toggle` treats it as an override too; separating the two is a
separate change.
- An edit turns a discovered agent's row into an override, so the last
test result, kept per source, is not shown again until the agent is
tested.
- The TUI edit form still lets a discovered agent's name be typed; the
server refuses the rename and the form shows its message.
- `/subagents test <name>` in the TUI always sends `source: "config"`,
so it cannot test a discovered agent; the slash command has only a name
to go on.
- The wire `own` flag is false for a config override of a discovered
folder unless its acp handshake named raven. The web falls back to its
agent catalogue, which names four of the five specialists, so an edited
Raven-PPT may show as an external agent there.

## Related Issues

N/A
2026-10-15 14:39:01 +08:00
江国庆/Forrest
2a139f8fbf
fix(*): show bug report values in full and give the wizard room (#952)
## Summary

Follow-ups to the web bug report wizard from #948, after trying it.

- **Decisions page lists the values in full, and only them.** The left
column showed each value masked (`544e***5100`) with its category,
count, decision and links under it. The reader decides on the value
itself, so the list now holds the values and nothing else, each in full
and wrapping rather than cut. `bugreport.status` carries a new `value`
field beside `masked_sample` for each item while the report waits on the
decisions; no other phase carries one. A confirmed item (a private key)
keeps no value of its own, since it is replaced whatever the reader
says, so it shows its replacement. The picked value's category, count,
decision and links, and a confirmed item's acknowledgement, move to the
right column's header; a redacted value is struck through in the list.
- **More room.** The wizard's dialog grows from min(640px, 94vw) x
min(560px, 88vh) to min(960px, 94vw) x min(720px, 90vh), close to the
settings dialog, and the decisions page's two columns fill it instead of
a fixed 360px.
- **Clipped fields.** The severity select and the file name and reporter
fields inherited the page-wide field rule's fixed 32px height and
monospace face, which cut off part of their text. The wizard's sheet now
sizes and sets them.
- **Completeness off the page.** The upload page no longer shows the
completeness verdict. It stays in both JSON files of the report
(`record.json` and the package's `bugreport.json`), for command-line and
web reports alike, and a new test pins that for both paths.

Why some web reports come out `unreplayable` is not addressed here; it
is tracked separately.

## Type

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

## Verification

- `uv run pytest tests/ -q` (full suite): 57 failed / 31566 passed / 177
skipped. The 57 are the same set, one for one, as on the tree #948
merged, where each also fails on `main` (environment-specific on this
machine, pre-existing); none is new.
- `uv run pytest tests/test_rpc_*.py tests/test_trajectory_*.py
tests/test_cli_trajectory_commands.py -q`: 4423 passed.
- `uv run pytest -m integration
tests/integration/test_web_bugreport_e2e.py
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed.
- `uv run ruff check`, `uv run ruff format --check`, `uv run ty check`
on the changed Python: pass.
- ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run
type-check`, `npx vitest run` (246 files / 3869 passed), `npm run build`
and `python3 ui-web/build.py` (both boot snapshots match),
`check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium on the built page (offline fixtures), at 1440 and
390 px: the dialog is 960 x 720 at 1440 px and 367 x 684 at 390 px; at
both widths the select and both text fields are 38px tall in the body
face at 14px, the decisions list shows only the full values, the right
header shows the facts and the acknowledgement, and both columns stay
inside the dialog.

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

## Risk

- `bugreport.status` now sends the values being decided in full while a
report is in the decisions phase. They already reached the page through
`bugreport.item`'s contexts; the status is not polled in that phase,
travels only between the local gateway and its page, and carries no
value in any other phase. A private key is never sent, only its
replacement.
- `BugReportItem` gains a required `value` field. The only client is
this page, regenerated in the same change.
- 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-10-15 12:06:34 +08:00
江国庆/Forrest
6b938a4267
feat(*): export conversations and report problems from the web page (#948)
## Summary

The web page gains two things a conversation could only get from the
terminal before: exporting the selected turns as a download, and
reporting a problem through the bug report pipeline. The trajectory view
is now on for everyone.

- **Trajectory view without `--dev` (R0).** `raven`, `raven web`, `raven
serve` and `raven gateway` no longer take `--dev`; the trajectory policy
starts enabled. `raven tui --dev` (running the TUI from source) is
unchanged.
- **Turn selection.** From this version each turn's opening user message
records its trace id (the Turn Trace Mark, never sent to the model).
`raven/trajectory/selection.py` lists a session's main-line turns,
closes a selection over the sub-agent and delegated traces it
dispatched, collects their spans, and cuts the session record down to
the selected turns; older records are matched conservatively and an
unmatched turn stays in the trajectory only.
- **Export.** The Trajectory Export package v1 (`schema:
raven_trajectory_export`, `format_version: 1`) is the input contract of
the coming `web-traj-import`; it is defined in `CONTEXT.md` and pinned
by tests. It holds the raw spans, artifacts and v2 message blobs of the
selected traces plus the cut session record, unredacted. Exports run as
background jobs (at most two) and the browser downloads them from the
same-origin `/trajectory/export/download` route with a one-time token.
New RPCs: `trajectory.turns`, `trajectory.export`,
`trajectory.export_status`, `trajectory.export_cancel`.
- **Bug reports.** `freeze_export` is split into staging and finishing
so a report can be prepared from selected turns; the CLI's behaviour is
unchanged. A Report Session holds a web report in the gateway between
page requests: at most two at once, all blocking I/O on worker threads,
a cancel checked after every step (a report cancelled while packaging is
never sent), a failed or uploaded report releases its slot and keeps its
last status for ten minutes, and an idle one is cancelled after thirty
minutes. Seven `bugreport.*` RPCs, the `bugreport-v1` capability
(announced only while the receiver URL is valid), and error codes -32026
/ -32027 / -32028. Every decision made on the web page, defaults and
bulk buttons included, is remembered in the redaction history with `web`
as its source, unlike the CLI's bulk flags.
- **Web page.** A three-dot conversation menu in the header's corner
(the desk launcher moves one slot in) opens the new `export` wizard.
Export: pick turns, name the file under an "unredacted" warning, follow
the job, download once automatically with a link to download again.
Report a problem: pick turns, describe the problem, decide the uncertain
values in two columns (hits highlighted at code points), upload, and get
a receipt. Closing before the upload starts discards the report being
prepared; once the upload starts the report is saved on the machine, a
failure marked retryable offers a retry, and the saved report can be
sent later from the command line by its id. Every answer is checked
against the wizard's epoch and the job or report it was asked about, and
a write step whose answer is lost is settled from the report's status
instead of being sent again. Layouts were measured at 360 and 390 px in
English and Chinese.
- **Docs and tests.** The webui and trajectory-debugging pages (English
and Chinese) describe both flows. Two integration tests drive them end
to end: the export through the real download route, and the bug report
against a real receiver process, including a stopped receiver, a retry,
the redaction history's replay and a cancel at each step.

## Type

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

## Verification

- The branch merges the current `main` (one merge commit, no conflicts);
everything below ran on the merged tree.
- `uv run pytest tests/ -q` (full suite): 57 failed / 31491 passed / 177
skipped. Every one of the 57 also fails on the current `main` on this
machine (environment-specific, pre-existing); none is introduced by this
branch.
- `uv run pytest -m integration
tests/integration/test_web_traj_export_e2e.py
tests/integration/test_web_bugreport_e2e.py
tests/integration/test_bug_report_upload_e2e.py -q`: 10 passed (three
consecutive runs of the two new files).
- `uv run ruff check`, `uv run ruff format --check`, `uv run ty check`
on the changed Python: pass.
- ui-web: `npm run gen:check` (239 methods), `npm run lint`, `npm run
type-check`, `npx vitest run` (246 files / 3868 passed), `npm run build`
and `python3 ui-web/build.py` (both boot snapshots match),
`check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: pass.
- ui-tui: `npm run lint:rpc`, `npm run lint:i18n`: pass.
- `uv run --group docs mkdocs build -f docs-site/mkdocs.yml --strict`:
pass.
- `make check-source-language check-large-files check-commits`: pass.
- Headless Chromium on the built page (offline fixtures): both flows
walked to the download and to the receipt; the header corner measured in
five layouts (desk panel open and closed, workspace panel open, shell
mode, narrow split) and the wizard at 360 and 390 px in both languages.

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

## Risk

- A process started with the old `--dev` flag that runs `system.upgrade`
relaunches itself with `--dev`, which the new version refuses; the user
runs `raven web` once by hand. This was accepted as the cost of dropping
the flag.
- The trajectory view is on by default: each open page calls the light,
in-memory `trajectory.state` every five seconds, and the index is built
only when the view is opened. No switch to turn it off is added here;
the policy keeps a replaceable source for a settings entry later.
- The export is the raw trajectory and may contain secrets. The page
says so in a warning; the download is served only on the same origin,
behind the session guard, by an unguessable one-time token, and no path
ever reaches the page.
- Rollback: revert the squash commit. Nothing is migrated; the
`trace_id` field already written into session records is ignored by
older versions.

- [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-10-14 21:34:46 +08:00
Dizhan Xue
a0380968d5
fix: normalize web UI capitalization (#946)
## Summary

- Normalize Web UI labels, action captions, acronyms, and brand names,
including Model ID, API key, ACP, OpenAI, and Raven. Keep sentence case
in prose.
- Share agent kind display labels and remove CSS that forced them to
lowercase. Regenerate the shared TUI catalogue and update existing test
expectations.
- Align the backend SSH approval note and Web/TUI test expectations with
the shared catalogue. Context chip tests use the real English catalogue
so focused runs have the same setup as the full suite.

## Type

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

## Verification

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

- `npm test --prefix ui-web -- --maxWorkers=2`: 3,753 tests passed
across 239 files.
- `npm test --prefix ui-tui -- --maxWorkers=2`: 2,098 tests passed
across 144 files; 13 skipped.
- `PYTHONPATH=. uv run --no-sync pytest
tests/test_i18n_sensitive_notes.py tests/test_config_self_surface.py
tests/test_i18n_boundary.py tests/test_i18n_prompts.py -q -n 0`: 141
passed. Separate local `--idle-ceiling-strict` runs passed all
assertions but exceeded the cold-load idle limit on this host; the base
revision also reproduced the cold-load warning.
- `npm run --prefix ui-web type-check`: passed.
- `npm run --prefix ui-web lint`: no errors; four existing React Hooks
warnings.
- `npm run --prefix ui-tui lint`, `npm run --prefix ui-tui lint:rpc`,
`npm run --prefix ui-tui lint:i18n`, `npm run --prefix ui-tui
type-check`, and `npm run --prefix ui-tui build`: passed; lint has 23
existing warnings.
- `npm run --prefix ui-web build` and `uv run --no-sync python
ui-web/build.py`: passed, including both boot snapshots.
- `make check-large-files check-source-language
COMMIT_RANGE=origin/main..HEAD PYTHON_VERSION=3.12`: passed.
- `uv run --no-sync pre-commit run --from-ref origin/main --to-ref
HEAD`: all applicable hooks passed.
- Chromium checks covered English and Chinese model settings, Model ID
fields and search prompts, and the agent kind CSS. No browser errors
occurred. Screenshots were checked locally; no documentation update is
needed for this copy change.

## Risk

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

Low risk: visible wording changes also reach the TUI through the shared
catalogue. Configuration keys, protocol values, and persistence formats
are unchanged. Revert this PR to restore the previous presentation.

## Related Issues

N/A
2026-10-14 17:50:48 +08:00
Handsome-wzw
b43d78bf04
feat(*): read, write and deliver files on a registered machine by address (#922)
## Summary

Third of four changes that let a Raven dispatch work to the machines in
its machine registry. #920 is merged; this branch is opened against main
ahead of #921, so the diff here includes #921's commits as well: review
from "read, write and deliver files on a registered machine by address"
on (the commits before it are #921's, carried here until it merges).

What this does:

- The file tools take a path on a registered machine as it is written
  for scp -- `user@host:/path`, or `scp://user@host:port//path` when the
  port is not 22 -- and answer it through the machine's daemon
  (`raven/agent/tools/remote_files.py`, hooked from `filesystem.py` and
  `file_search.py`): `read_file`, `list_dir`, `find` and `grep` run
  Raven's own tools there and bring back the answer, so a read of fifty
  lines of a large file moves those fifty lines; `write_file` and
  `edit_file` write there, with the digest of that agent's own last read
  -- the conversation's, or its sub-agent run's -- as the expected
  state, so a file changed since it read it is refused and nothing is
  written, and another agent's read does not stand in for its own. The
  path is resolved against the registry
  only, never this computer's ssh config, so one path names one machine
  on any computer; one that matches no row is refused, not guessed.
- What is shown back as an address is only what the tool says about
  paths -- its errors, its headers and footers, a write's account, a
  diff's two header lines; a read's numbered lines, a search's matches
  and context, and a diff's body come back as they are, so the model
  edits against the bytes the file holds. The shell's refusal of typed
  `ssh` to a registered machine (`raven/agent/tools/shell.py`,
  `machine_exec.py`) reads the program in any spelling -- a path, a
  backslash, and on a Windows host `ssh.exe`, `SSH.EXE` or a whole
  `C:\...\ssh.exe`, with the backslashes the shell there keeps and
  without the quotes it takes off (a quoted piece and a bare one next to
  it making one word), so a quoted destination or port is matched like a
  bare one -- and, with the lane on, names the file tools. `scp`, `sftp`
  and `rsync` to a registered machine stay what they are on main: a copy
  starts nothing there and passes exec's own question like any command,
  and the file tools cannot carry a directory, a binary file or a large
  one, so the copy stays the route for those. A drive-relative or
  extended Windows path (`C:file`, `\\?\C:\...`, UNC) is this
  computer's, not a machine nobody registered.
- Permissions (`raven/permissions/`): a path inside the directories
  Raven's agents work in on that machine -- its session directory, its
  `remoteCwd`, the row's listed `paths` -- is read without asking;
  elsewhere a read asks once per machine and directory for the session.
  A write there asks wherever it falls, as a write here does, and its
  grant is for the one file, apart from any read. The daemon checks the
  roots again on the machine, links included.
- `deliver_files` fetches one file by its address, whole and checked,
  under a 20 MB cap, into `<workspace>/pulled/<machine>/<key>/<name>`,
  the key a digest of the file's path on the machine, so two paths never
  share a landing: not two files of one name from two directories, and
  not two names this computer's filesystem reads as one (`Report.txt`
  and `report.txt`, a trailing dot). The name beside the key is written
  as one this computer keeps (a backslash, what Windows reserves in a
  name, control characters and the percent sign itself as
  percent-codes), and a landing that would not resolve under the
  machine's delivery directory is refused before anything is made; a
bigger file is named with its size and read there instead. Only a file
under the directories this Raven's agents work in
  on that machine is fetched: the tool asks nothing, and a read some
  conversation was allowed is no evidence for this one, so a file
  elsewhere is refused and read there instead. Nothing reclaims
  `pulled/`: a delivery is opened from its landing for as long as its
  record lasts, and a bound by size or age is left out of this change on
  purpose.

## Type

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

## Verification

- `uv run pytest tests/test_remote_file_tools.py
tests/test_permissions_remote_read.py tests/test_deliver_files_tool.py
tests/test_shell_machine_channel.py tests/test_ops_remote_path.py
tests/test_permissions_gate.py tests/test_import_cycle_budget.py
tests/test_node_server.py tests/test_node_client.py
tests/test_subagent_acp_remote.py tests/test_acp_remote.py
tests/test_cli_ops_connection_commands.py`
  -- all passed on this tree (703 in the run that covered the first
eight groups, the node's own suite and the real-node cases among them).
  Covered: each tool on a remote path answers as its local tool would,
  through a stood-in link and a real daemon; a path outside the roots is
  refused on both sides; a write with a stale digest is refused and
  writes nothing; the address form on what the tool says about paths,
  and a read's lines, a grep's matches and a diff's body untouched; the
  shell's refusal of typed ssh to a registered machine, by host, by
  alias, in a pipeline, as `ssh.exe` and `SSH.EXE`, and with a whole
  Windows path or a quoted destination or port when the host is Windows,
  a copy with scp, sftp or rsync not refused, and the file tools named
  only with the lane on; a fetched name holding the
  other platform's separators lands as one name under the machine's
  directory and nothing lands elsewhere, and a landing that would
resolve outside fetches nothing; a Windows path form read here with the
lane on; the read
  permission inside the roots and the question elsewhere, remembered per
  machine and directory, a write asked wherever it falls and its grant
  kept per file and apart from a read; a read's digest kept per agent,
  so another agent's read lets no stale overwrite through and an agent
  that never read the file expects nothing; a delivery fetched whole
  under a key of its path (two files of one name, two names a
  filesystem reads as one, and the percent-code pair all land apart),
  refused over the cap and refused outside the roots whatever was read
  before.
- `uv run pytest` on this tree after the merge with main -- 31210
passed,
  231 skipped, 2 xfailed, 4 failed, every one of the four in a test that
  needs what this machine lacks (`test_rpc_files.py`, the two simulation
  cases and the kimi-code case that fail the same way on main here); the
groups above also pass under `--idle-ceiling-strict`, CI's idle ceiling.
- Diff coverage of this change against main after the merge: 95.27% (805
of
  845 executable changed lines), against the 90% gate. The node suite,
the remote-path tests and the real-node cases among the groups above run
  on the merged tree.
- Real machines (two registered Linux machines): fifty lines from the
  middle of a 5 MB file read through the daemon in 30 to 35 ms, byte for
  byte what this computer reads; list, find and grep answered; a write
and an edit landed as the local tools would, and a write after the file
  changed was refused; a path outside the roots refused; a file written
  by an agent there fetched back by address. The shell's refusals are
  covered by the tests above.
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
  and `scripts/check_large_files.py` on the branch range, `commitlint`,
  `ruff` -- all clean.

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

User docs follow once the lane is no longer debug-only.

## Risk

Behind the debug lane, as the two changes before it. With it on, a
remote
path reaches the machine only through its daemon, inside the roots each
call names and under the read and write questions above; the shell
cannot
run a command on a registered machine by address, and a copy to or from
it
with scp, sftp or rsync is the plain shell's behind exec's own question,
as
on main. A write refused for a stale
digest writes nothing. A delivery fetches at most 20 MB per file into
the
workspace, and only from the directories the agents work in on the
machine. Rollback is a plain revert.

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

## Related Issues

#920 (merged); depends on #921.

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-14 16:10:18 +08:00
zhanghui
d106a5c6ef
feat(plugins): add the everos-cloud-memory plugin and its host wiring (#883)
## Summary

Adds `everos-cloud-memory`, a separately distributed memory plugin for
EverOS Cloud, and wires the host so a second memory plugin is a
first-class choice.

The plugin (`plugins-dist/everos-cloud-memory`) is a thin REST client
over httpx: one API key (the config slice
`plugins.config.everos-cloud-memory.api_key`, or
`EVEROS_CLOUD_API_KEY`), owner ids from the host's `ServiceLocator`
(never from the slice), every add in `agent` mode, and a flush only when
a caller marks the conversation over (`metadata.flush` /
`metadata.is_final`: the sub-agent handoff and the importer's final
batch) and once at stop. It ships its own onboard screen (env or on-file
key used without a prompt; 401 / 403 / unreachable get their own
sentences with Re-enter or Skip), `delete` answers False (the cloud
deletes by scope, nothing calls it), and `health()` classifies seven
answers for `raven doctor` and the settings card.

Host changes, each guarded so `memory.backend` `everos` and `null`
behave exactly as before:

- `raven onboard` step 4 asks "Which memory backend?" when more than one
plugin contributes a screen (preselects the current backend, `Off`
clears it, cancel exits 1 and writes nothing); with one plugin the step
is byte-identical to today.
- The memory page reads whichever backend `memory.backend` names: the
cloud slice's key goes out as a Bearer header and the `/health` probe is
skipped for the cloud; a missing distribution is named in the page's
note.
- `settings.everos` reports `reason: "other_backend"` for any non-EverOS
backend, so the Model page hides the three EverOS-only roles (embedding
stays: knowledge bases use that pin); `settings.everosSet` refuses those
three sections for another backend; `settings.set` admits
`plugins.config.<id>.<field>` against the plugin's manifest through the
same admission door channels use; new `settings.everosCloud` feeds the
card (key source, endpoint, health).
- Provider-key and main-model saves no longer restart the local EverOS
when another backend is active.
- ui-web: an EverOS Cloud card (status chip, key row, endpoint) and the
`settings.everosCloud` data behind it. No page mounts the card: it drew
on Model settings until the owner ruled that a memory backend's endpoint
and credential answer neither question that page asks, and where it
belongs is the Memory section's to say once that section has a design.
Until then the key is entered through `raven onboard` or
`EVEROS_CLOUD_API_KEY`. The fixture gate pins the four optional fields
the offline library never sends.
- Gates: the plugin boundary test scans both memory plugins, coverage
and the release workflow build the second wheel, deptry's ignore list
names the plugin beside `raven_everos`, and a conftest fixture keeps the
second plugin out of entry-point discovery for the existing onboarding
tests (they describe a one-plugin install).

A second topic rides along, because it is what makes the hosted backend
reachable from an agent product at all. Every product under `agents/`
pinned its memory at the stock EverOS address and only `raven-design`
read the host's, so the other four addressed whatever answered on 18791
-- the wizard moves a managed server when the port is taken, and a
server the user runs themselves is wherever they put it.
`inherit_memory_backend` in `raven/config/product_render.py` now carries
`memory.backend`, the endpoint, and (only when the product holds none
itself) the credential from the host into every render, beside the host
denials and plugin opt-outs that already travel there; `raven-design`'s
private copy is deleted and the five product configs stop naming an
address. Identity never travels, which is what keeps five products apart
inside one store. `memory.backend: null` travels like any other value,
because that null is how an operator turns long-term memory off and a
product that kept writing would be the one surface ignoring them; the
product's own default stands only when the host carries no key at all.
Which store memories live in is not a product's choice either: the host
reads a sub-agent's memories back through its own backend, so a product
writing anywhere else left that record empty with nothing reporting it.
`owned` is forced off whenever the local backend is in force, because a
product infers ownership from a slice naming no root -- the shape all
five ship -- and so answered a host that was merely not serving by
starting a second server against a root of its own, stranding every
memory written so far.

Decisions worth a reviewer's eye: the fake cloud
(`tests/_everos_cloud_fake.py`) honours or refuses every field the
backend can send and serves both an in-process transport and an HTTP
face for the real-host acceptance; the live tests
(`tests/integration/test_everos_cloud_real_cloud.py`) skip without
`EVEROS_CLOUD_API_KEY`; run with a real key on 2026-10-09 all six pass
against api.evermind.ai (round trip, get by session, empty flush, 401
wording, probe with and without a key, and extraction without a flush
within two minutes), so the documentation and the service agree on
everything the plugin sends. Design, acceptance cases and plan are under
`docs/specs/2026-10-08-everos-cloud-memory-*.md` and `docs/plans/`.

## Type

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

## Verification

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

Rebased onto main `182dacac0` on 2026-10-13. What that rebase and the
four commits on top were verified with:

- Full suite, `uv run --frozen --python 3.12 --extra dev pytest -q` ->
**29748 passed, 8 failed** in 4m10s. All eight fail identically with
these four commits' sources reverted in-tree at the same base, so none
of them is this branch's: the two `test_the_products_tool_face_*` cases
in the code and oncall launchers (an extra `web_search` in the visible
tool set), `test_agent_loop_token_budget`,
`test_rpc_files::test_a_host_without_libreoffice_says_so`,
`test_ppt_engine_image_search`, `test_shell_background`, and the two
`test_simulation_*` cases.
- Real-host before and after for the inheritance, driving the launcher
the host spawns (`agents/raven-research/run.py`) against an isolated
`RAVEN_HOME` whose EverOS address is `19701`, not the stock port.
Before: the product rendered `base_url: http://localhost:18791` with no
`owned` key, ignored the host, and started an EverOS of its own -- an
orphaned `everos server start --root <its own state root>/everos`
holding 18791, which is the stranding this change exists to stop. After:
it rendered `{"base_url": "http://localhost:19701", "owned": false}` and
said so itself, "the EverOS you manage is not running at
http://localhost:19701 ... Raven does not start or stop it", with `ps`
and `lsof` confirming nothing was started. On the cloud the product
rendered `memory.backend: everos-cloud` with the host's key and left the
out-of-force local slice untouched, and `raven doctor` over that
rendered config answered `everos-cloud: ok https://api.evermind.ai`, so
the credential reached the service. Identity stayed `raven-research-ng`
throughout, and a fingerprint of the operator's own EverOS root was
identical before and after.
- The first CI round on this head found one that the local gates did
not: `tests/test_import_cycle_budget.py`. `inherit_memory_backend` read
the backend-to-distribution pairing from `raven.core.plugin_stack`, and
that edge from `raven.config` into `raven.core` -- which imports
`raven.config` back -- took mutual pairs from 13 to 14 and packages
inside a cycle from 18 to 22. `make lint-imports` keeps ten contracts
and none of them covers that pair, so it was green throughout. The
pairing now lives in `raven/config/raven.py` beside the two fields it
joins (`MemoryConfig.backend` names a contribution,
`PluginsConfig.config` is keyed by the distribution), which `raven.core`
may import and which imports nothing back; `plugin_stack` re-exports the
two names its own callers read from it. An intermediate commit put it in
`raven.contracts` instead, which broke the cycle but took the papers
ceiling from 3700 to 3719 lines -- `tests/test_kernel_budget.py` says a
new paper is a reviewed change to that ceiling, so it moved again rather
than raising it.
- The review round on this head raised one non-blocking finding, fixed
rather than carried forward: the inheritance read `memory.backend` with
`.get()`, which collapses an explicit `null` into an absent key, so a
host with long-term memory off left every packaged agent on its own
shipped backend and still writing. Reproduced by calling the function
directly before the change and after, now read on presence, and pinned
by a case whose mutation (restoring the `.get()`) turns it and nothing
else red.
- One ordering problem found while checking the above, pre-existing and
not fixed here: `tests/test_rpc_settings.py` run before
`tests/test_cli_onboard_commands.py` leaves
`raven.home._current_config_path` pointing at a dead tmp config, so the
onboard cases write somewhere else. With main's own copies of both files
and main's conftest in the tree it is 57 failures; with this branch's,
19. Which cases turn red changes run to run as xdist distributes them
differently.
- `cd ui-web && npx vitest run` -> 876 files, 3728 passed, 0 failed;
`npm run lint` -> 0 errors (4 warnings, all in files this change does
not touch); `npm run gen:check` -> in sync (228 methods); `npm run
type-check` -> clean; `cd ui-tui && npm run lint:i18n && npm run
lint:rpc` -> in sync
- `make lint-python` / `lint-imports` (10 contracts kept) / `lint-types`
/ `lint-deps` -> all pass; `uv lock --check` -> exit 0 with both sides'
new packages present; `scripts/check_source_language.py` and
`scripts/check_large_files.py` on `github/main..HEAD` -> exit 0;
commitlint over every commit -> ok
- Semantic-conflict audit of the rebase, beyond what the suite answers:
21 of the branch's 66 files are also in main's 499, and every one of
main's changes in them is additive and elsewhere in the file. The one
that could have broken silently is main's new `vision.model` /
`vision.provider` simple keys meeting this branch's new
`plugins.config.<id>.<field>` branch in `settings_set`; nothing in the
suite exercises `vision.*` through that method, so it was run directly
-> `{'applied': True}` and `{"model": "..."}` on disk. The subtraction
decisions were re-checked against the new base: no new caller of a
memory backend's `delete`, main's new onboard cases are about TLS and
not the memory step, `inherit_everos_address` exists nowhere, and
`DEFAULT_EVEROS_BASE_URL` is still defined.
- Mutation runs on the new code, restored afterwards: dropping `owned:
false`, letting the host's credential overwrite the product's own, not
writing the host's backend name, and carrying every memory slice instead
of the one in force each turn their own cases red; making the cloud card
render nothing turns 4 of its 5 new cases red and leaves the fifth
("draws nothing when not selected") green.

From the earlier round, on base `6d509a8c5`:

- `uv run --frozen --python 3.12 --extra dev pytest -p no:cacheprovider
-q tests/test_everos_cloud_fake.py tests/test_everos_cloud_backend.py
tests/test_everos_cloud_backend_contract.py
tests/test_everos_cloud_onboard.py tests/test_everos_cloud_discover.py
tests/test_cli_onboard_commands.py tests/test_rpc_memory.py
tests/test_rpc_settings.py tests/test_plugin_boundary.py
tests/test_rpc_schema_match.py tests/test_rpc_registration.py
tests/test_release_plugin_list.py
tests/integration/test_everos_cloud_real_cloud.py` -> 1001 passed, 6
skipped (the six live tests, no key)
- `cd ui-web && npx vitest run` -> 214 files, 3211 passed; `npm run
lint` -> 0 errors (4 warnings, all in files this change does not touch);
`npm run gen:check` -> in sync (207 methods); `cd ui-tui && npm run
lint:rpc && npm run lint:i18n` -> in sync
- `make lint` (ruff, ruff format, ui tsc, deptry) -> ok; `make
lint-types` -> All checks passed; `make build-ui` -> boot snapshots
match; `scripts/check_large_files.py` and
`scripts/check_source_language.py` on `6d509a8c5..HEAD` -> exit 0;
commitlint and `scripts/check_commit_messages.py` on each commit -> ok
- Mutation runs per change (restored afterwards, `git diff` clean): a
host import of the plugin turns the boundary test red; `import
raven_everos` in the plugin turns the import-isolation test red;
removing the chooser's cancel exit, the Bearer header, the restart
guard, the slice-admission guard, the Roles filter and the fake's two
fixes each turn their own test red
- Real-host acceptance (64 cases,
`docs/specs/2026-10-08-everos-cloud-memory-acceptance.md`) run against a
fake EverOS Cloud: the wizard in tmux (chooser, key typed / from env /
on file, 401 / 403 / unreachable wording, back, Off, Ctrl-C,
non-interactive, base-tree transcript byte-identical with one plugin),
`raven agent` turns (user and agent-track recall, agent-mode adds, 4 s
recall bound, a 300 KB message dropped with a warning, a sub-agent trace
stored under its own ids, flushed and read back, one exit flush per
unflushed session), `raven import run` (3 adds then one flush; a hung
flush retried 4x and the exit sweep defeated), `raven doctor` under
seven cloud conditions (seven sentences, exit 2 only for the five
faults) and with the distribution hidden, and the web page through
playwright-cli (memory page counts and the fake's episode, empty and
refused stores, the Model page hiding the three EverOS-only roles while
the embedding row stays, the cloud card rotating a key and showing the
401 wording, three refused settings.set frames over the gateway
WebSocket, the local everos / null / mem0 backends drawing the page as
before, and a provider-key save that restarts the local EverOS on the
base tree and does not on this branch). Evidence and the per-case
verdicts are kept outside the repo. The live service was reached with a
real key after the acceptance run: six tests, six passes, the service's
replies archived with the evidence.

## Risk

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

User-visible changes: the wizard's step 4 chooser (only when two memory
plugins are installed); Model settings hides the three EverOS-only role
rows when `memory.backend` is not `everos`/`null` and draws no cloud
card; the memory page sends a Bearer header for the cloud backend.

Two behaviour changes for agent products, both on the `agents/` lane
only. An agent product now follows the host's `memory.backend` and
endpoint instead of its own, which is a fix for the four products that
never followed the host and a change for `raven-design`, which followed
the endpoint but not the backend. And a product no longer starts an
EverOS server of its own: where it used to answer a host that was not
serving by starting one against an empty root of its own, it now reports
long-term memory as unavailable, which is what the host does. Rollback
for this part is the one commit; the product configs it edits are
shipped files, not user config. The plugin is not installed by default
(its wheel is built by the release workflow; nothing changes for an
install without it). Rollback: revert the squash commit; the config
schema gains no new key (the slice is a plugin slice), so an older raven
reads a config written by this one.

Credentials: the cloud key is written only by `set_plugin_config_fields`
into the plugin's slice; the settings page's key row goes through
`settings.set` with a manifest-declared field, and
`settings.everosCloud` reports `api_key_set` / `key_source`, never the
value.

## Related Issues

N/A

---------

Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-10-14 11:08:11 +08:00
Dizhan Xue
92bc2377c7
fix(ui-web): attach a picture dragged into the composer by its own path (#900)
## Summary

Dragging a picture from the transcript into the composer now attaches
the file shown by that picture. The composer accepts the same-origin
/file path when it matches a drag that began in the document. File
uploads retain their image extension through the MIME type when the
browser supplies a generic filename. The drag listeners live in the
global listener registry, and the composer and viewer share the
picture-extension table.

Uploads, picked deck templates, and direct-chat uploads are staged by
abs_path. Attachment notes preserve that identity through queued sends,
history reloads, and changes of session. Dragged files retain their
original paths. Reloaded attachment notes pair each engine path with one
entry, preventing overlapping suffixes from duplicating an image.

The viewer and turn.send share session-aware path resolution. Under
tools.restrict_to_workspace, attachments are admitted from the session
directory and agent home. The viewer serves agent-home uploads by their
resolved location, including absolute paths, and rejects traversal or
symlinks that escape uploads into other agent-home files.

Both fs.upload and deck.templates.pick use one filename allocator. It
checks agent home, the runtime-resolved directory, and a draft's
selected directory. This covers pinned drafts, the gateway's tui
directory, existing sessions, and a process -w override. Unreadable
candidate directories are skipped individually while the remaining
directories are checked. Draft directories use the same validation as
session.create. The optional session/workdir fields are documented in
OpenRPC and mirrored in Python and both generated clients.

## Type

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

## Verification

Linux validation after rebasing onto main and retaining both the
trajectory visibility and draft-workdir imports:

- `uv run --frozen --all-extras pytest -q --tb=short`: 28470 passed, 8
failed, 120 skipped. All eight failing test IDs also failed on an
unmodified main checkout: five proxy-environment cases, one Node-path
case, one terminal-color case, and one root-permission case.
- `uv run --frozen --python 3.12 --no-sync pytest
tests/test_rpc_console.py tests/test_rpc_deck_templates.py
tests/test_rpc_files.py tests/test_rpc_turn_send.py
tests/test_rpc_schema_match.py tests/test_import_cycle_budget.py -q -n 0
-x --tb=short`: 785 passed.
- In ui-web: `node node_modules/vitest/vitest.mjs run
--no-file-parallelism`: 231 files, 3511 passed.
- In both ui-web and ui-tui: `node node_modules/typescript/bin/tsc
--noEmit -p tsconfig.json`: passed.
- In ui-web: `node scripts/gen-rpc-client.mjs --check`; in ui-tui: `node
scripts/gen-rpc-types.mjs --check`: both clients match the contract.
- `make check-commits check-large-files check-source-language
lint-imports`: passed; 10 import contracts kept, 0 broken.
- `uv run --frozen --python 3.12 --no-sync pre-commit run --from-ref
origin/main --to-ref HEAD`: all applicable hooks passed.
- `uv run --frozen --python 3.12 --no-sync ty check raven/rpc/files.py
raven/rpc/deck_templates.py raven/rpc/methods/console.py
raven/rpc/models.py`: passed.
- In ui-web: `node node_modules/eslint/bin/eslint.js src/app/install.ts
src/app/install.test.ts`: passed.
- `git diff --check origin/main...HEAD`: passed.

Regression cases cover colliding names in agent home and session
directories, repeated deposits, draft-directory validation, unreadable
directories, per-call frontend context, and the precedence of a process
working-directory override. Pre-fix runs reproduced failures for
template collisions, pinned-draft uploads, process-override collisions,
and the frontend request context.

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

The RPC contract documents the added optional parameters. This update
changes attachment handling and has no new visible control.

## Risk

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

The same-document drag check and resolved-path boundaries remain
enforced. The new directory hints affect filename allocation; deposited
bytes remain in agent home. Existing callers may omit the added fields.
Clients should send abs_path to preserve upload identity if the session
directory or its files later change.

Cross-tab drags follow the existing browser-file fallback, and direct
chat retains its upload control without a drop target. Validation above
covers the affected Python and frontend suites; native Windows and macOS
browser behavior was not rerun for this update.

Rollback is reverting the squash commit. There is no data or
configuration migration, and previously recorded absolute attachment
paths remain usable.

## Related Issues

N/A
2026-10-14 11:07:32 +08:00
Kevin Hu
6e7926a8e5
fix(knowledge): seven defects in the document reader, six of them docker-only (#938)
## Summary

Seven fixes to the knowledge reader, all found by running the Docker
image
against real documents. Six of the seven only reproduce there or only
reproduce in a browser, which is why they reached a release.

**The image could not draw the reader at all.** The document viewer
serves a
page of the file as a picture (`/knowledge/page`), the region a chunk
was cut
from (`/knowledge/crop`), and the file itself (`/knowledge/file`). All
three
are engine routes and none was in the nginx server block, so they fell
to
`location /` and were answered with index.html -- a 200 of text/html
where the
page put an `<img>`, which a browser draws as a broken image and reports
nowhere. Measured before: `200 text/html`. After, with a session:
`200 image/webp`, 126060 bytes, byte for byte what
`knowledge_pages.image_for`
writes. Source installs proxy nothing, so the reader has always worked
there.

**A document could be stranded at `indexing` for good.**
`index_document` is
awaited inside the RPC that asks for it, on the page's websocket, so a
reload
or a lost socket cancels it. `asyncio.CancelledError` is a
`BaseException`:
the five-type clause there and the `except Exception` in the RPC method
both
missed it, and the record was left reading `indexing` with nothing
indexing
it, no error beside it and nothing to retry it. It is set back to
`pending`
and re-raised now.

**Nothing drained that queue.** `_requeue_interrupted` puts back what a
restart interrupted and the above puts back what a cancel interrupted,
both
into a queue whose only other caller was a model switch on one base. The
row
read `Queued` and stayed there -- the same complaint
`_requeue_interrupted`'s own docstring makes about the state it rescues
documents from, one status further along. The gateway drains it at boot
now,
after a delay and one document at a time.

**Every .docx, .pptx and .xlsx failed to parse in the image.**
`mimetypes.guess_type` answers from the host, and the image carries none
of
the six files `mimetypes.knownfiles` names, so Python's built-in table
is all
it knows -- and that table predates OOXML. It knows `.doc` and `.ppt`
and
answers None for `.docx`, `.pptx`, `.xlsx` and `.rtf`. The manager falls
back
to `text/plain` for an unknown type, so a Word document went to the text
parser, which decoded the zip container as UTF-8 and died on the first
byte
that is not a character: "'utf-8' codec can't decode byte 0x91 in
position
15", against a file nothing is wrong with. The same table reversed is
what
`supported_extensions` builds the upload dialog's accept list from, so
those
formats were missing there too. The parsers state what they read now
instead
of asking the machine they run on.

**Indexing silenced every other control on the page.** `busy` is one
flag for
the whole store and both the upload and the rebuild held it across the
entire
parse-and-embed, tens of seconds on a long PDF. For all of that time
delete,
rename, star, pin, move, folder create and delete and every chunk edit
returned at their guard and did nothing -- no toast, nothing in the
console.
The confirm had already armed, so a reader answered "Delete, really" to
a
question that was then thrown away. Indexing has its own flag now; it
still
refuses to start a second one, which was the part that mattered.

That makes deleting a document while it indexes reachable, so the
manager
checks the record still exists before inserting. The delete already took
that
document's vectors, and inserting the ones that run computed would put
pieces
of it back with no row to own them, answering searches out of a deleted
file.

**A freshly uploaded file read `Queued` until the page was reloaded.**
The add
answers with the row as the server first wrote it, and the next line
starts
the call that indexes it. The row was left at what the add said for all
of it
while the server had already moved to `indexing` -- so reloading showed
the
truth and waiting did not. The rebuild path has never had this problem
because
it marks its own row, and the comment above that line is this bug
described in
advance: "a row that does not move until it is over reads as a press
that did
nothing". Both call one helper now.

**Picking a folder uploaded everything in it.** No browser applies
`accept` to
a directory, so a chosen folder arrived as every file under it --
.DS_Store,
lock files, images -- and each became an upload, a parse and a row
reading
Failed for a file nobody meant to add. The single-file picker set no
`accept`
at all. `knowledge.status` has answered with the readable extensions
since the
reader was written, and the comment above it asks for exactly this: "a
surface
that walks a folder has to filter by today's answer". Nothing on the
page had
ever called it. Both pickers carry that list now and what comes back is
filtered before anything is uploaded, because `accept` is advisory twice
over.
What is left out is reported rather than dropped quietly, and an install
whose
list could not be read filters nothing.

## Type

- [x] Fix

## Verification

- `uv run --frozen pytest tests/` -- 29694 passed, 121 skipped, 2
xfailed, 3
failed. The three are environmental and fail identically on this
branch's
base: macOS resolves soffice under /Applications so blanking PATH does
not
hide it, a case-insensitive filesystem, and process-descendant
enumeration.
- `npx vitest run` (ui-web) -- 238 files, 3724 passed.
- `npx tsc --noEmit` and `npx eslint src/features/knowledge/` -- clean.
- `uv run --frozen ruff check .` -- clean.
- `uv run --frozen --all-extras deptry raven` -- no dependency issues.
- `make check-source-language` and `make check-large-files` -- clean.
- `npm run --prefix ui-tui lint:i18n` -- clean after regenerating the
  catalogue for the one added message.
- In a running container: `/knowledge/page` answers 200 image/webp where
it
answered 200 text/html; a document deleted during a rebuild goes in
about
three seconds with the PDF still reading Indexing; opening a base sends
knowledge.status and both pickers are built carrying all 27 extensions.
- Every new test was checked against the unfixed code and fails there.

Not verified by hand: the upload picker is an `<input>` built detached
and
clicked, so it cannot be driven from a page script. The freshly-uploaded
status and the folder filtering rest on unit tests and on the element
the
picker builds, which was inspected live.

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

## Risk

User-visible behaviour changes, each of them a surface that did nothing
before:

- the knowledge reader's pictures load in Docker;
- a `.docx`, `.pptx` or `.xlsx` indexes in Docker instead of failing on
its
  zip header;
- an interrupted index is retried instead of sitting at `indexing`;
- the gateway indexes what is queued when it starts, which is embedding
work
at boot that did not happen before. It waits, runs one document at a
time,
  never raises, and does nothing when the queue is empty;
- structural controls work while a document indexes;
- a file picked from a folder that this install cannot read is left out
with a
  count rather than uploaded and failed.

Rollback is per commit: each of the seven stands alone and reverting any
one
restores the behaviour it changed. The nginx block, the mime
registration and
the cancel clause are additive and revert cleanly. The queue drain is
one call
at boot and removing that call disables it entirely.

Security: the mime registration adds only IANA mappings for formats the
parsers already accept, and routes no new input anywhere. The nginx
block
proxies three engine routes that enforce their own session check --
verified
by the 401 an unauthenticated request still gets.

Backward compatibility: no stored shape changes. The one record
transition
added, `indexing` to `pending` on cancel, is what a restart already did.

- [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-10-14 10:43:57 +08:00
Dizhan Xue
146bba8d8a
fix(ui-web): refresh pictures and deck pages on reopen or redelivery (#907)
## Summary

Reopening a rewritten picture or deck could reuse cached content, and an
open picture did not refresh when delivered again. Picture, SVG and deck
URLs now combine the open sequence with the latest delivery stamp.
Repaints, repeated delivery records and unrelated deliveries retain the
current URL.

Image errors belong to the displayed version. HEAD probes, text reads
and file sniffing capture the delivery row before fetching and mark it
missing on 404 only while that same row is current. A delayed response
cannot mark a replacement delivery missing, including when a prior row
already existed.

Delivery-card pictures and thumbnails retain their per-delivery
versions. Composite versions are URL-encoded without changing file paths
or download tokens.

## Type

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

## Verification

Linux, Node 22 and Python 3.12, after rebasing onto main:

```text
cd ui-web
node node_modules/vitest/vitest.mjs run --no-file-parallelism
npm run type-check
node node_modules/eslint/bin/eslint.js src/features/desk/DeskSurface.test.tsx src/features/transcript/TranscriptPage.test.tsx src/features/transcript/TranscriptPage.tsx src/features/workspace/WorkspacePage.test.tsx src/features/workspace/WorkspacePage.tsx src/features/workspace/store.ts src/features/workspace/types.ts
```

Results: 231 test files and 3510 tests passed; TypeScript and ESLint
passed for the affected files. The full `npm run lint` also passed with
four existing warnings in unrelated components.

```text
uv run --frozen --python 3.12 --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
make check-commits check-large-files check-source-language lint-imports
git diff --check origin/main...HEAD
```

All applicable hooks and gates passed. The new text/sniff race cases
failed before the fix. Replacing row-identity comparison with path
comparison makes the existing-row picture regression fail; the source
was restored afterward. Tests also cover unrelated deliveries during a
pending request. Independent read-only security review found no
remaining issue.

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

No new controls or configuration require documentation changes.

## Risk

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

Open pictures and decks request fresh content on redelivery and
reopening. Text/sniff errors update only the delivery row observed when
the request began. Route authorization, file-size limits and path
resolution remain in force. Revert the squash commit to roll back; no
data migration is needed.

## Related Issues

#838
2026-10-12 21:32:42 +08:00
Kevin Hu
82c76a82a9
feat(knowledge): read every format, show what the index holds, and let an agent search it (#489)
<img width="2318" height="1448" alt="image"
src="https://github.com/user-attachments/assets/bca71d69-4972-420c-b14e-c8cf74a17de9"
/>

## Summary

Everything a knowledge base could not read, and the pieces it cut them
into
saying what they are.

**Reading a PDF.** A PDF records glyphs at coordinates; whether they are
a
heading, a table cell or a running footer is inferred from how they
look. There
are now two readers. The geometric one infers structure from type size
and
position and needs nothing but the file. The other asks deepdoc's
models, ported
into `raven/knowledge/parser/deepdoc`: a layout model that says what
each region
is, a detector and recognizer that read a page carrying no text at all,
and a
table-structure model that rebuilds a grid from a picture of one. 
 Detecting boxes around text the file already spells
out exactly costs an inference pass per page to learn less, and
recognising it
costs accuracy.

The layout graph answers with a shape its own postprocessing
raises on, and its classes are DocLayout-YOLO's order rather than the
list
Both were established by running the model, and the label order is
pinned by a test.

**Tables go in as tables.** `<table>` is the only shape that keeps what
a grid
states -- which column a cell stood under, which cells are merged, which
row is
the header -- and it is the shape a model reads a table in, which is
what these
chunks are for. PDF, Word and PowerPoint all state their merges exactly,
and
they now survive as `colspan` and `rowspan`. The flat form this replaces
had to
repeat a header standing over two columns across both of them, because
there was
nowhere to record a span; it had no callers left afterwards and is gone.
Two
deviations from upstream, both about what the string is for: every
cell's text
is escaped, where upstream interpolates it raw and a cell holding a `<`
produces
markup that is no longer a table, and the span attributes are written
only where
there is a span, where upstream emits `<td  >` for every ordinary cell.

**A picture of where each chunk came from.** A chunk is a few hundred
words with
a page number on it, which is enough to cite and not enough to answer
whether
the parser read the page correctly. So every PDF chunk that knows where
it sits
carries one image: the regions it covers, cropped out of the rendered
pages and
stacked. here they are already structured in the parser's element spans,
so
the markers would only put text nobody wrote into the thing being
embedded.
The panel draws a chunk's tables as tables, parsed and
rebuilt as elements rather than injected: a person can rewrite any piece
from
that same panel, so what comes back from the store is user input however
it got
there.

**The page that reads them.** Upstream retired the knowledge page while
this
branch was out; it is rebuilt against the new architecture, and the half
that
never existed is the one a reader needs -- what a document actually
became once
it was cut and embedded. Documents sit in one-level folders and arrive
by four
routes: a file, a folder, a URL, a written note. Adding and indexing are
two
calls on the contract and nothing drains that queue on its own, so a
page that
stopped after the first left every upload saying Queued for good.

Opening a file takes the whole page: the document on the left, the
pieces the
index holds of it on the right. The left half is the file drawn as its
own
pages rather than framed by the browser's PDF viewer, which reads where
to open
once and answers to nothing afterwards -- and which nothing can be drawn
on.
Pages are rendered once and kept, and the region a piece was cut from is
washed
over the page it came from, placed in fractions of the page so the
picture's
own scale never enters the arithmetic. Clicking a piece takes the file
there;
double-clicking opens it for rewriting.

The pieces can be searched, filtered by state, turned on and off,
deleted,
rewritten and added to, one at a time or in a batch. Every one of those
was
already on the contract with no reader for it. A base's settings are
back and
fuller: how many pieces a search returns, how documents are cut, and how
much
prose comes with a table or a figure. The embedding model is a picker
while the
base holds no pieces and a stated fact once it does -- moving it then is
the
collection made again at the new width and every document re-cut, which
is not
a thing a panel does by being saved.

**An agent can read them.** The retrieval engine was there and nothing
could
reach it: no agent had a tool that opened a library. A reader now points
a
conversation at bases from the composer, the way they pin a working
directory,
and the selection rides in the same place -- the session's metadata,
bound
around the turn.

The tool takes a query and never a base. The scope is the reader's
choice, so a
model cannot reach material nobody offered it, and it is withheld where
nothing
was picked rather than offered and refused. A hit says which document
and page
it came from, because a hit a reader cannot place is a hit they cannot
check --
and the passages are pressable in the transcript, walking into the base,
the
document, the folder it is filed under and then the piece. A citation a
reader
cannot follow is a claim they have to take on trust, and the whole point
of
searching their own material is that they can go and look.

**The word segmenter and the resources.** `raven.core.Tokenizer` is
Infinity's
`rag_tokenizer`, ported: a forward and backward maximum match over a
dictionary
trie, with stemming and lemmatisation on the latin path. XGBoost is not
carried
over. None of the data lives in git -- the dictionary, the NLTK corpora
and the
ONNX graphs run to about a hundred megabytes, so `make fetch-resources`
on an
install and an optional Docker layer behind `RAVEN_RESOURCES` both point
at one
script. A checkout that could not reach the network still works, and
every
feature that reads this data says so when asked.

## Type

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

## Verification

Run on macOS against Python 3.12, with the deepdoc weights fetched (the
model
tests skip without them):

```
uv run pytest                        27450 passed, 111 skipped, 3 failed
npm run test --prefix ui-web          3276 passed
npm run test --prefix ui-tui          2106 passed
npm run type-check --prefix ui-web    clean (tsc)
npm run lint --prefix ui-web          clean (4 pre-existing hook warnings)
make lint-python                      clean (ruff check + format)
make lint-types                       clean (ty)
make lint-imports                     10 contracts kept, 0 broken
make check-source-language            clean
make check-large-files                clean
make build-ui                         built, both boot snapshots match
node ui-web/scripts/check-css.mjs     clean
node ui-web/scripts/check-class-namespace.mjs  clean
```

The three Python failures are not this branch's and were each confirmed
on the
base alone: one asks a host without LibreOffice to refuse a render and
this host
has LibreOffice installed, and two simulation cases fail on an
unmodified
checkout of the base commit.

The RPC contract was regenerated for both consumers and both match it
(`npm run gen --prefix ui-web`, `npm run gen:rpc --prefix ui-tui`, then
`gen:check`). The page's boot snapshots and region goldens were
refreshed where
the composer bar gained a button, and each records that button and
nothing else.

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

## Risk

A PDF's tables, and a Word or PowerPoint file's, are now indexed as HTML
rather
than as header-prefixed lines. Chunk text changes shape for those
documents, so
a base indexed before this and searched after it holds both forms until
its
documents are reindexed; retrieval keeps working either way, because
both forms
are text. The same applies to how much prose a table or a figure carries
with
it: the setting now reaches as far as it says, where before it stopped
at the
nearest paragraph, so a chunk cut before this keeps the narrower context
until
its document is rebuilt. Rolling back is reverting the branch and
reindexing.

The deepdoc models are optional. An install that never ran `make
fetch-resources` reads PDFs geometrically, exactly as before, and says
so when
the models are asked for by name. Nothing here reaches the network at
request
time.

Chunk crops and rendered pages are written at index time and on first
view, both
under the state directory rather than in the repository, and both are
deleted
with their document. A page is immutable for the life of its document
id, so
the route serving them caches; the document route does not. All three
routes
take ids and no path, and the two image routes answer under the
strictest
sandbox in the tree.

What an agent may search is the reader's choice and nothing else. The
tool takes
no base argument, so a model cannot name one, and it is absent from the
schema
entirely for a conversation that named none -- a lane nobody pointed at
a base
is unchanged by this branch. The bases a session carries are stored
beside its
working directory and travel no further.

- [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-10-12 19:05:16 +08:00
江国庆/Forrest
fa29b27449
feat: add the developer-only trajectory view to the web page (#877)
## Summary

`raven --dev` and `raven web --dev` now serve a trajectory view in the
web page: an icon toggle in the chat header, left of the workspace panel
button, once a conversation has content. The view lists every recorded
step of the conversation with its timing, opens the details of any step,
and draws a duration bar above the list. A normal launch is unchanged:
no capability, no toggle, `/health` reports `trajectory_view: false`,
and `raven web --dev` against a running normal service refuses to attach
and says how to proceed.

Backend (`raven/trajectory`, `raven/observability`, `raven/rpc`,
`raven/cli`):
- `entries.py` projects the span log into trajectory entries with stable
ids and a single Timing Owner per logical span, so the bar never charges
a duration twice; broken records keep unique ids and in-progress spans
charge nothing. A turn opens with `user.input` and closes with
`turn.end`, which owns the turn's whole clock. The projection marks the
rows the list need not show (`meta.hidden`: a turn's end that repeats
the turn's last model output word for word, a turn's end of a turn that
finished ok with nothing recorded in it, an internal step that recorded
nothing) and what every model input adds to the conversation before it
(`meta.delta` first / continued / independent / unknown, with
`new_from`, `echo_at` and `message_count`, proven by an ordered prefix
over the v2 message references within one chain and purpose, the
predecessor's own output written back into the history not counted as
news). Tool results that trip an error rule (an error key, a true
is_error, a false ok / success, an error status word) fail the output
entry with the rule as evidence. A model input's row previews the first
message with text that is not a system one of what the call brought,
read from an inline payload or learnt by bounded repair reads the index
queues, which keep at most five probes per input and treat a failed read
as terminal. A shell that a long tool list pushes past the 64 KiB
preview read still gives its message references, which precede the
tools; an input whose references cannot be read at all leaves unknown
only the input it may have preceded directly. A span whose preview pass
raises (a result nested too deep to parse, a pointer that cannot name a
file) marks its own entry unreadable and never stops the session's
index.
- `observability/purpose.py` names the purpose of each model call
through a context variable that the `llm.call` span records as
`llm.purpose`; the main loop (its wrap-up when the iterations run out
included), watch work, titles, the permission judge, DAG verdicts,
memory extraction, the skill gate and playbooks each set theirs around a
call that records an `llm.call` span, so side questions are told apart
from the main line.
- `index.py` indexes one session's spans incrementally across the
archive chain and the active file, verifies log identity on open,
detects same-size rewrites, serves change snapshots with cursors bound
to an epoch and a revision (up to four list walks at once), and queues
the one blob read a continued input needs for its preview. One index
refreshes one scan at a time, even when the request that started a scan
was cancelled; a spilled sub-agent trace whose first log file was
removed is recovered from the files still there, and the gap is counted.
- `details.py` describes an entry's blocks and reads them in pages under
bounded limits, with integrity findings (missing, outside the store,
oversized, unreadable artifacts) built from the same pass. A
memory.feedback step's skills carry the names its own turn's
skill.inject step recorded. The usage block is attributes only, the
timing block is left out when nothing was charged, empty optional blocks
are left out, the tool block is gone (its fields live in timing and
error), an outline block lists a message list page by page (role, size,
first words and the cursor of the page each row starts, read from the
first 8 KiB of a large message) so a long prompt can be folded before it
is read, and two blocks under the raw record serve the files the span
names: a directory with the recorded size and a cursor per file, and one
file's content by its cursor, as JSON when it parses and text otherwise,
saying when it was cut at the 512 KiB read limit or to fit one response.
- Five RPC methods, `trajectory.state`, `trajectory.list`,
`trajectory.changes`, `trajectory.detail` and `trajectory.block`, with
error codes -32020 (disabled), -32021 (entry not found), -32022 (cursor
expired) and -32023 (revision changed); the `trajectory-v1` capability
is announced only by a process launched with `--dev`, which `web`,
`serve` and `gateway` all accept, and which the page-triggered upgrade
carries into the relaunch; a root `--dev` ahead of a subcommand is
refused with the form that works. Detail and block reads refresh the
index first, and while a rebuilt index is still scanning, an entry it
has not reached yet is answered with its new epoch rather than as gone;
response pages are measured in the UTF-8 bytes the transports send.

Frontend (`ui-web/src/features/trajectory`):
- The icon toggle and the parked conversation scroller; the fixed-row
virtual list over the index's visible rows, with live appends followed
near the tail (a selection from the bar or a link brings its row into
view once and leaves the following alone), stable selection, and
per-session memory of the place, the selection and the zoom. Hidden rows
stay out unless "show hidden entries (n)" is on or a link pointed at
one, which reveals it with a marked edge. That switch and the bar's
duration threshold (a slider over detents from 0 to 1000 ms, applied to
the bar only) are viewer preferences in localStorage, where an earlier
build's switches are migrated.
- The details pane: tabs per block with arrows when they overflow,
on-demand paged reads, an 8 MiB cache budget and a page window that lets
its stalest page go but never the one just asked for, recovery through
revision and epoch changes with bounded retries, and a place in the
page's Escape order. Relations resolve to links by (trace, span); the
usage block is six labelled rows with unrecorded cache counters said so;
an unreadable artifact reads as missing data in red. The messages tab
lists the outline on its own, folds the messages the model had already
seen and opens the new ones, draws only the rows near the viewport and
reads bodies for the open rows in that window; a row whose page the
cache let go folds again until asked for, a row a page was cut short of
to fit one response is read by its own cursor, a page that failed to
read is said in place with a retry, and an outline walk cut short is
taken up again on return. A JSON node draws its children two hundred at
a time. Under the raw record every file the span names is headed by its
attribute and shown as a JSON tree or text; contents are read by their
own cursor only for open files near the viewport, placed by where they
stand on the page, two at a time, kept apart from block pages, and let
go stalest first when the budget is short, to be read again only on
request.
- The duration bar on a canvas above the list: a fit that goes dense
when the rows outnumber the minimum slots, a spread with a frozen unit,
wheel zoom about the pointer, drag to pan with the anchor carried along,
a delayed click that checks the world it was made in, a pick list for
dense blocks placed within the window, a hidden turn end's time as the
turn's band under its blocks, a green dot above the selected entry's
block and a red one below a failed one, the summary in the band's hover
and the tools' title, a sideways wheel or swipe (or Shift with the
wheel) panning a zoomed bar, and a zoomed view that keeps its place on
the next entry when the threshold takes its anchor away.
- 223 `gui.trajectory.*` catalogue keys in both languages, the kind
vocabulary covering every kind the index emits with zh labels of at most
four characters; the TUI catalogue regenerated.

Docs: `commands.md`, `webui.md` and `webui.zh.md` describe the developer
launch; `CONTEXT.md` and `ui-web/CONTEXT.md` define Trajectory Entry,
Timing Owner, Message Delta, LLM Purpose and Trajectory View.

## Type

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

## Verification

Python, compared with the main commit this branch is based on (61269654)
by test nodeid, same command and environment in both trees (`uv sync
--frozen --python 3.12 --extra dev --dev`, then `uv run --frozen
--python 3.12 --extra dev --dev pytest tests/ -q -p no:cacheprovider
--junitxml=...`):
- main: 52 failed, 27541 passed, 143 skipped (all environment-dependent:
subagent probes, a2a interop, whatsapp, everos, ...)
- branch: 52 failed, 27786 passed, 143 skipped, the same 52 as main, so
no test that passes on main fails here; tests collected only on the
branch: 245 (all added by this PR)
- `uv run ruff check .`: All checks passed; `uv run ruff format --check
.`: already formatted; `make lint-types`: All checks passed

Web UI (`ui-web/`):
- `npm run gen:check`: generated.ts matches the contract (215 methods)
- `npm run type-check`: 0 errors; `npm run lint`: 0 errors, 4
pre-existing warnings outside this change
- `npx vitest run --maxWorkers=24`: 231 files, 3493 tests passed (the
`scripts/gates/*.test.mjs` gates included)
- `npm run build && python3 build.py`: the build matches the boot
goldens, which this PR changes by one node each, `div#trajHost`
(`boot-stub.txt` 344, `boot-live-noserver.txt` 343,
`src/test/__golden__/region-app.txt` 189 lines)

TUI (`ui-tui/`): `npm run lint:rpc` in sync, `npm run lint:i18n` up to
date, `npm test`: 144 files, 2098 passed, 13 skipped.

Repository gates: `make check-source-language`, `make check-large-files`
and `git diff --check` exit 0; `uv run --frozen --group docs mkdocs
build -f docs-site/mkdocs.yml --strict`: built with no warnings.

End to end, on a real service with headless Chromium (scripts, logs and
screenshots kept outside the repository; run on this branch at its head,
every review change in): `raven web --foreground --dev` on a freshly
built fixture home with thirteen sessions (slow, failed, parallel,
nested sub-agent trace with injected skills, rotated archive, broken
artifacts, a 45-message prompt continued twice and a side question, a
240-message prompt, a turn whose end recorded nothing, a tool round
trip, a span naming thirteen small and another naming twenty large
files, empty, 10002 entries). The expected entries, with their hidden
marks, deltas and failure rules, are derived from the fixture definition
by the recording rules; the indexer and the paged `trajectory.list` walk
are checked against that list first, and the page is checked against it
after. 185 checks passed: the toggle and the parked scroller, the
visible rows' ids and order with hidden replies left out and listed
again under the switch, failure marks including a result that carried an
error key, integrity wording per broken artifact, the virtual window
bound and both ends of the long list, the details tabs, relation links
across traces, the usage rows, the messages tab folding the old rows and
opening the new ones as a window over the pane's viewport, a 240-message
list reading only the pages in view, letting the stalest pages go on the
way down and reading a folded row back on request, a feedback step's
skills under their own turn's names, a turn whose end recorded nothing
hidden while a failed one stays, the call after a tool round trip
previewing the first result with its predecessor's echo folded, the
duration threshold at 200 ms and 1 s, sideways panning, every file of a
span headed and read as it comes into view, large files each read once
with the earliest released and read back on request, a file's tree
folding to bring the next file in, the bar above the list, the turn's
band and its hover, the green and red dots read from the canvas, the
short filter, a slot doubling under a x2 wheel, drag by the pointer's
travel with the anchor kept across live appends, dense slots in
proportion at the scale ceiling, the summary hover in the gap between
blocks, pick list placement in tall and short windows, measured column
widths per language, tab arrows under overflow, theme and language
switches, viewports of 1200, 800 and 320 px; then a normal `raven web`
with no toggle, and `raven web --dev` against it exiting 1 with the
stop-first message while the service kept running.

## Risk

- [x] Security impact considered: the view is served only under `--dev`;
the RPC methods answer -32020 otherwise, artifact reads stay inside the
trace store with the 512 KiB cap, and the page reads through the
existing authenticated channel.
- [x] Backward compatibility considered: no existing RPC method, session
file or span format changes; the one new span attribute (`llm.purpose`)
is additive; a normal launch behaves as before. Known recorder gap, left
for a follow-up: `semconv.turn` reads the turn's reply from a tuple and
records `{"content": null}`; this PR only hides such empty turn ends.
- [x] Rollback path is clear for risky changes: revert this PR; it adds
a feature behind a flag and no migration.

## Related Issues

N/A

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
2026-10-12 11:33:11 +08:00
knqiufan
27636d1337
fix: keep approval Escape from stopping the running turn (#868)
## Summary

Pressing Esc on an approval card previously denied the request and then
reached the page's stop handler, cancelling the running turn. Clicking
the Deny button only denied the request, even though that button
displays Esc as its shortcut.

- Consume Escape in both permission and confirmation cards after
answering deny. The turn can continue to respond to the refusal; a later
Escape follows the existing page close order and stops only when no
higher layer is open.
- Cover all five permission layouts, confirmation cards, editable
fields, the running-turn handler, layer priority, and approvals parked
in another conversation.
- Update the keyboard contract, stale comments, and both permission
guides. Use the existing portable path helper in the CSS gate so the
complete WebUI suite can run on Windows.

## Type

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

## Verification

Commands below ran in ui-web unless prefixed with uv or git.

- `npm test -- src/features/composer/approve.test.ts
src/state/escapeOrder.test.ts src/features/composer/credential.test.ts
scripts/gates/settings-drawer-css.test.mjs --maxWorkers=4`: 160 passed.
- `npm test -- --maxWorkers=4`: all 3194 tests in 214 files passed. Nine
denial/bubbling cases failed against the original handlers before the
fix.
- `npm run lint`: passed with four existing React hook warnings in
unchanged files.
- `npm run type-check` and `npm run gen:check`: passed.
- `npm run build`: passed.
- `uv run python ui-web/build.py`: passed; both stub and
live-without-server boot snapshots matched.
- `node scripts/check-page.mjs`: passed; the assembled page and its two
scripts validated.
- `uv run python scripts/check_large_files.py origin/main`, `uv run
python scripts/check_source_language.py origin/main`, and `git diff
--cached --check`: passed.
- `uv run pre-commit run --files docs-site/docs/permissions.md
docs-site/docs/permissions.zh.md ui-web/CONTEXT.md
ui-web/scripts/gates/settings-drawer-css.test.mjs
ui-web/src/features/composer/approve.test.ts
ui-web/src/features/composer/approve.ts
ui-web/src/features/composer/credential.ts
ui-web/src/state/escapeOrder.test.ts ui-web/src/state/escapeOrder.ts`:
all applicable hooks passed.

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

## Risk

Esc now has the same deny-only behavior as the card's button. Users can
press Esc again to close the next layer or stop the turn. Denial still
refuses the action; the permission decision and allow shortcuts retain
their existing behavior.

Reverting the squash commit restores the previous combined deny-and-stop
shortcut.

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

## Related Issues

Fixes #852

Co-authored-by: Codex <noreply@openai.com>
2026-10-10 17:40:18 +08:00
clearlove13
f77d7448ca
fix(config): translate the approval card's security note in the zh UI (#857)
## Summary

- `change_view` now sends `sensitive_key` (the path a reason belongs to)
beside the English `sensitive` sentence, so the card can translate the
note; the sentence itself stays untouched because `raven_config
describe` shows it to the model.
- The approval card renders the note through
`gui.confirm.cfg.why.<path>` and falls back to the English sentence when
the catalogue has no entry.
- `i18n/messages.json` gains every reachable reason (19 catalog settings
+ 70 channel fields, counting the host's enabled / allow_from /
workspace socket fields) in both locales;
`ui-tui/src/i18n/messages.generated.ts` regenerated from it.
- New `tests/test_i18n_sensitive_notes.py` walks the catalog and the
channel specs and holds the catalogue to them: an entry exists per
reason, the en column equals the source sentence, and zh is present, so
new reasons cannot regress silently.

## Type

- [x] Fix

## Verification

- [x] Relevant tests pass locally: `uv run pytest
tests/test_i18n_sensitive_notes.py tests/test_config_self_surface.py` ->
105 passed; `uv run pytest tests/test_raven_config_tool.py` -> 131
passed; `npx vitest run src/features/composer/approve.test.ts` -> 50
passed
- [x] Relevant lint / type checks pass locally: `ruff check` + `ruff
format --check` on the changed files; `ty check` at the pre-change
baseline (18 platform-only diagnostics on Windows); `npm run
type-check`; eslint on the two changed web files; `npm run gen:check` ->
generated.ts matches the contract (205 methods)
- [ ] User-facing docs or screenshots are updated when needed: not
needed, catalogue strings only

## Risk

- [x] Security impact considered: only a translated rendering of an
existing warning is added; the English sentence remains the fallback and
the model-facing copy is untouched
- [x] Backward compatibility considered: `sensitive_key` is additive,
and a surface that ignores it keeps the previous behaviour
- [x] Rollback path is clear: plain revert, no data or protocol
migration

## Related Issues

Fixes #851
2026-10-10 17:33:12 +08:00
ypflll
c3d2821303
feat(playbook): carry a Persona as a saved Harness a session can run as (#709)
## Summary

The engine half of Personas. A stored Playbook could hold a worker table
and a turn could generate one, but nothing let a person describe the
assistant they wanted, keep it, and come back to it.

**Schema v2** separates three concepts. A reusable artifact carries a
**Harness**, a **Workflow**, or both: the Harness is the durable worker
table bound into a turn, the Workflow is the DAG compiled from one
accepted successful run, and a **Run Record** is the per-execution
evidence, kept beside the artifact and never loaded as one. Schema v1
keeps loading through the `dag` and `prompt` modes.

**A Harness gains a coordinator.** `_SeatPlaybook` carries the four
Harness roles and `CoordinatorPlaybook` / `SubPlaybook` are the two
seats that wear them, so the main seat gets the surface a worker already
had rather than a parallel one. A workers-only payload is normalized on
the way in, so Personas written before this keep loading. Two demands
are contract rather than prose: a named missing-input gate must be a
generated `intake` on the coordinator, and a boundary depending on
tool-call arguments must be a `judge` on the seat making the call. Host
Raven is excluded from the persona roster at the candidate layer.

**Binding needs no new process.** `bind_charter_for_turn` is the
counterpart of `bind_delegate_for_turn`, so `load_playbook` activates a
stored Persona's main seat in the same call that activates its workers.
What a session binds is a snapshot rather than a name to look up later,
carried in the session's own metadata, so editing or deleting the
library entry does not rewrite or break a conversation already running
on it.

**RPC**: `session.create` takes a Harness to open on,
`session.set_harness` reports / binds / unbinds, and `playbooks.list`
grows a `coordinator` flag.

## Scope change

This PR was the whole feature; it is now **the backend only**. The
persona page and the shell wiring are being reworked and will follow in
their own PR, which is why they are not here. The two `rpc/generated.ts`
files stay with this one because the `ui rpc contract` gate reads them
against `openrpc.json`.

Nothing here has a caller yet: the RPC surface grows, a Playbook gains a
shape, and no existing path changes behaviour.

This also supersedes #568, now closed -- every file it added is here.

## Type

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

## Verification

```
ruff check / ruff format      clean (1782 files)
pytest (full)                 27643 passed, 8 failed
coverage_gate diff            91.34% (threshold 90)
gen-rpc-client --check        matches the contract (209 methods)
commitlint / commit messages / source language / large files
```

The 8 failures are environmental and fail the same way on plain `main`:
five proxy-credential redaction tests, the node-dir resolver, the
subagent read test, and one runtime-checkpoint timing test that passes
three times out of three when run on its own.

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

## Review history carried over

Both blocking threads raised against the earlier combined branch were
answered and closed before the split: the refinement poll that accepted
the draft it started on, and the staged Persona that outlived the draft
it was made for. Both fixes live in the page, so they travel with the
frontend PR.

LivXue's three non-blocking notes are in this half. One is addressed
here: `default_generation_mode`'s `persona` value never reached the
guard that mints one, and the field now says so instead of describing
itself as a fallback that would. The behaviour is deliberate and
unchanged -- read as a default it had a reader typing "hi" spend a model
call on a Harness. The other two (the missing `error=` on a cancelled
capture's run record, and the `set_preselected` path no producer ever
writes) are left for a follow-up; the second one also needs
`CONTEXT.md`'s discovery contract corrected with it.

## Risk

No behaviour change for a turn that asks for nothing. Rollback is a
revert of the merge commit; stored v1 Playbooks keep loading.

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

Co-authored-by: yao pengfei <yaopengfei@evermind.ai>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-10-10 11:28:13 +08:00
Handsome-wzw
a5652e8fa9
fix(ui-web): list the models messages went out on as recently used (#887)
## Summary

The composer's model picker heads its list with "Recently used", but it
recorded the last models picked in the picker, not the models messages
went
out on. A model picked once and never sent with stayed in it, and the
model
every message actually ran on -- a default set in settings, never picked
--
never appeared, not even right after a send. On a working install the
list
showed two models that no message had gone out on in two weeks, and left
out
the default that carried every turn.

- `features/model/recent.ts`: the list now records models used. Its doc
comment says when it is written and why the pick-based rule (from #669)
  was replaced.
- `features/model/source.ts`: `chipModel()` reads what the composer's
chip
names -- the model and the account the turn runs on -- or null while the
account is not known (such a row could never be shown, and kept it would
  push a real one out of the three); `rememberUsed()` records one.
- `state/session/runtime.ts`: a message that starts a turn of its own (a
first
message on a draft, or a message on an idle conversation) reads the chip
as
  it leaves and records that pair once `turn.send` is answered and not
refused. A refused send records nothing, and a pick made while the
message
is on its way does not stand in for it. The first message of a draft
whose
staged model `applyStagedModel` saw refused records nothing either: that
turn runs on the model the session already had, which the chip shows
only
once its reload lands. The refusal is forgotten when that reload lands
or a
send reads it, so a conversation the sub-agent roster made does not mute
  its first send long after the chip is right. A message merged into a
running turn rides on the model that turn started with, recorded when it
  started.
- `features/model/store.ts`: a pick in the picker no longer records
anything.
- The list moves to its own storage key, `raven.models.used`. The old
`raven.models.recent` holds picks that may name models no message ever
went
  out on, so it is not read, and the first write removes it. The list
  therefore starts empty after this change and fills as messages go out.

No layout change: the same group, rows and order.

## Type

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

## Verification

- `ui-web`: `gen:check` clean, `type-check` clean, `eslint .` 0 errors
(the
same 4 warnings as main, in other files), `npx vitest run` -- 214 files,
  3216 tests passed; build and both boot snapshots match their goldens.
`ModelPicker.test.tsx` now seeds the list the way a send does and adds:
the
default a message went out on is listed though never picked; a pick with
no
  message is not; the old picks are not carried over and the first write
  removes them; a chip with no known account records nothing.
`runtime.inject.test.ts` adds: a message that starts a turn records the
chip's model once the send is answered, a refused send records nothing,
the
chip switched while the message is on its way does not replace the model
it
  left on, and a message merged into the running turn records nothing.
`runtime.promote.test.ts` adds a draft's first message: the staged model
is
recorded when the server applies it, nothing when it refuses it, and the
model it left on when the chip is switched while `turn.send` is held;
and a
roster-made conversation whose stage was refused records its first send
  once the refusal's reload has landed.
- Mutations, each turning a test red: a pick recording again, a merged
message recording too, the old key read, the old key left behind, a chip
with no account recorded, a refused staged model recorded anyway, a
model
recorded before the send is answered, the chip read when the answer
lands
  rather than as the message leaves, a draft's first message recording
nothing, a draft's first message reading the chip after the answer, and
a
  refused stage not cleared when its reload lands
- Real browser, on an isolated gateway running this branch (its own home
holding only a made-up key, its own ports, channels off): with an empty
  list, a message sent on the default model; the picker then listed that
model under "Recently used", marked current, though it was never picked.
Picking another model without sending left the list as it was. No
console
  errors.
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and
  `scripts/check_large_files.py` on the merge base, and the prospective
  squash header through `commitlint` -- all clean

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

No user-facing doc or spec describes the picker's recent list.

## Risk

User-visible change: "Recently used" lists the models messages went out
on in
this browser, latest first, three at most; a model picked and not sent
with
no longer appears, and the default does once a message goes out on it.
The
first time the page loads after this change the group is absent until a
message is sent, since the old pick list is not carried over. It is
still
per browser (localStorage), as before. Rollback is a plain revert; the
old
key is removed on the first write, so a revert also starts from an empty
list.

- [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-10-10 10:40:47 +08:00
Dizhan Xue
9c893bb65e
fix(*): trust the system certificate store and stop unverified Codex retries (#878)
## Summary

Behind a TLS-inspecting corporate proxy, or against a company-hosted
gateway signed by a private CA, `raven onboard` failed with
`CERTIFICATE_VERIFY_FAILED` even with the corporate root installed in
the operating system (#637). httpx, LiteLLM and the OpenAI SDK verify
against certifi's bundled roots unless told otherwise, so the
operating-system store was never consulted on the paths that reach a
model. aiohttp, urllib and websockets read OpenSSL's defaults instead,
so one process trusted two different sets of roots depending on which
client made the call.

What changes:

- `raven/security/tls.py` (new): `use_system_ca()` injects truststore,
so every TLS context built afterwards is verified by the operating
system (CryptoAPI on Windows, the Security framework on macOS, OpenSSL's
default paths on Linux). A bundle a caller loads into a context is still
honoured: on Linux it joins the store, on macOS its roots become extra
anchors, on Windows it is tried when the system roots fail. So every
root trusted before stays trusted. `RAVEN_NO_SYSTEM_CA=1` opts out,
parsed like `RAVEN_NO_UPDATE_CHECK`.
- `raven/cli/entry.py` (new) is now the entry of both the console script
and `python -m raven`, the form the web supervisor starts its gateway
with. It switches trust before importing the CLI, because the CLI's
imports reach aiohttp (through the sub-agent backends), and aiohttp
builds its default context when it is imported. `raven/cli/commands.py`
no longer starts the CLI when run as a script, which skipped the switch;
pointing it at the entry would not have helped, since by then its own
imports have built aiohttp's context.
- The provider probe names a certificate that fails verification
`certificate_untrusted` instead of `network_error`. It checks for that
ahead of the proxy branch: through a proxy that answered the tunnel, a
refused certificate used to be reported as `proxy_unreachable`. The
Codex check (its backend's list of the account's models), MiniMax's
token renewal (which reported `oauth_token_missing`) and the sub-agent
key prompt's probe name it too. LiteLLM's Copilot token exchange and its
ChatGPT renewal drop the handshake error before Raven sees it, so those
still read as the credential.
- The three surfaces that read the probe say so. `raven onboard` and
`raven provider test` no longer send the reader to check the network,
proxy or VPN; their hints name the three causes: a CA to add to the
system certificate store; macOS and Windows refusing a certificate by
their own rules even when `SSL_CERT_FILE` trusts its CA, which
`RAVEN_NO_SYSTEM_CA=1` turns off; and an expired certificate, or one for
another host, which is the server's to fix. `raven onboard` offers the
menu a network error gets (re-entering the key cannot fix a
certificate); the web Settings page has its own line, in English and
Chinese, in `i18n/messages.json` and the TUI's catalogue generated from
it.
- The RPC contract's description of the model catalogue's `status`
(`rpc-schema/openrpc.json` and both generated clients) now lists the
probe's real words. It named `unauthorized`, which the probe never
returns (a 401 or 403 is `invalid_key`), and missed `proxy_unreachable`
as well as the new status.
- The Codex provider no longer retries a request whose certificate
failed verification with verification turned off (`verify=False`). The
second attempt carried the ChatGPT OAuth bearer token and the whole
conversation to whoever presented the certificate (a captive portal, a
hostile network, a proxy that re-signs TLS), and on a network like the
one in #637 it is what would keep Codex working unverified while every
other provider fails. The retry dates from the initial import;
`_request_codex` loses the `verify` parameter that existed only to carry
it.
- `raven upgrade` and the page's Update verify against the same store as
the release lookup. The upgrade helper runs on the base interpreter,
outside the tool environment that holds truststore, and fetched the
release lists with urllib's default context; uv fetched the rest with
its bundled roots. When the spawning process itself verifies against the
system store, it now copies truststore into a fresh temporary directory
and hands the helper its path, as it hands over the marker path; one
that opted out, or never went through `cli.entry`, hands over nothing
and needs no truststore to say so. The helper loads the copy before its
first download and deletes it, and gives `UV_SYSTEM_CERTS` (and
`UV_NATIVE_TLS`, which older uv reads) to uv's own calls only, so the
Raven it relaunches inherits neither. A copy, because
`inject_into_ssl()` imports requests and urllib3 wherever it finds them,
and the tool environment's belong to what uv is about to rewrite.
- Quick Start, in both languages, gains a section on corporate proxies
and private CAs: WSL2 does not see the Windows store, and the EverOS
memory server and Node-based agents run as separate programs that need
`SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS` in the shell profile.
`SSL_CERT_FILE` must name a complete bundle that exists, since httpx
refuses to start with a missing one:
`/etc/ssl/certs/ca-certificates.crt` on Debian, Ubuntu and WSL, and one
built from `/etc/ssl/cert.pem` on macOS. A note says macOS and Windows
apply their own certificate policy and names `RAVEN_NO_SYSTEM_CA=1` as
the way back.

The LiteLLM warning in the issue ("Failed to fetch remote model cost map
... CERTIFICATE_VERIFY_FAILED", with `SSL_CERT_FILE` exported) is not
LiteLLM building its own store. That fetch is a plain `httpx.get`, which
reads `SSL_CERT_FILE`, and the variable replaces the whole trusted set:
with a corporate-only PEM the gateway verifies while
raw.githubusercontent.com, signed by a public root, no longer does.
Measured with a private CA: corporate-only PEM, warning; certifi plus
the corporate root, remote fetch succeeds.

Not covered, by construction: the EverOS server is a separate `everos`
executable and Node-based agents are not Python, so an injection in this
process cannot reach them. The new docs section gives them their
environment variables.

`uv.lock`: adding truststore re-resolved the lock (uv 0.11.25, revision
3 kept). Besides the truststore entries, five packages' dependency edges
lose a marker: matrix-nio, h2, aiohttp-socks, aiologic and culsans. Each
dropped marker is implied by the only path that reaches its package
(matrix-nio, and through it h2 and aiohttp-socks, only where
`sys_platform != 'win32'`; culsans and aiologic only below Python 3.13),
so the resolved set is unchanged on every platform. uv 0.12.23 produces
the same edges and also rewrites the lock to revision 5, so it was not
used; both versions accept the committed lock under `uv lock --locked`.

## Type

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

## Verification

Red first, on the base: the end-to-end `raven provider test custom`
against a gateway whose root only the stand-in system store holds exits
1 with `network_error ... unable to get local issuer certificate` under
both launch forms, and its opted-out twin prints "Check network /
firewall / VPN settings"; the probe test returns `network_error`, and
through a CONNECT proxy `proxy_unreachable`; the onboarding menu offers
`rekey` for a certificate failure; the web note falls to
`probe_unknown`; and the Codex test's endpoint receives `Bearer
tok-secret`, with the captured log line `SSL certificate verification
failed for Codex API; retrying with verify=False`.

Mutations, each applied and then restored byte for byte:

- the entry no longer switching trust: both end-to-end trust cases fail;
- the switch moved after the CLI import: only
`test_trust_is_settled_before_the_cli_builds_a_context` fails;
- the classifier accepting any `ssl.SSLError`: the plain-HTTP case
fails;
- the certificate check placed after the proxy branch: the proxy case
fails.

Review round two, red first at the round-one head: against an endpoint
signed by a root no store holds, the Codex check returned
`network_error`, MiniMax's token renewal `oauth_token_missing` and the
sub-agent key probe `network_error`; both hint tests failed on the
missing opt-out; the guard scan found `raven/cli/commands.py`; and the
upgrade tests found nothing handed over. Round-two mutations, each
applied and then restored byte for byte:

- the classifier matching `CERTIFICATE_VERIFY_FAILED` in the message:
the new macOS and Windows cases fail (282 of 282 stayed green before
them);
- 17 single-construct mutants of the upgrade hand-over (not switching,
not putting the copy on the path, keeping it, hiding a failed load,
leaving the path in the environment, not telling uv, overwriting a uv
setting the user made, dropping the older uv name, telling uv without a
copy, uv not given its environment, passing on an inherited path,
importing truststore instead of reading whether this process switched,
handing over without that check, handing over always, handing over no
copy, and keeping a copy no helper started, at each spawn site): each
fails at least one test;
- the copy failure's warning and its cleanup: each fails the
copy-failure test.

Commands and results, at the head after rebasing onto `main`. The
commits `main` gained since round one touch none of this branch's lines:
`git range-diff` shows every commit unchanged, and the aggregate
patch-id is the same before and after.

- The touched Python test files (`tests/test_security_tls.py`,
`tests/test_cli_system_ca.py`, `tests/test_config_update_providers.py`,
`tests/test_cli_onboard_commands.py`,
`tests/test_cli_provider_commands.py`,
`tests/test_cli_subagent_setup.py`, `tests/test_updates_upgrade.py`,
`tests/test_openai_codex_provider.py`), the Codex provider's neighbours
(`tests/test_providers_first_byte_budget.py`,
`tests/test_provider_protocol.py`) and the i18n tests, in full: 1010
passed.
- Full suite with branch coverage, `pytest -q -p no:randomly --cov=raven
--cov=raven_everos --cov-branch` on the all-extras environment with the
box proxy variables unset: 2 failed, 27750 passed, 119 skipped. Both
failures fail the same way on a clean tree of the new merge base under
the same interpreter, so neither is introduced; they are local to this
box (an `npm` on its PATH, and running as root):
-
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
-
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
- `scripts/coverage_gate.py diff --base-ref origin/main --threshold 90`
over that run: 100.00% (57/57 executable changed lines).
- `tests/integration/test_cli_upgrade_real_uv.py`, which CI runs only in
the Windows self-upgrade job (`--noconftest`): 3 passed locally. Its
fixture calls the handoff without `cli.entry`; the `system store`
variant switches first, as `cli.entry` does, so that job runs the whole
hand-over on Windows, and the fixture prints what it handed over so
neither variant passes without its branch running.
- `ruff check`, `ruff format --check`, `ty check` over the changed
modules, `lint-imports` (10 contracts kept), `deptry raven`: clean.
- Repository gates over `origin/main...HEAD`:
`check_source_language.py`, `check_large_files.py` and
`check_commit_messages.py` exit 0.
- Generated files on the rebased tree, where `main` had also changed the
RPC schema, the message catalogue and their generated copies:
`gen-i18n.mjs --check` and `gen-rpc-types.mjs --check` (ui-tui) and
`gen-rpc-client.mjs --check` (ui-web) exit 0.
- Round two changes no file under `ui-web`, `ui-tui` or `rpc-schema`;
these were measured at round one:
- ui-web, `node node_modules/vitest/vitest.mjs run
src/features/settings/SetupBodies.test.tsx
scripts/gates/i18n-keys.test.mjs`: 33 passed; `scripts/gates`: 46 files,
205 passed; `tsc --noEmit` clean, its `--listFiles` resolving the edited
files inside this tree; ESLint clean on the three files.
- ui-tui, the steps of TUI checks: ESLint 0 errors; `lint:rpc` and
`lint:i18n` pass; `tsc --noEmit` clean; the build passes; `vitest run`
has 9 failures in 4 files (renderer and typing-burst tests), the same 9
that fail on a clean worktree of the merge base on this box, so none is
introduced.
- RPC contract: `node scripts/gen-rpc-client.mjs --check` (ui-web) and
`node scripts/gen-rpc-types.mjs --check` (ui-tui) exit 0, each generated
file differing from the base by the one description line; the 9 Python
test files that read the schema, 798 passed.
- Docs: `mkdocs build --strict` clean, with the new paragraphs on the
English and Chinese pages; `tests/test_docs_site.py` and
`tests/test_living_docs.py` pass in the full suite.

The end-to-end cases run on Linux only. They stand the system store in
with OpenSSL's directory store through `SSL_CERT_DIR`, and name a bundle
of public roots in `SSL_CERT_FILE` so that httpx cannot pass by reading
`SSL_CERT_DIR` itself. Verification on macOS and Windows was read from
truststore 0.10.4's source, not run. The upgrade helper's tests share
the limit: on Linux truststore and the standard library read the same
store, so they show the hand-over (the copy loads on the base
interpreter under `-I` before the first download, and uv alone is told),
not the Keychain difference it exists for.

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

## Risk

- Every Raven process started as `raven` or `python -m raven` now trusts
the operating system's roots in addition to what each library bundles.
For those processes `SSL_CERT_FILE` adds to the trusted set instead of
replacing it; someone using it to narrow trust to one private root keeps
that root but also trusts the system store.
- On macOS and Windows the system verifier applies its own certificate
policy as well. A private certificate that OpenSSL accepted from
`SSL_CERT_FILE` can be refused there if it breaks that policy;
`RAVEN_NO_SYSTEM_CA=1` restores OpenSSL's verification.
- On macOS and Windows truststore also verifies the client's chain on
server-side contexts, refusing a client that sends none. Raven builds no
server-side TLS context: it serves plain HTTP on localhost.
- Upgrades verify their downloads the way the release lookup does: on
macOS that includes Apple's certificate policy, which the helper's
OpenSSL did not apply. uv is told to use the system store only for the
upgrade's own calls, and a `UV_SYSTEM_CERTS` or `UV_NATIVE_TLS` the user
set is kept.
- Behind a proxy that re-signs TLS, Codex requests now fail with the
certificate error instead of continuing unverified. Trusting the proxy's
root, in the system store or in a complete bundle named by
`SSL_CERT_FILE`, is the remedy.
- Startup: about 100 ms warm and 270 ms cold, measured on Linux, mostly
truststore importing urllib3 and requests to patch their references.
- Rollback: `RAVEN_NO_SYSTEM_CA=1` restores the previous trust per
process, and an upgrade started under it hands its helper and uv
nothing; the Codex change has no switch, by design. Reverting the squash
commit removes both.

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

## Related Issues

Fixes #637

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-10 10:40:12 +08:00
Handsome-wzw
b56da140aa
fix(ui-web): say there is no new key instead of sending an empty save (#884)
## Summary

On a connected provider's sheet (Settings > Model providers), Update --
or
Enter in the key field -- with no new key in the field sent
`model.save_key`
with the slug alone. That happens with the field empty, and since #881
with
the stored key the eye revealed, unedited, which is deliberately not
sent
back. A key-shaped provider draws no address in that card, so the
request
carried nothing to save: the server refused it -- or, for Bedrock's
ambient
credential, accepted it and changed nothing -- and the page toasted its
English refusal ("OpenRouter requires an API key") while the key sat on
screen.

- `ProviderDetail.tsx`: when the provider is connected, the field holds
no
new key and the card has no address to send, the page sends nothing and
  says so in the pane's own error line (where "Enter the API key first"
already appears for a provider not yet connected): there is no new key
to
  save; to replace the saved one, type a new key and press Update. A
provider whose address is drawn in that card (a key-less vendor reached
by
  address) still saves the address, as before.
- Endpoint-shaped providers (custom, Azure OpenAI, MiniMax CN) are
covered
too: the page groups them with local servers, but `model.save_key`
refuses
their save without a key, the address included. Not yet connected,
"Enter
the API key first"; connected with nothing changed, the same "no new
key"
line; connected with only the address edited, the address is saved on
its
own through `model.set_fields` -- the route the settings design gives
any
field but the key, and the one the Advanced address field already uses
--
so no key is asked for again, even with the revealed key unedited in the
  field. A save that carries a key goes out as before.
- `i18n/messages.json`: one new string,
`gui.settings.providers.key_unchanged`
(en and zh), naming the API key field since the line is drawn at the
foot
  of the pane; the TUI catalogue is regenerated.
- `docs/specs/2026-09-20-web-settings-model-section-acceptance.md`:
T3.2's
observation for pressing Update over the revealed key now reads "sends
no
  frame and the pane says there is no new key to save", and its red-when
  column fails any frame from that press.

No layout change: the message uses the existing error line.

## Type

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

## Verification

- `ui-web`: `gen:check` clean, `type-check` clean, `eslint .` 0 errors
(the
same 4 warnings as main, in other files), `npx vitest run` -- 214 files,
3211 tests passed; build and both boot snapshots match their goldens.
New
  cases in `ProviderDetail.test.tsx`: Update and Enter over an unedited
revealed key send nothing and show the message, and so does Update over
the empty field; for a custom row, nothing changed shows the same
message,
an edited address is saved alone through `model.set_fields` (also with
the
revealed key unedited in the field), an edited address with a key typed
saves both, and Connect on one not yet connected asks for the key first;
  the existing case that saves a key-less vendor's address still passes.
- `ui-tui`: `lint:i18n` and `type-check` clean; `npm test` -- 144 files,
  2111 tests passed
- Mutations, each turning a test red: dropping the new check (the empty
save
  is sent again), dropping its address condition (a key-less vendor's
address is no longer saved), leaving endpoint providers out, not asking
an
  unconnected endpoint provider for the key first, refusing an edited
  endpoint address again, and writing an unchanged one anyway
- Server side, for the claims above: `credential_status` refuses custom,
azure_openai and minimax_cn_api without a key whether or not an address
is
sent, and accepts each with one; `model.set_fields` with `api_base`
alone
  is how the Advanced address field already saves
- Real browser, on an isolated gateway running this branch (its own home
holding only a made-up key, its own ports, channels off): Settings >
Model
providers > the connected provider; eye pressed, then Update -- the page
sent only the `model.reveal_key` call, no `model.save_key`, and the pane
  showed the new message; eye pressed again, then Update over the empty
field -- no frame, the same message; the config file's hash was
unchanged;
  no console errors
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and
  `scripts/check_large_files.py` on the merge base, and the prospective
  squash header through `commitlint` -- all clean

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

No user-facing doc describes the provider key field.

## Risk

User-visible change: on a key-shaped or endpoint-shaped provider, Update
or
Connect with nothing new shows a sentence in the reader's language
instead of
the server's English refusal, and no request is made; a connected
endpoint's
edited address now saves without the key. Nothing that used to save
stops
saving: `model.save_key` refused every one of these saves (checked with
the
provider's environment variable set as well: refused, stored key
unchanged),
except Bedrock's, which it accepts and which leaves the config
unchanged. A
provider whose address is drawn in the key card saves exactly as before.
Rollback is a plain revert.

- [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-10-09 16:35:03 +08:00
Handsome-wzw
6d509a8c51
feat(*): show a provider's saved API key when the eye beside it is pressed (#881)
## Summary

On a connected provider's sheet (Settings > Model providers), the API
key
field is empty by design -- its placeholder says to type a new key to
replace
the saved one -- so the eye beside it had nothing to show. The one key a
reader could not check was the one in use. The page is never sent a key:
`model.options` reports whether one is configured and nothing more.

This reverses a rule the web settings specs record: "the eye toggle
reveals
typed text, never a stored key" (model-section design C10 and A8,
acceptance
T3.2, and the parent design's C10 and "masked" term). The owner asked
for the
key in use to be readable from the eye; each of those rules now carries
a
dated amendment (2026-10-09) saying what it was and what it is. What
still
holds: the stored key never goes back to the wire unedited, and it is
never
part of `model.options` or any other snapshot.

- `model.reveal_key` (new, `raven/rpc/methods/model.py`) reads back the
flat
`api_key` of one provider's section -- the value `model.save_key` writes
and
the field edits -- only when it is the key requests carry: an
`endpoints`
  list or Gemini's `apiKeyList` replaces the flat key outright
(`provider_endpoints`), and a flat key left behind under one answers
null.
It answers that key alone: not the rest of the section, not an
endpoint's
key, not a key the environment supplies. Unknown providers are refused
like
the other `model.*` handlers. Schema, Pydantic models and both generated
  clients carry it.
- The sheet asks for it only when the eye is pressed over an empty key
field
of a connected provider. The key fills the field as text. Pressed again
with the key unedited, the field empties back to its placeholder rather
than holding a "new" key that is the old one; an edited key is the
reader's
and stays. A key the reader typed is read back as typed, with no fetch.
A
  provider that is not connected never asks. Typing, or pressing the eye
again, retires a read still in flight, so an answer that lands after the
reader started typing a replacement does not overwrite it. Update or
Enter
with the revealed key unedited sends what the empty field sends -- no
key
-- rather than writing the stored key back (which rewrote the config and
  could restart EverOS for no change).
- `KeyInput` gains an optional `onPeek(shown)`, called before the eye
turns
and waited for, so the field does not flash empty and then fill. A
failed
  read still turns the eye (the source has already shown the error). Its
  other callers (plugins, tools, agent keys, the add-provider form) pass
  nothing and behave as before.
- The offline fixture library answers the new method with a made-up key
per
  connected row, so the demo page's eye has something to show.

No new strings and no layout change: the same field and the same eye.
`docs/specs/` carries the amendments above.

## Type

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

## Verification

- `uv run pytest tests/test_rpc_model.py tests/test_rpc_schema_match.py
tests/test_rpc_registration.py --idle-ceiling-strict`
-- 662 passed (eight new cases: the saved key read back, null when none
is
saved or after a disconnect, the key alone from a section that also
holds
an address and a secret header, null for a flat key left behind under an
endpoint or under Gemini's key list, a lone endpoint carrying the same
key
  still revealed, the environment's key not read, an unknown provider
  refused)
- `uv run pytest --ignore=tests/integration --idle-ceiling-strict` after
  `uv sync --all-extras` -- 27691 passed, 115 skipped, 3 failed:
  `test_rpc_files.py::test_a_host_without_libreoffice_says_so`,

`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
  and

`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`,
  which fail the same way on main on this machine. The one test over the
  idle ceiling is the failing simulation-suite one.
- `ui-web`: `gen:check` clean, `type-check` clean, `eslint .` 0 errors
(the
same 4 warnings as main, in other files), `npx vitest run` -- 214 files,
  3205 tests passed, including the fixture gates; build and both boot
  snapshots match their goldens
- `ui-tui`: `lint:rpc`, `lint:i18n` and `type-check` clean; `npm test`
-- 144
  files, 2111 tests passed
- Real browser, on an isolated gateway running this branch (its own home
holding only a made-up key, its own ports, channels off): Settings >
Model
providers > the connected provider, eye pressed -- the field showed the
saved key as text; pressed again -- the field was empty and masked, with
  its placeholder; no console errors
- Fifteen mutations, each reverting one part of the change, each turning
a
test red: the handler reading the key redacted, an empty key sent as an
empty string, a flat key that requests do not carry revealed, an
unedited
revealed key saved again, an unknown provider not refused, the method
not
  registered,
the source calling another method, an unconnected provider asked, a
typed
key replaced by the saved one, the revealed key kept when the eye shuts,
an
edited key emptied when it shuts, the eye opening before the key
arrives,
  an answer landing after typing overwriting the typed key, typing not
  retiring the read in flight, and a failed read keeping the eye shut
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and
  `scripts/check_large_files.py` on the merge base, and the prospective
  squash header through `commitlint` -- all clean

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

No user-facing doc describes the provider key field or its eye.

## Risk

The page can now receive a stored provider key in plaintext, which it
could
not before. The limits on that:

- one provider per call, only on an explicit press, never in
`model.options`
  or any other snapshot or poll, so the key does not ride along on every
  refresh;
- the answer is the key alone, and the RPC dispatcher logs no results;
- it adds no reach: a signed-in page could already read a stored key in
  plaintext through the CLI bridge (`provider get <slug> --show-secrets`
over `cli.dispatch`), and could replace the key or change the address
the
provider sends it to. It is behind the same sign-in and Origin check as
  every other page RPC, and it is an RPC method only, not an agent tool.

Compatibility: the method is additive. The page and the gateway ship
together; a page talking to an older gateway would get method-not-found
when
the eye is pressed over an empty field, show that error, and open on the
empty field, as before.

Rollback is a plain revert.

- [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-10-09 11:53:25 +08:00
Dizhan Xue
2f0a09dcfc
feat(*): let the image role run on an OpenAI-compatible provider (#866)
## Summary

The image role in Settings offered OpenRouter alone, although
`image_generate` already speaks the OpenAI Images API
(`/images/generations`, `/images/edits`) on any other base. A user with
an OpenAI or OpenAI-compatible provider could reach it only by
hand-editing `tools.media.image.apiKey` and `apiBase`.

`tools.media.image` gains `provider`. A section naming one runs on that
provider's address, key and headers as one group, taken from the
endpoint the key comes from and resolved at call time the way the
embedding pin is (`provider_connection`, factored out of
`resolve_provider_credentials`); the section's own `apiKey`, `apiBase`
and `extraHeaders` stand aside. Every media request sends the section's
`extraHeaders` (a new field, secret like a provider's own) after the
bearer key, the order the chat route gives a provider's `extra_headers`.
The registry declares which providers the image tool can run on
(`ProviderSpec.image_api`: OpenRouter, OpenAI, Custom), `model.options`
carries the flag per row, the roles card offers exactly those for the
image slot, and `settings.set` refuses any other. An OpenRouter pick
writes an empty provider, so existing sections keep their current
meaning. Speech and video keep to OpenRouter: their sections have no
`provider` field, so one written there is ignored on every reader, and
`settings.set` and `set_media` refuse it.

Two fixes on the same path:

- The OpenRouter key, `providers.openrouter.apiKey` or
`OPENROUTER_API_KEY`, is borrowed only by a section that calls
OpenRouter's address. A keyless section pointed at another endpoint used
to send that endpoint the OpenRouter key as its bearer token.
- Off OpenRouter, every image model goes to the Images API. The chat
route with output modalities is OpenRouter's own; an OpenAI-compatible
relay answered it with its own 404 (`model is not found`), which the
OpenRouter-only fallback did not recognise, so a model outside the
Images API name list could not generate there.

The live config reader resolves the named provider's section exactly as
boot does: every spelling, former name and field alias of it goes
through `ProvidersConfig`, which folds them into one section, and no
other provider's section is validated. A section header replaces the
key's header of the same name in any case.

raven-ppt and raven-design inherit the host's image section through the
same resolver. When raven-ppt pins an image setting, the section becomes
a snapshot read as written: it drops the provider name and takes the
Wire Model that provider uses. A pinned key or base leaves the inherited
headers behind, since they complete the host's key at the host's
address. A pinned base also clears whatever key the host resolved, so
the deck's key slot decides afresh: `PPT_IMAGE_API_KEY`, the host
section's own key, or, toward OpenRouter only, the key that pays for the
words. That closes a leak every 0.2 release has, the OpenRouter key the
host borrowed for OpenRouter's address going to a pinned deck base. On a
named provider's own address the deck sends that provider's key or none.
The launcher can outlive its raven, since a stamped home tree outranks a
checkout's own `agents/`, so it calls only what every 0.2 release has:
the reader's two-argument form, and `media_provider` looked up where it
exists.

The settings dialog's design and acceptance specs (C14, A22, A24 and
their decisions) are amended to the new rule.

Overlap: open #432 and #433 (MiniMax images and video) edit
`_generate_one`, the video tool's `execute`, a `_resolve_key` override
on each tool, and the lines beside the removed `borrows_openrouter_key`.
Their MiniMax routes return before the routing this change touches and
their overrides delegate to the base resolver, so the conflicts are
textual.

## Type

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

## Verification

- `uv run --frozen --python 3.12 --all-extras pytest -q`: 27601 passed,
7 failed, 115 skipped. The 7 fail identically on `origin/main` 3632e6040
on this machine (five proxy tests in `test_config_update_providers.py`
under the shell's proxy variables,
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
and
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
run as root); 0 introduced.
- ui-web, `node node_modules/vitest/vitest.mjs run
--no-file-parallelism` (both test roots, 214 files): 3188 passed, 0
failed, 0 unhandled errors. Measured before the review commits, which
touch no TypeScript, generated file or RPC contract.
- ui-tui, the same command (144 files): 2089 passed, 9 failed, 0
unhandled errors. The 9 are rendering tests in four files that fail with
identical ids on `origin/main`'s ui-tui on this machine; 0 introduced.
- `tsc --noEmit` in ui-web and ui-tui, `gen-rpc-client.mjs --check`,
`gen-rpc-types.mjs --check`, eslint over the touched ui-web directories,
and `ruff format --check` / `ruff check` over the changed Python files:
all clean.
- `scripts/check_commit_messages.py origin/main..HEAD`, commitlint over
the same range, `scripts/check_source_language.py origin/main...HEAD`,
`scripts/check_large_files.py origin/main...HEAD`: all exit 0.
- The new tests were written first and watched fail for the missing
behaviour, the review rounds' tests on the head before each fix. A
mutation pass then removed each construct this change adds, one at a
time: 40 Python and 3 TypeScript mutants, all killed but one, controls
green. The survivor matches a provider on its name instead of its
`route_names`, which is equivalent today because every former name in
the registry is also a field alias.
- Each commit added in review passes the touched test files on its own.
- Live, against an OpenAI-compatible relay serving
`sensenova-u1.5-lite`: before, `image_generate` with the section's own
`apiKey`/`apiBase` posted to `/chat/completions` and got 404. After, on
an isolated `raven web` in Chromium, the image row offered Custom,
OpenAI and OpenRouter (speech and video OpenRouter only), the typed id
was added to Custom as an image model and saved as `{model, quality,
provider: "custom"}`, and one call through the live config reader
returned a 2048x1536 PNG from `/images/generations` with the Custom
provider's key.

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

No user-facing documentation covers the media tools; the settings
dialog's specs carry the rule.

## Risk

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

- Security: credentials travel to fewer places. A section borrows only
from the provider it names, address and key together, and a provider
with no known address supplies no key. `tools.media.image.provider`
joins the `settings.set` whitelist with the reach the subsystem pins
already have: it moves the tool to a provider the operator configured,
and names no address and carries no key.
- Provider headers can carry credentials: they travel with the key to
the provider's own address only, a video poll or content URL on another
origin gets neither, and a media section's `extraHeaders` is masked like
a provider's. The OpenRouter default lane still borrows only the
OpenRouter key, not that provider's headers.
- A keyless image, speech or video section whose `apiBase` is not
OpenRouter's now reports a missing key instead of borrowing the
OpenRouter key. A relay in front of OpenRouter at another address needs
`apiKey` on the section.
- On such a base, a model outside the Images API name list (a Gemini
image model, say) now goes to `/images/generations` instead of
`/chat/completions`.
- Choosing a provider other than OpenRouter in Settings sets aside a
hand-written `apiKey`/`apiBase` on the image section; they stay in the
file and apply again once an OpenRouter model is picked.
- A `provider` hand-written into `tools.media.speech` or
`tools.media.video` is now ignored: that section runs on OpenRouter,
with the OpenRouter key.
- raven-ppt: a deck pinning `PPT_IMAGE_API_KEY` no longer sends the
host's `extraHeaders`, so an endpoint that also routes by header cannot
take the deck's own key; before this change no header travelled at all.
A deck pinning `PPT_IMAGE_API_BASE` without a key of its own no longer
receives the OpenRouter key the host borrowed; it needs
`PPT_IMAGE_API_KEY`, the host section's own key, or a base on
OpenRouter's address.
- The raven-ppt launcher still renders under every 0.2 release, which
lacks `media_provider`; a test runs it against a reader with the 0.2
signature.
- Rollback: revert the squash commit. The previous config models ignore
a saved `provider`, so the image tool returns to OpenRouter with the
earlier key rules.

## Related Issues

Fixes #828

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-08 17:33:39 +08:00
Dizhan Xue
0703e03544
fix(*): stop storing display-only provider addresses, which broke Gemini (#865)
## Summary

Connecting Gemini from the settings dialog stored an address nobody
typed, and that broke both halves of the provider: the key check
reported a working key as refused, and every chat went to a path Google
answers 404. This stops the dialog storing addresses it only shows,
heals installs that already hold one, makes the probe ask each affected
vendor where it actually lists its models, and moves Gemini's default to
a model Google still serves to new projects.

**Root cause.** `model.options` hands each vendor's address to the
dialog for display, and for a vendor whose spec states no default that
address is `shown_api_base`, which `registry.py` documents as display
data only. Both Connect paths seeded their address state with it and
sent it even where no address field is drawn: the Connection block in
the provider detail, and the onboarding wizard's add form. For Gemini
that stored Google's bare host. Measured on main before this change,
with a made-up key against generativelanguage.googleapis.com:

- the probe then sent `Authorization: Bearer` to `/v1/models`. Google's
native routes read that header as an OAuth token and answer 401
`CREDENTIALS_MISSING` whatever the key, so the dialog said "The provider
rejects the saved key".
- chat through LiteLLM 1.85.0, the version `uv.lock` pins, built
`/models/<model>:generateContent` from the bare host. Google answers
that path 404, so every turn failed as `model_unavailable`.

The issue reports a working chat beside the 401, which fits a section
holding `.../v1beta` instead: that base keeps chat working and still
sends the probe down the bearer path. This change fixes that case too.

**The stored address was load-bearing elsewhere.** For OpenAI and
DeepSeek the address the dialog wrote was the only thing that let the
probe find their models: with no address, OpenAI sends nothing (LiteLLM
keeps its address inside the SDK) and DeepSeek derives `/beta`, which
lists none. Stopping the write without the last commit below would have
cost dialog-connected OpenAI and DeepSeek their key check and live model
list, so the probe now knows where both list their models.

**What changes**, one commit each unless noted:

- `fix(ui-web)`: each form sends an address only from a field it draws.
The add form derives drawing and sending from one predicate, so the two
cannot part again. A local deployment still connects by the address
typed into its field.
- `fix(*)`: `ProviderSpec.is_display_only` names that address,
`set_provider_fields` stores it as no address (which also clears a proxy
the section held), and config migration 12 removes it once, with a
notice, from installs the dialog already wrote it into. Only the exact
flat address goes, trailing slash aside, in either key spelling; a
proxy, a versioned root on the vendor's own host and the endpoint list
all stay.
- `fix(config)`: a section holding Anthropic's or Google's own address
is probed the way that vendor answers rather than as a proxy. Google's
refusal of a key it does not know, 400 `INVALID_ARGUMENT` with an
ErrorInfo reason of `API_KEY_INVALID`, now reads as `invalid_key`
instead of `http_400`. The second copy of the shape check, which could
never run once an address was derived, goes.
- `fix(providers)`: Gemini's default is `gemini/gemini-3.8-flash`.
Google's deprecations page (updated 2026-10-01) says the 2.5 models are
not deprecated but limited to users who used them before, and points new
projects at 3.8 Flash or 3.5 Flash-Lite. The model leads the curated
shortlist, which the default must sit in, and the wire baseline's
default entry moves with it; that file's docstring records why.
- `fix(config)`: OpenAI and DeepSeek are filed in `_CATALOGUE_SHAPES` at
the address each lists its models from, with the bearer token. That also
reaches a DeepSeek section still holding `/beta` from before its shown
address moved to the root.
- `fix(config)`: an address that does not parse, such as `http://[`, is
reported as a network error instead of raising `ValueError` out of
`test_provider`, whose contract is a dict. The raise was in the proxy
lookup a failed request takes when no transport is injected; it predates
this change and reached every vendor.
- `fix(*)`: `is_display_only` answers no for anything but a string.
`model.set_fields` takes any JSON value, and a number there raised
`AttributeError` from that check, which the RPC answers as an internal
error; the schema refuses it again, as `config_validation_error`. The
migration, which reads the same raw values, drops the type check it
carried for this.
- `fix(config)`, three commits (the rule, a case for its trailing slash,
and a docstring correction): an address counts as the vendor's own only
when it is, as written, its bare host or the root its catalogue hangs
from (both read off the `_CATALOGUE_SHAPES` URL, trailing slash allowed)
or DeepSeek's `/beta`, which sections saved while the settings field
showed it still hold. Any other address, on the vendor's host or not, is
asked where it points, as on main, so an endpoint pasted whole, such as
`https://api.openai.com/v1/chat/completions`, reads as the 404 it is and
another port gets that port's own answer; neither is taken for the
vendor and read as a verified key.
- `refactor(ui-web)`: the Connection block names once where it draws the
address field, above the key or alone, and both places and the send read
that one value; the field is one element. Behaviour is unchanged.
- `docs(config)`: the comment describing `_CATALOGUE_SHAPES` moves above
that table, from above `_CATALOGUE_EXTRAS`.

**Decided, open to a veto.**

- #763 met the same write on DeepSeek and left already-written configs
alone on purpose. This change migrates, because the stored host breaks
Gemini's chat outright, and the dialog cannot clear it either: the
Advanced field equals its shipped default, so it offers no reset button.
-
`test_a_vendor_with_no_catalogue_endpoint_is_reported_as_unprobed_not_unconfigured`
pinned OpenAI as a vendor the probe cannot reach. OpenAI now has a known
catalogue, and it was the last vendor in the registry that rule fitted,
so the test keeps the rule with OpenAI's entry taken out. The
derived-404 test moves from DeepSeek to Z.ai, which still derives its
address.

**Not fixed here.**

- Gemini as an embedding provider. `resolve_provider_credentials` used
to answer the stored bare host for a dialog-connected Gemini, which an
OpenAI-compatible client turns into `/embeddings`, also a 404 on Google
(measured). It now answers None, so an embedding pin on Gemini reports
no usable credential instead of failing on every call. Making it work
means adding Gemini's OpenAI-compatible base,
`https://generativelanguage.googleapis.com/v1beta/openai`, to
`_PROVIDER_BASE_URL_FALLBACK`, which is left for a follow-up.
- A model picked explicitly from the 2.5 line still meets Google's own
refusal on a new project. The shortlist keeps those rows, since Google
still serves them to the accounts that used them.
- An address on a vendor's own host that is not one of its own addresses
above keeps main's probe, which for Google and Anthropic is still the
bearer path, so Gemini's `/v1`, for one, still reads as a refused key.
Widening the list needs each such address checked against what the
vendor serves there.
- A section holding `https://api.anthropic.com/v1` is probed at
Anthropic's catalogue and its key reads as verified, but LiteLLM appends
`/v1/messages` to any Anthropic base that does not end in it, so chat at
that address goes to `/v1/v1/messages` and is answered 404, on main as
here. The probe checks the key; the route chat builds from the address
is LiteLLM's.
- `tests/integration/test_provider_real_llm.py` still expects Anthropic
to be unprobed, which has not held since Anthropic's catalogue was filed
in `_CATALOGUE_SHAPES`. It fails on main the same way, and CI does not
collect that directory, so it is left alone.

## Type

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

## Verification

Each new test was run red before its fix, failing for the reason it
names: twenty Python cases and two `ui-web` tests. The rest were proved
by withdrawing, one at a time, what they hold:

- forcing the add form's send condition false fails `the add form sends
the address it draws`;
- in `is_display_only`, dropping the default guard, the trailing-slash
fold or the equality (for a prefix match) each fails
`test_only_the_address_a_spec_shows_in_place_of_a_default_is_display_only`,
and dropping the string check fails all seven non-string cases, the
migration's among them;
- in the own-address match, dropping the bare host or the trailing-slash
fold fails the bare-host case, dropping the catalogue root fails the
`/v1beta` and `/v1` cases, emptying the extra list fails DeepSeek's
`/beta`, and comparing hostnames again fails exactly the three cases for
other addresses on a vendor's host;
- in the Connection block, sending only from the field above the key, or
drawing none alone, fails `sends the address from the field it draws
alone for a vendor that takes no key`, which also fails when the send's
former condition loses its second clause, an edit that left the whole
suite green before that test; drawing none above the key fails the local
and Azure tests, and sending whatever the block holds fails the key-only
vendor's.

Python, in an environment from `uv sync --frozen --python 3.12
--all-extras`, proxy variables unset:

```
pytest -q -p no:randomly
-> 27578 passed, 115 skipped, 2 failed
```

Both failures fail identically on main at this branch's base, on this
machine only (an npm elsewhere on PATH, and root reading a file the test
makes unreadable):

```
tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for
tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing
```

Each intermediate commit's own tree passes the config and provider
suites (`tests/test_config_update_providers.py`,
`test_config_loader.py`, `test_provider_registry_data.py`,
`test_provider_catalog.py`, `test_provider_wire_model.py`,
`test_rpc_model.py`): 924 passed after the second commit, 927 after the
third.

`ui-web`, serially, with `--localstorage-file` set because node 26 on
this machine needs it:

```
vitest run --no-file-parallelism
-> Test Files 214 passed (214), Tests 3189 passed (3189), no unhandled errors
```

That run includes the 46 gate files under `ui-web/scripts/`.

Static checks:

```
ruff check; ruff format --check     -> clean
lint-imports                        -> 10 kept, 0 broken
ty check (the lint-types targets)   -> all checks passed
eslint .                            -> 0 errors, 4 warnings in untouched files
tsc --noEmit -p tsconfig.json       -> clean
node scripts/gen-rpc-client.mjs --check -> matches the contract
pre-commit run --from-ref origin/main --to-ref HEAD -> all passed, no file modified
scripts/check_commit_messages.py, commitlint,
scripts/check_large_files.py, scripts/check_source_language.py -> exit 0
```

End to end, on an isolated `raven web` (its own `RAVEN_HOME`,
`--foreground`, serving this branch's `ui-web` build) driven by headless
Chromium, with made-up keys only:

- a config holding Gemini's bare host at migration stamp 11 boots with
the address gone, the notice logged, the other sections untouched and
the stamp at 12;
- "Check connection" on Gemini sends `x-goog-api-key`, and Google's 400
`API_KEY_INVALID` for the made-up key shows as "The provider rejects the
saved key", now because of the key rather than the header;
- Connect on Anthropic, OpenAI and DeepSeek in the dialog, and on OpenAI
in the wizard's add form, sends `model.save_key` with `slug` and
`api_key` only, and no section stores an address;
- with no stored address the probe reaches OpenAI's and DeepSeek's own
catalogues, and each vendor answers the made-up key with its 401, where
OpenAI's probe used to send nothing;
- the address field of a local deployment (Ollama), drawn above the key,
is drawn once and sends the address typed into it;
- a chat turn on the migrated config reaches Google's route and is
refused as `API key not valid` instead of returning 404.

The wizard's add-form run and the chat turn are from before the review
commits, which touch neither the add form nor the chat route; everything
else above was run again on the final build.

The docs box is left unchecked: no user-facing document describes the
address field or which header the probe sends.

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

## Risk

- Config migration 12 rewrites `config.json` once: a provider's flat
`apiBase` / `api_base` that equals the address the dialog shows for a
vendor stating no default (OpenAI, Anthropic, Gemini, DeepSeek, Z.ai,
Groq) is removed, with a notice. Such a section then behaves like one
that never stored an address. For OpenAI, Z.ai and Groq a chat request
goes to the same URL as before; Anthropic's native client uses the same
host; Gemini's chat starts working; DeepSeek's chat moves from the root
to `/beta`, LiteLLM's default and the path every section without a
stored address already uses.
- Writing that exact address through any write path now stores no
address, and clears whatever address the section held.
- The probe now sends a request for an OpenAI or DeepSeek section with
no address, to that vendor's own catalogue, where before it sent nothing
(OpenAI) or asked `/beta` (DeepSeek); the model picker gets a live list
for those sections. A section holding Anthropic's, Google's, OpenAI's or
DeepSeek's own address (the bare host, the root its catalogue hangs
from, or DeepSeek's `/beta`) is probed at that vendor's catalogue with
that vendor's header; any other address is asked where it points, as on
main. Keys go nowhere new: the host is the vendor's either way.
- Gemini's default moves for installs whose Gemini section lists no
models. A configured `gemini/gemini-2.5-flash` still routes to Gemini
and is still accepted (measured on both trees).
- Rollback: revert the squash commit. The migration does not restore
what it removed; each removed value is the vendor's own address, so
typing it back restores the old behaviour exactly, including the old
failure on Gemini.

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

## Related Issues

Fixes #820

The same write on DeepSeek: #763

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-08 16:57:30 +08:00
Dizhan Xue
d049515230
fix(ui-web): show a previewed image at its own size and scroll it both ways (#854)
## Summary

A previewed image taller than the window ran off the bottom of the
screen with no way to reach the rest of it. The preview overlay is a
fixed grid with auto tracks that capped the image at `max-width` /
`max-height: 100%`, and the auto row grew to the image's own height, so
the height cap resolved against the image itself. Measured in Chromium
at 1440x900: a 1200x4000 image drew at full size down to y=4032, and an
ordinary 4000x3000 photo drew at 1376x1032 with its bottom 164 px off
screen. A fixed overlay has nothing to scroll, so that part was
unreachable.

The preview now shows an image at its own size, and when the image is
bigger than the window the overlay scrolls both ways. An image smaller
than the window stays centred and is not scaled up. A click anywhere and
Escape still close it.

Key decisions:

- The grid tracks stay `auto` on purpose. A big image grows its own
track, so it is the grid that overflows, toward the end where a scroller
can reach it. A cell fixed to the window (`minmax(0, 1fr)`) would make
the image overflow around its centre, and the part above and to the left
would sit at negative scroll offsets that no scroll position shows. The
rule's comment says so, and a test fails if fixed tracks or a percentage
cap come back.
- The scroll bars are the app's own overlay thumbs. Their layer
(`.sbars`, `--z-scrollbars` 88) sits under every overlay, so the
lightbox's thumbs would have been drawn under its own scrim. While a
lightbox is open, `page.css` lifts the layer one step above it and shows
only the thumbs the scrollbar module marks as the lightbox's
(`data-over="lightbox"`). Lifting the layer alone would also lift a
thumb the transcript was showing when the image was clicked, or one from
a reply still streaming in behind the image.

Checked and deliberately not changed:

- Safari / WebKit is unverified. Whether a `<button>` can be a scroll
container has differed between engines; Chromium 151 and Firefox 153
both scroll it (Verification below), and WebKit would not start on the
machine this was tested on, which lacks its system libraries.
- With a mouse wheel and no trackpad, horizontal scrolling is
Shift+wheel, the arrow keys (the overlay has focus when it opens), or
dragging the bottom thumb once a scroll has shown it. An image that
overflows only sideways shows no thumb until it is scrolled. Drag-to-pan
is not added: a click anywhere closes the overlay, so panning would need
a click-versus-drag threshold, which is a behaviour change of its own.
- `PORTALS` in `ui-web/src/state/portals.ts` still lists `.sbars` at
`--z-scrollbars`. The lift is a `page.css` state rule, the same shape as
the onboarding lift of the model picker, which the table does not list
either.

## Type

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

## Verification

Run in `ui-web/` at the head of this branch unless noted.

```
node node_modules/vitest/vitest.mjs run src/state/lightbox.test.ts src/chrome/behaviour/scrollbars.test.ts
  Tests 29 passed (29)

NODE_OPTIONS=--localstorage-file=<file> node node_modules/vitest/vitest.mjs run --no-file-parallelism --reporter=json
  3174 passed, 0 failed, 0 unhandled errors; 214 files (168 under src/, 46 under scripts/gates/)

node node_modules/typescript/bin/tsc --noEmit -p tsconfig.json      exit 0
node scripts/gen-rpc-client.mjs --check                              matches the contract (205 methods)
node node_modules/eslint/bin/eslint.js .                             0 errors; the 4 pre-existing warnings, none in a changed file
node node_modules/eslint/bin/eslint.js <the three changed .ts files>  exit 0
node node_modules/vite/bin/vite.js build && python3 build.py         boot-snapshot OK (342 and 341 nodes match golden)

(repo root)
node ui-web/scripts/check-page.mjs                                   OK
node ui-web/scripts/check-css.mjs                                    OK
node ui-web/scripts/check-class-namespace.mjs                        OK
PYTHONPATH=. python scripts/check_commit_messages.py origin/main..HEAD     exit 0
commitlint --from origin/main --to HEAD --config commitlint.config.cjs     exit 0
PYTHONPATH=. python scripts/check_large_files.py origin/main...HEAD        exit 0
PYTHONPATH=. python scripts/check_source_language.py origin/main...HEAD    exit 0
```

The `--localstorage-file` flag is for node 26 on the test machine, whose
own `localStorage` global shadows happy-dom's without it.

Mutation checks, each applied alone and run against the two test files
above: dropping `overflow: auto` (1 failed), the layer lift (1), the
rule hiding unmarked thumbs (1), the mark in `scrollbars.ts` (2), and
renaming the mark on the producer side only (2). Re-adding the `100%`
caps, or fixed `minmax(0, 1fr)` tracks, fails the size test. The second
commit comes from the last of these: while the stylesheet test built its
thumbs by hand, renaming the mark in `scrollbars.ts` and in its own test
left all 29 green.

Browser checks, Playwright against the built `dist/index.html` in its
offline `?stub=1` mode, with an image staged through the composer's +
popover (Upload files) and its thumbnail clicked; 19 checks, all passing
in both Chromium 151 and Firefox 153 at 1440x900:

- a 4000x3000 image opens at its own size, starting at the 32 px padding
edge;
- the wheel, a horizontal wheel, Shift+wheel and the arrow keys all
scroll it;
- both thumbs show above the overlay, and a hit test at their centre
returns them;
- dragging the vertical thumb scrolls and leaves the image open;
- the far corner is reachable, with the padding included;
- a click on the image, and Escape, close it, and its thumbs leave with
it;
- a 400x300 image stays centred with nothing to scroll;
- a 5000x800 panorama scrolls sideways only and is centred vertically;
- a background scroller's thumb that is showing when the image opens is
hidden while it is open, including when it scrolls again, and is back
once it closes;
- no uncaught script errors were raised.

That script is local and not part of this change: `ui-web` has no
browser test harness, and the vitest tests above assert the mechanism
under happy-dom, which lays nothing out. Before the change, a probe that
loads `page.css` under the overlay's own markup measured 12 of 20
combinations of five images and four window sizes overflowing the window
with nothing to scroll, and the upload flow above reproduced it with the
tall image and the photo.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed (none
describe the preview; searched the READMEs, `docs/` and `docs-site/`)

## Risk

- [x] Security impact considered (a stylesheet change and one data
attribute on a scrollbar thumb; nothing reaches the network or storage)
- [x] Backward compatibility considered (user-visible: an image larger
than the window now opens at full size and scrolls, where it was scaled
to the window's width and cut off at the bottom when tall; a high-DPI
screenshot therefore opens at its pixel size, for example 2880 px wide
from a 1440-point display)
- [x] Rollback path is clear for risky changes (revert the squash
commit; no state, config or stored data is involved)

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-10-03 23:03:05 +08:00
Dizhan Xue
435efa8cb3
fix(ui-web): hide changes with no diff body from the diff list (#847)
## Summary

The floating desk's `diff` tab listed every file a turn changed,
including
ones with no diff to show. Only a file tool hands over a patch; a
command
reports the files its directory listing found, which is a path, a size
and a
line count. For a picture, a deck or an archive that is the whole
account of
the file, so opening its row gave an empty pane. Task file chips had the
same
hole from the other direction: their hunks are rebuilt from the node's
own
tool calls, and a picture's calls carry no text to rebuild from.

Three changes, one predicate behind them:

- `hasDiffBody` in the workspace store answers by extension, composed
from the
three extension tables the viewer already keeps (`IMG_EXT`,
`OFFICE_EXT`,
`BIN_EXT`) plus `pdf`, so a format added to one of them is known here
too.
An extension the tables do not claim is treated as text: an extra row
costs
  less than a hidden change.
- `diffEntries` in the desk store is now the single list both the tab's
badge
and the tab's rows read. It was two expressions before --
`idsOf('diff')` for
the count, `DiffNav` for the drawing -- which is exactly the shape that
lets
  a badge count rows nobody can see.
- A task's file chip routes an edit of a non-text file to the file
itself, the
door a written file's chip already used, and draws no chip at all for a
deletion of one: it has neither a patch to build nor a file left to
open.

The diff tab's paths are now carried split (`dir` greyed, `name` bold)
per
entry rather than concatenated, because a task row has no split to offer
and
has always drawn its path plain -- `.desk-name b` is `font-weight: 500`
for
every desk row, so wrapping a whole path in one would restyle text that
was
never bold.

## Type

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

## Verification

- `node node_modules/vitest/vitest.mjs run` (all of `ui-web`): 214 test
files,
  3178 tests, all passing.
- `node node_modules/vitest/vitest.mjs run --no-file-parallelism
scripts/gates`:
46 files, 205 tests, all passing -- the second test root, which a run
scoped
  to `src` does not reach.
- `npx tsc --noEmit -p tsconfig.json`: clean apart from a pre-existing
  `@dagrejs/dagre` resolution error, which this checkout reports on the
  unmodified base too.
- `npx eslint src/features/tasks/ src/features/desk/
src/features/workspace/`:
  no issues.
- Revert check: with `hasDiffBody` forced to `true`, all five new tests
in the
desk and workspace suites fail; with the chip fix reverted, both new
chip
  tests fail. Both fixes were restored and the suites re-run green.

- [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 non-text change no longer appears in the desk's diff
tab,
and a task chip no longer appears for a non-text deletion. The count on
the
  desk's diff tab and the launcher follow the same list, so they cannot
  disagree with what is drawn.
- A deleted non-text file is no longer named in a task's chip strip. The
row's
  own "N files changed" count and the node's step list still record it.
- Security impact considered: no new input reaches the page, and the
filter is
  a pure function of a path.
- Backward compatibility: the workspace record is untouched, so file
paths in
answers stay clickable; the deliverables shelf still lists every
delivered
  file. Only the diff tab and the chip strip change.
- Rollback path: revert the single commit. Nothing is persisted in the
new
  shape; `diffEntries` is derived on read.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-03 22:08:53 +08:00
arelchan
9dd5adf365
fix(*): show exec diffs on the page and fix three confirmation details (#849)
## Summary

Four follow-ups from a sandbox acceptance run of main on the web page,
driven through `raven web` (the gateway) the way users open it.

- **exec diffs on the page.** A file an `exec` command wrote opened as
the file, not as a diff, when its row in the desk's diff tab was
pressed. The gateway built its loop with `interactive=False`, and that
flag only gates the per-turn checkpoint, so no gateway turn (page, chat
apps, cron) had a shadow repo. `exec` measures a command's writes
against that repo (#829); without one a created file goes out with
counts only and a rewrite as a bare row, and the desk opens a row with
no hunk as the file. Both gateway `TurnPolicy` sites (first generation
and reload) are now `interactive=True`, which is what the
`CheckpointConfig` docstring already says the gateway is. Links in the
reply text still open the file; only the diff tab's rows open the diff.
- **The card for connecting an agent.** An `add` was laid out as a
change to the `subagents` setting: the whole table as the old value, the
call's JSON as the new one, and no security note when it lent a key.
`change_view` now gives an add its own `agents` list (name, preset,
model, lend_key) plus the `subagents.*.lendKeys` note when a key is
lent; the tool adds each preset's display name (`Pi`, not `pi`). The
page draws one line per agent ("Connect Pi, started with Raven's
openrouter key") and the note. The prompt line also stops saying a lent
first run spends the agent's own quota, since the lent key pays for it.
- **The credential card's keys.** It was written before the approval
sheets moved to key caps (#817) and kept numbered rows answered by 1 and
2. It now uses the sheets' foot: Esc skips, the send chord saves, skip
first and save last, no digits. The foot is one shared `SheetActs` in
`AskApproveSheet.tsx`, which keeps the import-direction gate clean.
- **Connectors subtitle.** #830 replaced the agents page title with the
module tabs and dropped its one-line description. `HubHead` now shows a
line for the module on screen: the original agents line, and a matching
new one for channels (en and zh).

## Type

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

## Verification

- `uv run --frozen --all-extras pytest -q -n 8` with coverage: 27446
passed, 27 failed. 22 of the failures fail the same way on clean main on
this machine (research tool vendors, libreoffice, simulation timing).
The other 4 were `test_cli_agent_loop_parity`, fixed by keeping both
gateway `TurnPolicy` calls inline; it now passes with
`tests/test_cli_gateway_commands.py` (95 passed).
- `scripts/coverage_gate.py diff --base-ref github/main --threshold 90`:
91.67%. The two uncovered lines are the two `interactive=True`
arguments, which a source test pins. `ratchet` and `baseline-check`
pass.
- Mutation checks, each reverted fix making a test fail: either gateway
site back to `False`; the add card's `agents`, its lend note, the
lent-run prompt line and the display name; the page's add row and its
words; the credential card's chord save, its key caps, and digit answers
restored.
- `npm test` in `ui-web`: 214 files, 3175 tests passed. `npm run lint`
(0 errors, the 4 existing warnings), `npm run type-check`, `npm run
gen:check`, `check-class-namespace`, `check-css`, `npm run lint:i18n
--prefix ui-tui`.
- `ruff check`, `ruff format --check`, `lint-imports` (10 kept),
`check_source_language.py github/main..HEAD`, commitlint.
- Boot snapshots regenerated: each gains the `p.hub-head-sub` line and
nothing else (the live one against a closed port).
- Manual, in a sandbox `RAVEN_HOME` through `raven web --foreground`: an
`exec` that created `fresh.txt` and appended to `notes.md` listed both
with counts, and each diff-tab row opened the diff while the reply's
link opened the file; the Tavily key card showed Esc / Cmd+Enter caps
and saved on Cmd+Enter; "connect Pi with Raven's openrouter key" showed
the one-line card with the lend note; both hub tabs showed their line.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed: no docs
cover these surfaces, and the repo keeps no image assets.

## Risk

User-visible changes:

- Gateway sessions now get the per-turn shadow-git checkpoint the CLI
and `raven serve` already had: a commit of the working directory at the
end of each turn (skipped for a home directory and its ancestors, and
off with `runtime.checkpoint.policy = "never"`), and a recovery note
after an interrupted turn.
- The connect-agent confirmation and the credential card look different;
the credential card no longer answers 1 or 2.

Rollback is reverting the squash commit. Setting
`runtime.checkpoint.policy` to `never` turns the gateway checkpoint off
without a revert.

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

## Related Issues

N/A

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-03 22:07:15 +08:00
arelchan
9c1cdaed97
feat: let raven read and change its own configuration (#833)
## Summary

Raven can now read and change its own configuration through one tool,
`raven_config`, instead of telling the user to open Settings or editing
`config.json` with file tools. The same path lets it connect preset
sub-agents and diagnose the ones that do not answer, and asks the user
only for what needs them (a key, a sign-in, a paid model).

**The tool and its catalog**
- `raven_config` actions: `describe` (every setting with its value, or a
search), `get`, `set` (one path, or several under one confirmation),
`unset`, `add` (connect presets, several at once), `test`, `restart`
(reload or restart once pending changes are gathered). `session.model`
switches only the current conversation.
- `raven/config/self_surface.py` is the catalog: 14 sections, about 93
settings, each with its value kind, its writer, and when a change takes
effect (next turn, at once, reload, restart, memory server, or inert).
Writes go through the RPC methods the settings page already uses
(`SELF_CONFIG_METHODS` allowlist), so the page and the agent share one
validation path. `tests/test_config_self_surface.py` holds every entry
against the schema and every next-turn claim against a real reader.
- A refused sub-agent comes back with one next step per refusal kind (9
Raven fixes itself, 5 the user does), with stop rules: no hunting for
keys, no credential stores, no restarting another app's services, stop
after three commands that explain nothing.
- `subagents.add` stays preset-only: every execution field comes from
the preset. Presets can be named by display name, an add can pin a model
the agent lists, and a model pick on an unmeasured agent reads the
handshake menu first.
- The companion skill `raven-self-config` describes the whole flow; its
description is injected every turn, the body is read on demand.

**Approval**
- Reads run unasked. Every write asks by default, on a dedicated config
card (what changes, before and after, when it takes effect, a sensitive
note). A grant for the session never carries a change.
- In a turn someone is at, full access, the user's allow rule, and smart
mode's reviewer let a change through; the reviewer never approves a
sensitive setting. Sensitivity is declared by the owner: catalog entries
(approval mode and review model, workspace confinement, sandbox, deny
patterns, disabled tools, MCP servers switched on, skill blocklist and
auto-install, provider endpoints, web and media proxies, remote
machines, workspace path, lent keys, sub-agent descriptions) and each
channel adapter's spec (who may instruct Raven, whether a channel is on,
where its credentials and traffic go, encryption). The gate and the tool
read a call the same way: one value decoder, one path spelling, one
channel field lookup, an object value judged field by field; a path the
tool does not write is refused at the gate, and a call naming one
setting twice is refused. A value is secret when the schema, the channel
spec or the catalog says so, a credential-named env entry, any header,
or a credential inside a URL. The reviewer's instruction counts the
agent's own non-security settings as ordinary work. Unattended turns
(cron and other scheduled runs, no one to answer) are refused; a channel
user who can answer an approval is attended.

**Secrets**
- A key never travels through a tool call. The agent names the secret
with an empty value and a credential card of its own
(`credential.request` / `submit` / `skip` / `pending` / `closed`) takes
it; the host writes it through the handler that owns it and the model
learns only saved or skipped. Channel secrets use the same card. A call
that only asks for keys goes straight to the card. Enabled on page
surfaces only.
- Tool output is scrubbed of the values Raven holds
(`config/held_secrets.py`, including JSON-escaped spellings and URL
credentials) and dotfile reads under home are redacted, once, inside
`ToolRegistry.execute`, so the trace span, the page's diffs, the
sentinel and both agent loops get the scrubbed copy. What a sub-agent
says is scrubbed where it is kept: transcripts, call labels, closing
text, the output a later DAG node renders, error records, announces, the
ACP frame journal, probe details. A key pasted into the chat is refused.
- Lent keys: an ACP sub-agent row can name Raven providers (`lendKeys`)
whose key it is started with. The row stores the provider name; each
start (the spawn path and the capability probe) reads the key into the
variable the preset reads (`presets.LENDABLE_KEYS`, Pi only for now), so
it never reaches the model and follows a rotated key. Verified live: Pi
refused without it, answered with Raven's OpenRouter key, and its row
reads connected and tested with a 398-model menu.

**Page**
- Config card and credential card; the model and permission chips
refresh after the agent changes them; the transcript names
`raven_config` calls by what they did.
- Agents page: the note on a refused connect, a failed test, or a check
that found a problem offers "Hand it to Raven" on its title line; it
opens a new conversation with a prompt naming the agent and the reason,
not sent. A connected row whose check found a problem now shows one head
line and an amber note in the body (shaped like a failure's) instead of
the check's English sentence folded under the head.

**Other**
- Memory LLM left unset follows the main model (EverOS restarts when the
main model moves).
- Reload and restart wait for page turns in flight too.
- `plugin` points agents and chat apps at `raven_config`; `cron` names
the missing `message`; a GNU `timeout` shim on hosts without one,
accepting only the durations the permission gate parses (one shared
definition); read-only package-manager subcommands allow.
- Contracts: `CONTRACTS_VERSION` 35 (this branch's credential types plus
main's `FileWrite`) with the surface repinned; paper-tier line ceiling
3,700 (measured 3,682) with its review note. `CONTEXT.md` defines the
self-configuration surface and lent key.

## Type

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

## Verification

- `uv run pytest -q -n auto`: 27187 passed, 3 failed. The 3 fail on this
machine regardless of this branch:
`test_rpc_files::test_a_host_without_libreoffice_says_so` (LibreOffice
is installed here),
`test_simulation_scenario::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
and
`test_simulation_suite::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`.
`schemas/subagent.schema.json` is regenerated for `lendKeys`;
`test_import_cycle_budget` holds (the capability probe takes the launch
env from its caller rather than importing the agent layer).
- `make lint-ui` (gen:check, eslint, tsc): pass; the 4 eslint warnings
are in files this branch does not touch.
- `npx vitest run` in `ui-web`: 3116 passed; `check-css`,
`check-class-namespace`, `check-page` OK.
- `npm run lint:i18n`, `lint:rpc`, `type-check` in `ui-tui`: pass.
- `uv run ruff check` and `ruff format --check` on every changed Python
file, and `lint-imports` (10 contracts kept): pass.
- In a browser against a local gateway: credential card save, skip,
replace and reload replay; the value appears in no session, trace or
log. Agents page link opens a new task with the prompt filled and
unsent; sent, the agent reads the self-config skill and calls
`raven_config` first, and for Pi offers Raven's key before a sign-in.
- Smart-mode reviewer, run against the real model: 7 ordinary config
changes allowed; `sed` or `write_file` on Raven's config, reading an SSH
key, and `curl | sh` escalated.

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

## Risk

- Behaviour changes: the agent can now change settings and connect
sub-agents after the user confirms (or unasked under full access, and
under smart mode for non-sensitive settings). Lending gives a sub-agent
Raven's key for a provider after an explicit, sensitive confirmation;
what it spends is billed to that key.
- Memory: a memory LLM left unset now follows the main model, so
long-term memory starts working after the upgrade for anyone who never
pinned one, extracting on the main model and billed to the main
provider's key, and EverOS restarts when the main model changes. To keep
it off, set `memory.backend` to null; to keep it on a different model,
pin one of its own.
- Backward compatible: new config fields are optional, and both probe
fingerprints include `lendKeys` only when set, so recorded verdicts and
menus survive. A `config.json` written with `lendKeys` will not load on
an older build (`extra=forbid`).
- Rollback: revert this PR; nothing is migrated. To switch the feature
off without a revert, add `raven_config` to `tools.disabledTools`.

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

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-10-03 12:14:04 +08:00
arelchan
342c52b76a
feat(ui-web): move channels out of settings and beside agents under one rail row (#830)
## Summary

Channels were a section of the settings dialog, so a reader who never
opened settings never learned that Raven can be reached from a chat app.
This moves them out of settings and puts them beside the agent hub,
under one rail row.

- **One place, two modules.** The rail row "Agent Connector" becomes
"Connectors" in English (its Chinese label changes to match). Its page
has two underlined tabs at the top, Agents / Channels, with no page
title or counts above them (`components/HubHead.tsx`). Both are still
their own module pages and islands; they share the rail button, the
header, and `state/hub.ts`, which remembers the module the reader was
last on so the rail row goes back to it.
- **The channel page is drawn like the agent hub.** Filter tabs (All /
Connected / Not connected) over a grid of fixed-height cards, and the
picked channel in the shared detail drawer. The list's switches and
search are gone: pressing a card only opens it, and connecting happens
in the sheet.
- **Three states on a card, not five.** Connected (green); connection
problem (switched on, host up, adapter not running: red, sorted first,
with a line saying what to do); not connected (everything else,
including an adapter waiting on a scan). No host at all is one notice
over the grid, not a reason on every card. The gateway's refusal from a
write is kept on the row and shown in the sheet instead of a toast.
- **The sheet matches the agent sheet measure for measure** (head,
labels, inputs, white foot with a hairline). It also says where
credentials come from in one guide box with the console link, says
"leave blank to keep" once instead of in every box, counts what is
missing only in its head, moves Disconnect to the far end of the foot,
and lays a scan channel out as the code's frame beside its three steps.
- Copy keys this leaves unused are removed from `i18n/messages.json`,
and `ui-tui`'s generated copy is regenerated. Two keys that were already
unused on main (`gui.conn.gw_live`, `gui.conn.close`) are left alone.

Front end only: no backend, config or RPC change.

Known gap, not addressed here: a WeChat / WhatsApp pairing that expired
reads as "not connected" rather than "connection problem", because
`channels.status` cannot tell an expired pairing from one that never
happened.

## Type

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

## Verification

In `ui-web/`:

- `npx vitest run --maxWorkers=4`: 212 files, 3118 tests passed. A plain
`npx vitest run` passed too, apart from timing-sensitive session tests
that time out when the machine is heavily loaded; they pass on their
own.
- `npx tsc --noEmit -p tsconfig.json`: clean.
- `npx eslint .`: 0 errors. The 4 `react-hooks/exhaustive-deps` warnings
are pre-existing (one in the untouched QR panel).
- `node scripts/check-class-namespace.mjs` and `node
scripts/check-css.mjs`: OK. Two pins in `check-class-namespace.mjs` are
lowered because this change retires the debt they count (`extAgents`
unprefixed 1 -> 0, `.k` shared 3 -> 2).
- `npm run build`, then `uv run --frozen python ui-web/build.py`: both
boot snapshots match their goldens (regenerated in this PR, and the live
one was regenerated against a closed port).

At the repo root: `make check-large-files` passes, and `npm run gen:i18n
--prefix ui-tui` is reflected in
`ui-tui/src/i18n/messages.generated.ts`.

Manual: clicked through in a browser against an isolated `raven serve`
(scratch `RAVEN_HOME`) and against the offline `?stub=1` page, in both
languages and both themes. The flow: rail row, module tabs, return to
last module, each card state, the credential and scan sheets.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed: no docs
cover this page, and screenshots are not attached because the repo does
not keep image assets.

## Risk

User-visible changes:

- Channels are no longer in the settings dialog.
- The rail row is renamed from "Agent Connector" to "Connectors".
- Channel rows no longer carry an on/off switch; switching off is
Disconnect in the sheet.
- The toasts for "adapter refused" and "gateway not receiving" are
replaced by the sheet's state line and the page notice.

Rollback is reverting the squash commit; nothing outside the front end
and its copy changes.

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

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-30 20:59:35 +08:00
arelchan
22f161c98b
fix(*): let exec measure the files its command wrote (#829)
## Summary

A file an `exec` command wrote reached the desk diff as a bare row. The
loop listed the working directory on either side of the command (#692),
so it knew a file had changed but never what it changed from: a rewrite
showed a bare `M` with no counts, and opening any such row fell back to
the file viewer instead of the diff pane. File-tool edits were
unaffected; this only concerned commands (`python3 gen.py > out.json`,
`echo x >> notes.md`, `sed -i ...`).

This supersedes #826. That PR measured the change in the loop, around a
call named `exec`. Here the exec tool measures it itself, around the
command it runs, and hands it back the way it already hands back the
files a command removed; the loop only forwards it.

How it works:

- **The tool measures.** `raven/agent/tools/command_writes.py` lists the
directory before and after the command and, where the checkpoint's
shadow repo covers it, stages the tree first, so a rewritten or removed
file is shown against what it held. The result travels on a new
`ToolResult.written` / `ToolOutput.written` (`FileWrite` on the tool
paper, contract version 32 -> 33, and 33 -> 34 for
`FileRemoval.withheld`), beside the existing `removed`.
- **The repo is handed in.** Tools do not import the loop shell
(import-linter), so `ExecTool` holds the shadow repo through a
`ShadowTree` protocol and a resolver the loop passes in
(`AgentLoop._command_shadow`: the turn's repo, only where it covers the
command's directory). The built-in is built with it, and a plugin's
same-name `exec` replacement (raven-code's `CodeExecTool`) is handed it
through `measure_writes` before it is registered, so it measures as the
built-in does, as the loop-level listing it replaces did for any tool
named `exec`. Both happen before the registry admits the tool, because
the registry reads the ceiling off the spec it admits.
- **Every command stages afresh inside its own call**, into a
per-process index of its own in the shadow repo (never the index the
per-turn commit reads), and waits up to 120 s. Whenever there is no
snapshot to measure against -- the tree cannot be staged at all
(checkpoint off, `working_dir` outside the repo, git error) or it did
not finish within the wait -- the command runs all the same and is still
listed, so its files are reported without the text they held; where a
repo covers the directory, its rules still decide what text may be
shown. A late staging is left running, so a later command usually finds
it done. What follows the command is bounded too: the shadow repo's
reads get 60 s (past it every file goes out without text) and the whole
post-command step 120 s (past it the call returns the command's output
with no record of its files), so a slow measurement never costs the
output. `measure_writes` raises the tool's registry ceiling by what
measuring may take (the 120 s wait and the 120 s bound), so the
built-in's goes from 660 s to 900 s and a replacement's own ceiling
keeps its margin. A git read whose caller stops waiting kills its
process.
- **Warm-up as a session opens.** The first staging of a directory
hashes every file. `session.create` / `session.resume` call
`ExecTool.warm` for the directory the session resolves to, and a session
opened by its first message (a channel's) is warmed at the start of that
turn. `warm` returns at once and runs on the staging thread, so it
overlaps the model's first reply.
- **One rule for what text may be shown.** Every file a command created,
rewrote or removed, including the ones its own removal watch caught by
name, carries text only where the shadow repo's rules would store it
(`git check-ignore --no-index` against its excludes and the user's
`.gitignore`, the rules alone, not what the index holds). So a `.env` or
a key never enters the event or the stored session, even one the repo
staged before an ignore rule named it, and even when the staging failed:
the rules need no tree. Where no shadow repo can vouch for a file, a
created file carries its counts only.
- **Loop.** The exec-only listing branch in `turn_path.py` is gone; the
loop turns `result.written` into `file_written`. Besides that it has the
resolver above and the one-line warm-up at turn start. The registry now
keeps `removed` / `written` on a result it rewrites as an error (a
command whose output begins with "Error" still wrote what it wrote). A
removal whose body the rules kept back goes out marked `withheld` (a new
defaulted field on `FileRemoval`), and the turn's removal watch fills in
a bare removal from what the turn wrote only when it is not: with the
checkpoint off every bare removal stays fillable, as before, and a
withheld body is never put back.
- **Wire and page** (unchanged from #826). `file_written` entries gain
optional `added` / `removed` / `diff`; the diffs share a 512 KiB budget
per call, past which the counts still go. Contract updated in
`rpc-schema/openrpc.json`, `raven/rpc/models.py` and both generated
clients. ui-web draws these rows with their hunks, so they open in the
diff pane with +/- in the desk list, and `fromUnified` now skips only a
real `---`/`+++` header pair, so a removed `-- note` line is no longer
dropped.
- **Robustness.** Stagings run on daemon threads with blocking git calls
(an asyncio subprocess still starting when its loop closes hangs the
close on CPython 3.12 macOS). `add` and `write-tree` run under one lock
per index; the staging `add` has its own 600 s ceiling; the turn commit
waits for a warm-up's repo setup instead of racing it on the config
lock. The setup's future and every staging future are running from
creation, so a cancelled waiter cannot cancel them, and the warm-up and
staging threads settle them whatever happens, so no staging is left
published for nobody to finish (the cancellation 0xKT and gloryfromca
measured on #826). Git queries now encode paths with `surrogateescape`,
so a POSIX file name that is not UTF-8 no longer raises after the
command has run (the follow-up gloryfromca raised on #826).

Behaviour that moved with the measurement: staging now happens after the
permission gate has ruled, so a denied command is never staged; a
background command (`run_in_background`) takes no listing, since its
files land after the call returns; a sub-agent's `exec` does not list
(its runner lists every call itself, as before).

Not covered: files the shadow repo excludes (`*.log`, `.env`, the user's
`.gitignore`) get no diff, text files over 256 KB get no counts, a
same-name `exec` that is not an `ExecTool` (none ships) reports no
files, and existing sessions keep the rows they stored.

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

- `make test-python` -- 27077 passed, 108 skipped, 3 failed (on the
previous head; the focused set below is on this one). The 3 failures
(`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
`test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`,
`test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`)
fail the same way on `github/main` on this machine.
- `uv run --frozen --all-extras pytest tests/test_runtime_checkpoint.py
tests/test_runtime_checkpoint_deep.py
tests/test_agent_loop_session_stamps.py tests/test_agent_loop_workdir.py
tests/test_rpc_session.py tests/test_shell_command_writes.py
tests/test_shell_file_removals.py tests/test_tool_registry_execute.py
tests/test_tool_registry_channels.py
tests/test_tool_registry_session_overlay.py tests/test_rpc_spine.py
tests/test_workdir_snapshot.py tests/test_shell_approval.py
tests/test_contracts_two_tier_ledger.py tests/test_kernel_budget.py
tests/test_removal_watch.py tests/test_agents_code_flow_exec.py
tests/test_agents_code_tools_plugin.py
tests/test_agents_code_launcher.py tests/test_subagent_dag_runner.py
tests/test_agents_research_ask_user_text.py tests/test_living_docs.py
tests/test_tracing_compact.py -q --idle-ceiling-strict` -- 1231 passed.
- `make lint-python lint-types lint-imports` -- clean (10 import
contracts kept). `npm run gen:check --prefix ui-web`, `npm run
type-check --prefix ui-web`, `npm run lint --prefix ui-web` (0 errors, 4
pre-existing warnings), `npm run lint:rpc --prefix ui-tui` -- clean.
`npm test --prefix ui-web` -- 3107 passed.
- Mutation checks, each restored afterwards and each turning at least
one test red (48): a staging timeout not falling back to running the
command without a diff; the wiring not asking the tool to record writes,
or not handing it the repo; the resolver dropping its `covers` check, or
ignoring the turn's binding; the registry dropping `written` on unwrap
or on an error result; the loop ignoring `written`; no turn-start
warm-up; `session.create` / `session.resume` not warming; a failing
warm-up failing the open; created-file text ignoring `trackable`; the
diff budget ignored; removals losing the staged text; staging a
directory too large to list; reading the written files on the event
loop; a named removal reported twice; the ceiling under the sum of the
wait, the command cap and the measuring bound; no bound on the shadow
repo's reads after the command, or on the whole post-command step; a
late read keeping a named removal's text; a cancelled git read left
running; the checkpoint's timeout not being a `TimeoutError`; `warm`
ignoring `record_writes`; a background command measured; the setup
future not marked running; the warm-up or a command's staging not
settling its future on an unexpected error; a rewritten or removed file
read without the rule; a named removal's text kept without the rule; the
repo dropped when the staging failed, or its rules applied only where
there is a tree; a tree-less staging still read for blobs; the removal
watch refilling a withheld body, or never refilling an unknown one; a
named, listed or timed-out removal not marked withheld where the repo
kept its body back, or a listed one marked where no repo ruled;
measuring switched on only for the built-in, so a plugin's same-name
`exec` reports nothing; `measure_writes` not raising the ceiling, or
raising it on every call; the built-in or the replacement measured only
after the registry admitted it, so the admitted ceiling stays at 660 s;
a failed staging not warned about, or warned about on every command.
- Real gateway (`raven serve` from this branch, isolated `RAVEN_HOME`,
real model), in a cold 12,775-file / 428 MB directory on a machine
running endpoint protection at load average 13-14. The first message
opened the session and the warm-up started with it; the model's first
`exec` (append to a `notes.md` Raven had never touched, and create
`made_by_exec.txt`) waited out the cold staging and took 37.8 s in
total. The second `exec` took 3.7 s, with the staging under the 1 s
sampling interval. The desk lists `M notes.md +2` and `A
made_by_exec.txt +3`; `notes.md` opens in the diff pane with both
commands' hunks, and a reload draws the same rows.

## Risk

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

User-visible changes:
- An `exec` now runs only after the working directory has been staged
(or the 120 s wait has passed). On a warm directory that is well under a
second; the first command in a large directory the shadow repo has never
indexed waits for the first staging (tens of seconds on a slow disk),
which the session-open warm-up usually hides. Past 120 s the command
runs without a diff.
- Opening a session starts one background `git add` per directory per
process, writing into the same `.raven/shadow.git` the checkpoint
already uses. Each process keeps its own `exec-<pid>.index` there; files
older than 7 days are pruned.
- No file content is stored beyond what the checkpoint already commits,
and the same excludes apply. With `runtime.checkpoint.policy = "never"`
a command's rewrite is reported bare, as today, and a created file
carries counts only.
- The new `FileWritten` fields are optional, so older clients ignore
them. `ToolResult` / `ToolOutput` gain a defaulted `written` field and
`FileRemoval` a defaulted `withheld`; contract version 34.

Rollback: revert the commit. The staging indexes in `.raven/shadow.git`
are inert without the code and are pruned by age.

## Related Issues

Supersedes #826

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-30 17:44:00 +08:00
arelchan
2324beceb3
feat(ui): preview files by what renders and answer approvals with cmd+enter (#817)
## Summary

The file viewer picked how to show a file from its extension alone, and
two of those choices did not match what the gateway and the browser can
actually render. This PR lines the classification up with the real
rendering paths and redesigns the note shown for a file that has none.

**Classification, checked against what renders**

- **Office documents.** The gateway converts ten Office formats to PDF
with LibreOffice (`raven/rpc/pdf_preview.py` `RENDERABLE_SUFFIXES`: ppt,
pptx, doc, docx, xls, xlsx, odp, odt, ods, rtf), but the viewer only
routed `pptx` there; docx, xlsx and the rest fell to the "cannot render"
note. They are one `office` kind now (renamed from `pptx`), drawn as
pictures of their pages the way a deck already was. The transcript
delivery tile uses the same kind, so these formats also get a first-page
thumbnail.
- **Unknown names.** Anything the kind table did not know was treated as
binary, so `Makefile`, `.gitignore` or a config file named `x.model`
showed the note. Such a file now has its first 8 KB read with a `Range`
request, and the bytes decide: a NUL byte, or more than 2% undecodable
characters, means binary. Text is shown as text (straight from that one
answer when it covers the whole file); binary gets the note, with the
size taken from `Content-Range`; an empty file (416) is empty text.
Extensions that are never text (archives, media, fonts, model weights,
databases) skip the request. No gateway change: `/file` is an aiohttp
`FileResponse`, which already answers ranges. A test now pins the 206
and 416 answers the viewer relies on.
- **Broken pictures.** An image that failed to load always said the file
was gone. It now says gone (404), too large (413), refused (403), or
could not be drawn, from the route's status.

**The fallback note**

Before: a line of text in the top-left corner, the full path repeated,
and three loose outline buttons ("Open this MODEL in its app", "Open
with...", "Copy path").

After: a card centred in the pane with a file tile carrying the
extension, a title, a `MODEL file - 4.0 KB` line, and one split button
(open in the default app, chevron to choose another). The path and the
copy-path button are dropped from the body because the pane header
already has both. A failed Office render uses the same card, with the
gateway's reason quoted in a monospace box under the title. The rules
moved from `styles/page.css` into `features/workspace/styles.css` under
the `workspace-` prefix; the class-namespace ratchet is lowered to match
(`workspace` 35 -> 33, `.w` 3 -> 2). `browser` goes 25 -> 26 only
because `.h` is no longer shared with the workspace.

**A gone Office file** read as "could not be rendered as a PDF" with the
route's 404 quoted under it. A 404 from the render route now reads as
the file being gone, the way every other kind does, and marks the
delivery missing.

**Second topic, added at the maintainer's request: approval and question
sheet shortcuts.** This is unrelated to the file viewer and is kept in
its own four commits (`feat(ui): answer approvals with esc and cmd+enter
instead of digits`, `fix(ui): shorten the always-allow button and name
its rule on its own line`, `fix(ui): draw the approval sheet as a
tool-approval card`, and `fix(ui): keep the approval answers inside the
card, and draw confirm the same way`), so it can be reverted or
cherry-picked on its own.

- The approval sheet was answered with 1/2/3, with deny as 1: backwards
to anyone used to a terminal agent, where 1 is yes, and unlike the GUI
agents, which answer a tool call with a chord. It now takes Esc to deny
(unchanged), Cmd+Enter to allow once, and Shift+Cmd+Enter for the
broader grant (the suggested rule, or this conversation when there is
none). Ctrl works in place of Cmd. Digits no longer answer; each button
shows its key as a cap instead of a number badge.
- The question sheet keeps its number keys for options and arrows for
steps, and gains Cmd+Enter for Next / Submit, from its own answer field
too. Esc is left to the page, where it stops the turn.
- The broader grant's button said the whole rule ("Always allow: git
push * (every directory)") and was the widest thing on the sheet. It now
says only "Always allow", as GUI agents label it, and the rule it would
save is named on its own line under the evidence, with the pattern set
as code, so the reader still sees what outlives the conversation before
pressing it. No line is drawn when the grant saves no rule.
- The permission sheet is drawn to the approval design: a solid card
(16px radius, a ring and a soft shadow instead of the rack's frosted
glass) capped at 300px, a 15px question, one muted line of why, the
evidence in a bordered box that scrolls on its own, and the answers
pinned to the foot as 30px outlined buttons with allow once filled. Key
caps are outlined, here and on the question sheet's Submit. The corner
cross is gone from this sheet: refusing is Deny and Esc, and a cross
read as "not now" rather than as the refusal it sends. The answers row
is a sibling of the scrolling body, not a child, so a long why sentence
and a long rule on a narrow window scroll the body instead of pushing
the buttons under the card's bottom edge (a CSS gate pins the three
rules this needs, since happy-dom does no layout). The `confirm.request`
sheet wears the same card class and now draws the same card: evidence
box, answers along the foot, deny first and focused, no cross.
- Deny keeps the focus, so a bare Enter still never grants, and a chord
pressed in a field (the composer's own Cmd+Enter) is left to the field.

**Not changed, on purpose:** a standalone PDF is still framed with the
browser's own viewer, which keeps text selection and search. Office
files are drawn as page pictures instead, so the two paths still differ.

## Type

Feature, because the squash commit is released as one entry and the
shortcut change is new behaviour; the file-viewer half is a fix riding
in the same PR (Summary says which commits are which).

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

## Verification

- `npx vitest run` in `ui-web`: 211 files, 3121 tests passed (at the
head of this branch, rebased on the current main). New cases cover the
ten Office extensions, a text head read in one request, a head that is
only the start of the text, a binary head with its range size, a
never-text extension making no request, an empty file, text that turns
binary past its head, and a 413 picture.
- Shortcuts: new cases cover Esc / Cmd+Enter / Shift+Cmd+Enter on both
approval variants, Ctrl in place of Cmd, digits and a bare Enter
answering nothing, chords pressed in a field being ignored, the
conversation grant when no rule is suggested, a question docked above a
pending approval taking the chord, Cmd+Enter from the question's empty
answer field, the rule line (drawn with the pattern as code when a rule
is suggested, absent otherwise), no close cross on either approval
sheet, the answers row sitting outside the scrolling body, and the
confirm sheet's deny-first order and focus. The restyled card was
checked in a real browser in light and dark themes; at 444px wide with a
multi-line why, a long suggested rule and a long evidence block, the
body scrolled (295px of content in 181px) and the answers row stayed
inside the card. Six mutations of the key handling (Shift chord allowing
once, a bare Enter counting, the field guard removed, the question's
chord or its field chord disabled, the stacking check removed) each
failed at least one case. Checked by hand in a real browser:
Shift+Cmd+Enter answered `allow_session`, "1" answered nothing,
Cmd+Enter allowed once, and a two-step question was answered with "2",
"1" and Cmd+Enter.
- Mutation check: six mutations (sniff every name, drop the one-request
reuse, drop the NUL test, drop the 416 case, map 413 pictures to "gone",
classify only pptx as office) each failed at least one of the new tests.
- `npm run type-check`, `npm run lint` (0 errors), `npm run gen:check`,
`node scripts/check-class-namespace.mjs`, `node scripts/check-css.mjs`,
`npm run build && python3 build.py && node scripts/check-page.mjs` (boot
snapshot matches golden): all pass.
- `npm run lint:i18n` in `ui-tui`: generated catalogue up to date.
- `uv run --frozen --all-extras pytest tests/test_rpc_files.py
tests/test_rpc_transport.py -q`: 100 passed, 1 failed. The failure is
`test_a_host_without_libreoffice_says_so`, which expects 503 and gets
500 here: it empties `PATH`, but this machine has LibreOffice in
`/Applications/LibreOffice.app`. This PR touches no code under `raven/`;
CI, without LibreOffice, is the check that counts.
- In a real browser against a running gateway, light and dark theme: an
unknown-extension text file and a `Makefile` open as text, 4 KB of
random bytes shows the note with its size, a `.docx` renders as a page,
an empty `.keep` shows as empty text, and the open-with menu lists the
host apps.

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

No docs describe the viewer's fallback, and screenshots are kept out of
the repository.

## Risk

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

The shortcut change alters muscle memory: a reader who pressed 3 to
allow once now presses Cmd+Enter, and a digit does nothing rather than
answering. The `confirm.request` sheet used to focus allow, so a bare
Enter allowed; it now focuses deny, as the gate card always did, so a
bare Enter refuses. Opening a file of unknown type now costs one extra
ranged GET, capped at 8 KB, on the same authenticated, workspace-fenced
route the viewer already reads. Nothing new is served or executed.
Office formats other than pptx now ask the gateway for a LibreOffice
render; a host without LibreOffice answers 503 and the note shows that
reason, as a failed pptx already did. The kind rename (`pptx` ->
`office`) is page-internal and touches no wire contract. Rollback: the
shortcut change is the four commits named in Summary and reverts on its
own; the file-viewer change is the other three commits. Reverting the
whole PR undoes both.

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-30 16:46:50 +08:00
Dizhan Xue
68c5c14c0d
fix(*): a web sign-in to the codex subscription reaches the pickers and reports usage (#818)
## Summary

Signing in to the OpenAI Codex (ChatGPT subscription) provider from the
web UI got as far as the device code, then broke in four places. Each
was reproduced against a real ChatGPT account before it was fixed.

- **A second "Authorize in browser" click stopped the poll.** The
  gateway refused a start while one was polling, and the settings store
  had already stopped its timer, so a sign-in completed with the code on
  screen was never noticed. `oauth_login.start` now answers a start that
  finds one polling with the same code and the time it has left, rather
  than refusing it or minting a second code the first poller would never
  see. A code that expired while its poll winds down (the driver's poll
  outlives the code by up to one interval) is not handed out again. The
  store stops its old poll only once a start succeeds, and watches the
  code for exactly the time the gateway reports. Its old 30 s floor
  would have kept a code with seconds left on screen, dead, for half a
  minute.
- **The landing never reached the model pickers.** The poll refreshed
  the settings snapshot but not the offer the pickers read, so
  onboarding's Chat slot answered "No model added for OpenAI Codex."
  until a reload. The landing is the one provider write that does not go
  through the store, so it now calls the same `reloadOffer()` the
  store's other reads use.
- **Codex usage was always zero.** `OpenAICodexProvider` never passed a
  usage sink to `_consume_sse` and built its `LLMResponse` without
  `usage`. It now reports usage the way `OpenAIResponsesProvider`
  already does with the same reader. The calls stay unpriced
  (subscription billing), which `TurnSpend` counts in
  `cost_missing_calls` by design.
- **A sign-in from the web UI left the token file at the process umask
  (0644).** `raven provider login` restricts every credential file after
  its handler; the web UI's path did not. `start` now calls the same
  `restrict_to_owner` once the flow ends, and logs rather than raises if
  that fails, since the background task has no caller left by then.

Tests whose meaning changed:

- `test_start_returns_the_pair_and_keeps_polling_until_the_starter_ends`
  no longer expects a `RuntimeError` from a second start; that assertion
  encoded the bug.
- `test_oauth_login_refuses_a_key_provider_and_a_second_start` is
  renamed to end in `_and_a_failed_start`, with a neutral message.
  `start` no longer raises for a second start, but the `RuntimeError`
  mapping the test pins still covers vendor failures.

New coverage worth naming: one test runs LiteLLM's real ChatGPT
authenticator with only the vendor faked, pinning that its
`_login_device_code` still mints the code through the
`_request_device_code` step the starter hooks. Every other test of that
starter fakes the whole driver. Renaming the hook in the starter turns
the new test red. Another pins the `asyncio.shield` that `start` awaits
the pending code through: two starts wait on one code, one is cancelled
the way the WebSocket transport cancels a lost connection's requests,
and the other must still get the code. Deleting the shield turns that
test red, and no other in the two test files that import the module.

Checked and deliberately not changed:

- `chat()` retries with `verify=False` on `CERTIFICATE_VERIFY_FAILED`,
  which would hand the ChatGPT token to anyone presenting a bad
  certificate. It predates this PR, and removing it can break users
  behind TLS-inspecting proxies, so it wants its own decision.
- The token file is restricted after the driver writes it, so there is
  a window at the process umask. `provider login` has the same shape,
  and `get_oauth_dir()` keeps the `oauth/` directory 0700 throughout.
- Three conditions have no test that fails when they alone are
  deleted: the usage sink on that `verify=False` retry, which belongs
  with the retry's own decision; `_still_valid`'s failed-handoff case;
  and `start`'s check that the attempt it would reuse is still running,
  which predates this PR. The last two only matter to a start that
  lands in the same event-loop cycle as the attempt failing or ending.

## Type

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

## Verification

On this branch, rebased onto the current `main`:

- `uv run --frozen --python 3.12 --all-extras pytest -q` over the six
  test files this PR touches or that exercise the changed code
  (`test_providers_oauth_login.py`, `test_rpc_model.py`,
  `test_openai_codex_provider.py`, `test_providers_chatgpt_token.py`,
  `test_cli_provider_commands.py`, `test_providers_codex_catalog.py`):
  365 passed.
- Full suite, `uv run --frozen --python 3.12 --all-extras pytest -q`:
  27012 passed, 7 failed. None of the seven is in a file this PR
  touches, and each has a cause local to this machine: the five proxy
  tests in `test_config_update_providers.py` read the ambient
  `HTTP(S)_PROXY` (155 of 155 pass with those variables unset);
  `test_resolve_node_dir_answers_each_case_it_exists_for` in
  `test_install_script.py` finds an npm elsewhere on `PATH`; and
  `test_what_cannot_be_read_names_nothing` in
  `test_subagent_node_runtime.py` fails as root, the same way on
  `main`. CI's four unit shards on this head: 27015 passed, 0 failed.
- ui-web, `node node_modules/vitest/vitest.mjs run src/features/settings
  src/features/model`: 20 files, 315 passed. Full ui-web suite:
  3088 passed, 13 failed, 0 unhandled errors. Eleven are 5 s
  timeouts, and the other two are assertions in
  `src/state/session/registry.test.ts` and
  `scripts/gates/direct-chat-media-live.test.mjs`. None is in a file
  this PR touches, and the eleven files they sit in re-run on their
  own: 106 passed, 0 failed. CI's `ui rpc contract` job ran the same
  suite on this head: 210 files, 3101 passed.
- `make lint-python`: all checks passed, 2147 files already formatted.
  `make lint-imports` (10 contracts kept), `lint-types`, `lint-deps`
  and `lint-ui` (`gen:check`, `lint` with 0 errors, `type-check`):
  exit 0.
- `check_commit_messages.py`, `check_large_files.py` and
  `check_source_language.py` over `origin/main..HEAD`, and commitlint
  over the same range: exit 0.
- Every new test was run against the unfixed code first and failed for
  the reason it names. The shield test was also run with only the
  shield deleted, over the two test files that import the module, and
  it was the one test to fail.
- The last commit changes only comments and a docstring in
  `oauth_login.py`. On it, ruff and the six test files above were
  re-run: 365 passed. The other local numbers are from the commit
  before it.

Live, against a real ChatGPT account, on an isolated `raven web` built
from this branch before three later changes (the expired-code check,
the logged restrict failure and the store's watch window), which the
unit tests above cover:

- a second click returned the same code with no error, and polling
  continued (4 `model.options` reads in 10 s, against 0 before);
- once the sign-in landed, onboarding's Chat picker listed the account's
  five models without a reload;
- a real chat turn's model call recorded 11108 input and 5 output tokens
  in the audit spans, and Settings > Usage showed 2 calls, 11k input and
  29 output;
- the token file was 0600.

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

No user-facing doc describes this flow's failures, so none needed an
update. `make lint-tui` and `make lint-bridge` were not run locally,
because their dependencies are not installed in this checkout; this PR
touches neither tree, and CI's `TUI checks` (144 files, 2111 tests) and
`bridge checks` passed on this head. CI settled at 20 pass and 2
skipping (`claude`, `docs deploy`).

## Risk

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

User-visible: a second click reopens the vendor's tab with the same
code instead of showing an error, and the page stops watching that
code when it expires; Codex usage now appears in traces and in
Settings > Usage; the credential file is owner-only.
`model.oauth_login` keeps its result shape, and on a repeat call
`expires_in` is the time the code has left. The pending code now goes
to any authenticated caller of the gateway rather than the first one
only; the gateway serves a single user. Rollback: revert the squash
commit, nothing is migrated.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
2026-09-30 16:24:54 +08:00
arelchan
b27126ef39
feat(*): upgrade from the page with progress, open it for bare raven (#806)
## Summary

The upgrade button on the page could never work for a normal install,
and when an upgrade did run, neither the page nor (on a slow link) the
terminal showed anything that moved. This PR makes the page upgrade
work, shows its progress, and fixes what an end-to-end run of it turned
up, plus two entry-point changes from the same pass.

**The page upgrade works on `raven web`.** `raven web` runs `raven
gateway`, so nearly every page is gateway-hosted, and `system.upgrade`
refused all of them (`gateway_hosted`): its relaunch brought back a bare
`raven serve`, which builds no ChannelManager, so the IM channels would
have vanished. Now:

- On every page mount the gateway hands the page its own graceful stop
(the path `gateway.shutdown` takes), its busy check, and its supervisor
pid. Every mount, because a config swap tears the page down and disarms
it.
- On upgrade the gateway exits 0. The `raven web` supervisor already
reads a zero exit as "stand down" (its docstring names
`system.upgrade`), so it exits too.
- The helper waits for the **supervisor**, not the gateway, then
installs and relaunches `raven web --supervise` on the same port with
the same token and cookie. Waiting on the supervisor matters: its
cleanup removes `web.json` after the gateway exits, and a supervisor
started before that would lose its state file, inviting the next `raven
web` to start a second one.
- Refused, each with its own reason, when nothing would bring the
gateway back (started by hand, or `raven web --foreground`), when work
the page cannot see is running (an IM turn, a sub-agent, a pending
question), or when there is no executable to relaunch from. The config
swap and the upgrade now share one busy check.

This takes effect for upgrades that start from a release containing it;
a gateway on an older release still refuses with the old message.

**The page shows the upgrade's progress.** The card said "Upgrading
Raven..." and nothing else until the new Raven answered, because the
process that served the page is gone for the whole install.

- The helper downloads the release itself, where the bytes can be
counted, and hands uv the local files so uv only resolves dependencies.
All or nothing: if any asset cannot be fetched, uv gets the original
URLs and downloads them as before. Files live under
`~/.raven/cache/upgrade/<version>`; earlier versions' are cleared.
- Once the old Raven has exited, the helper answers on the page's port
(recorded in the upgrade marker): `/upgrade/status` with phase, bytes
done and total, and rate; 503 to everything else, so the page's "is it
back?" probe keeps waiting and a reload gets a self-refreshing wait
page. It answers only the page's own Host, and lets the port go before
the relaunch binds it.
- A failure is held until the page has read it (at most five seconds).
Before, a failed install relaunched the old version and the page
reloaded onto it silently.
- The page polls the status, measures the bar while bytes are counted
and slides it otherwise, and says when the new Raven is starting. Its
twenty-minute ceiling now counts silence, not the whole upgrade, so a
slow download that is visibly moving is not given up on.

**Two bugs the end-to-end run exposed**, both fixed here:

- *A red "the service is not running, start it with raven web" bar
during the upgrade.* The transport's health probe counted any answer but
401/403 as "the gateway is back and refused this session", so the
helper's 503 made it give up. A 5xx now means "not back yet". Following
that bar's advice mid-upgrade is exactly what would start a second
supervisor.
- *The old gateway took 46 seconds to exit, blocked on the page's own
open WebSocket.* aiohttp's cleanup waits for live handlers instead of
closing websockets. The WS gateway now closes its sockets from
`on_shutdown`; the same run dropped to 4 ms. This also speeds up `raven
web --stop` with a page open.

**`raven gateway` refuses a half-written install.** `raven serve` has
guarded this since the upgrade marker existed, but the gateway never
did, and the gateway is what `raven web` supervises. A restart inside an
upgrade window came up on the half-written tree and, because the page
route is chosen once, served the placeholder page until restarted by
hand. The guard runs before the instance lock. It is also a precondition
for the restart above.

**Refusals are localized.** The page pasted the server's English
`detail` into an otherwise Chinese card. Refusals it can name come from
the catalogue; refusals whose detail carries facts from this run keep
them. A server-side `busy` gets the same wait notice as the page's own
busy turn, not the "run this in a terminal" card.

**The terminal upgrade names its download size.** uv draws one bar per
package and no total, so a large release reads like a stalled install (a
real report: a 72 MiB upgrade at about 50 KB/s looked frozen). The
helper prints each asset's size and the total before downloading, from
HEAD requests bounded at 5 seconds, headline first so a hanging probe
adds no silence; the terminal then shows the helper's own live progress
line. Output is flushed so it keeps its place in `web.log`.

**Bare `raven` opens the page.** The installer ends in `raven web`, but
the command typed the next day landed in the TUI. Bare `raven` now does
what `raven web` does; where no browser can be opened it runs the TUI
instead, decided before anything starts. `raven web` and `raven tui` are
unaffected.

**Composer placeholders.** Empty: "Describe your task, or have Raven
build an agent for it" becomes "Describe your task". While a turn runs:
"it is sent once this turn ends" was stale (mid-turn sends merge into
the running turn; the queue is only a fallback), so it now says Raven
receives the new instruction directly.

## Type

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

## Verification

End to end, three times, in a sandboxed uv tool install (own
`UV_TOOL_DIR` and `RAVEN_HOME`, no plugins, so nothing reached a real
memory server), upgrading 0.2.90 to 0.2.91 from a local stand-in for the
GitHub release API, clicking the real rail-foot upgrade row in a
browser:

- First run (fast local download): page back after 17 seconds, reloaded
by itself, still signed in; served by `python -P -m raven gateway` (not
`serve`) on the same port; `web.json` names the new supervisor, which is
the new gateway's parent; old supervisor and gateway gone.
- Second run, with the release trickled at ~200 KB/s: the progress
showed, and the run found the two bugs above (the red bar, and the old
gateway taking 46 seconds to exit).
- Third run, same trickle, after the fixes: the card read "Downloading
the new version: 0.6 / 6.1 MiB, 191 KB/s" five seconds after the click,
then 2.4 / 6.1 MiB with the bar measuring; no red bar; the old gateway's
page socket closed 4 ms after the control plane stopped; uv prepared the
package from the local file in 157 ms; the page reloaded itself onto
0.2.91.
- `raven upgrade` in a real pseudo-terminal against the same trickle:
the live line redrew in place 98 times from 0.1 to 6.1 of 6.1 MiB, then
uv installed from the local file.

Commands, all on this branch rebased onto current main:

- `make coverage` - 26,955 passed. 21 failed, and they are the same 21
that fail on unmodified main on this machine (research-tool and
simulation tests, and one that assumes LibreOffice is absent); a 22nd
was a load-sensitive test added here, fixed in this PR and then 25 of 25
under CPU load
- `scripts/coverage_gate.py diff --base-ref github/main --threshold 90`
- 100% (77 of 77 changed lines)
- `npm test --prefix ui-web` - 3096 tests pass
- `make lint-python` - pass; `uv run lint-imports` - 10 contracts kept,
0 broken
- `make lint-ui` - 0 errors (4 pre-existing `exhaustive-deps` warnings
in files this PR does not touch); `npm run lint:i18n --prefix ui-tui` -
up to date
- `node ui-web/scripts/check-page.mjs`, `check-css.mjs`,
`check-class-namespace.mjs` after `npm run build` and `build.py` - OK
- `mkdocs build --strict` - pass
- `npx commitlint --from github/main --to HEAD`,
`scripts/check_commit_messages.py`, `make check-source-language` and
`make check-large-files` with `COMMIT_RANGE=github/main..HEAD` - pass

New tests were mutation-checked; each edit below turns the test written
for it red. Server: relaunching `serve` instead of the supervisor,
waiting on the gateway instead of the supervisor, dropping the
unsupervised refusal, the busy refusal, the no-relaunch guard, or the
page-mount hand-over; not closing sockets on shutdown. Helper: never
downloading, not closing the status server before the relaunch, dropping
the Host check, not holding a failure, dropping the manifest or its
flush. Page: counting the ceiling from the start instead of from
silence, ignoring a held failure, dropping the "starting" line, a bar
that ignores or overshoots the fraction, the old 5xx probe rule, server
sentence instead of catalogue, `busy` routed to the failure card. Entry
point: never opening the page, opening it on the wrong port.

Note for reviewers running the gates locally: `make check-commits`
hardcodes `--from origin/main`, and `check-source-language` /
`check-large-files` default `COMMIT_RANGE` to `origin/main..HEAD`. Where
`origin` is not GitHub those ranges fail on unrelated commits; pass the
GitHub base explicitly.

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

The quick-start's update section (English and Chinese) now covers
updating from the page.

## Risk

User-visible changes:

- Bare `raven` opens the browser page instead of the TUI, leaving the
resident gateway `raven web` always leaves. Headless machines keep the
TUI; `raven tui` still names it outright.
- The page upgrade restarts the gateway, briefly disconnecting IM
channels. It is refused while any turn, sub-agent or pending question is
running.
- During a page-started upgrade the page's port is answered by the
upgrade helper (status and 503s) instead of nothing.
- The helper keeps the current version's wheels under
`~/.raven/cache/upgrade/<version>` (about 75 MB for a release with its
engines), because the tool's receipt names them as the install source.
- A `raven gateway` that starts inside an upgrade window waits it out
and exits instead of serving; the supervisor restarts it once the
install is whole.

Known edge: running `raven web` by hand in the seconds between the old
supervisor exiting and the new one starting can start a second
supervisor beside the relaunched one. The install itself stays protected
by the upgrade marker, and the page no longer tells the reader to do
this.

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

Security: the status endpoint is unauthenticated but loopback-only,
answers only the page's own Host (so a rebound host name gets 421), and
exposes version numbers and byte counts; the relaunch carries the same
token and cookie the `raven serve` path already did. Rollback: revert
the squash commit. Upgrades started from a release without this change
keep the old refusal, so there is no mixed-version state to unwind.

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-27 00:36:05 +08:00
arelchan
2f5027cdfc
feat(ui): give every desk pane one header that names what it shows (#805)
## Summary

Every desk pane said its name twice: once in the window header, then
again in a bar the content drew under it (the file path bar, the task
status line, the node card's back-and-title row). This gives each pane
one header that always names what is on screen, and folds the content's
bars into it.

- New `components/PaneHead.tsx`: glyph (or a back chevron when a part of
something is open), the title, a muted facts line under it, then the
controls that act on the object; the window's fullscreen and close sit
after a hairline. A picked node reads as "task > node", collapsed to one
name when both are the same (a single spawn). The content portals the
head into the desk header, so the state it owns (picked node, tab, file
view) stays where it is.
- The desk header's drag grab is now a native `pointerdown` listener. A
portal's React events bubble through the content's tree, not the
header's, so the old `onPointerDown` prop never heard a press on the
title.
- Task pane: the status bar and the node card head move into the header.
Stop leaves the palette's task list and lives in the pane header, shown
only while the task (or the picked node) is running. The runtime has no
per-node cancel for a graph, so on a graph node it stops the whole run,
and its tooltip says so.
- File and diff panes: the path bar moves into the header. The file
viewer no longer offers a download or the binary note's save-a-copy link
(the conversation's delivery cards keep theirs).
- HTML previews run their scripts by default (`run=1` plus
`sandbox="allow-scripts"`, never `allow-same-origin`, so the page keeps
an opaque origin), without the "preview does not run scripts" note and
its run button. Trade-off: a previewed page can now make network
requests of its own without a click.
- Narrow panes (container <= 560px) drop the parent crumb; the facts
keep their own line so status and duration stay visible.
- Header icons are sized by the ink they draw (about 10px tall each,
even sizes), and close is an SVG cross rather than the font's
multiplication sign, so the row reads level.

## Type

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

## Verification

In `ui-web`, after rebasing on the current main:

- `npm run gen:check`: generated.ts matches the contract (202 methods)
- `npm run lint`: 0 errors (4 existing warnings in files this does not
touch)
- `npm run type-check`: clean
- `npm test`: 210 files, 3077 tests passed
- `npm run build`, `python3 ui-web/build.py`, `node
ui-web/scripts/check-page.mjs`, `check-css.mjs`,
`check-class-namespace.mjs`: all OK
- In `ui-tui`: `npm run lint:i18n`: generated catalogue is up to date

New tests were mutation-checked: each goes red when the behaviour it
names is broken (file/diff path bar back in the body, crumb repeating
the title, crumb not wired, stop on a finished node, no stop on a
running node, stop back on the list, a download control back on any file
kind). Swapping the native grab for a React prop on the header fails
only the drag-by-title test.

Checked in a browser against the offline fixtures (before/after
screenshots of every pane kind) and against a real v0.2.2 gateway: a
spawn task, a markdown delivery and an HTML report render with the new
header, and the gateway answers the HTML request with `sandbox
allow-scripts`.

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

## Risk

User-visible: pane headers change for every pane kind; stop moves from
the palette's task list into the task pane; the file viewer loses its
download control; HTML previews run scripts without asking. Roll back by
reverting this PR; no data or config format changes.

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

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-26 23:58:59 +08:00
KT
8baa35901c
fix(ui-web): let a stored agent api key be replaced from the sheet (#788)
## Summary

The agents page sheet drew its API key field only while no key was
stored. An openai row (MiroThinker) whose stored key the endpoint
rejects therefore offered Connect, was refused by the enable gate with
the remedy "change the key and press Retry", and had no field to change
it in; Retry replayed the same switch. The TUI hub always draws the
field for an openai row, so the two surfaces disagreed.

Changes, all under `ui-web/src/features/extAgents/` (`health.ts` only
has a comment narrowed):

- `ExtAgentsPage.tsx`: the key field is drawn at every stage but live
and stale, with the existing "already set" placeholder when a key is
stored. A key typed there is what the primary press means: the button
then says Connect instead of Retry, a refusal about connecting names
that press in its note, and a refusal about anything else (a description
edit that failed) leaves the head and the note, since the press will not
retry it. Without a key the press keeps its verb. The Enter path shares
the button's in-flight guard.
- `source.ts`: `stageOf` now settles `stale` before `key`. A configured
openai row that is off, has no key and whose preset moved transport used
to be `key` (a key field, and with the new switch a connect that would
have put the old command line on the roster); it is `stale` now, so the
card wears the stale tag and both the card and the sheet offer the
migration. `unauthorized` moves ahead of both, which keeps its
precedence over `stale` as before; every other (kind, configured,
enabled, key, upgrade_to, needs_auth) combination returns what it did.
- `store.ts`: `saveKey` on a configured row that is off follows the
update with the switch, because the server does not prove a key written
to a row that is off; a refused update does not chain the switch. A
keyed connect of a preset now carries the description drafted for it,
which the keyless connect already did.
- Tests: thirteen new sheet cases, two store cases and three stage
assertions pin the stale exclusion, the stage order, the field's
presence per stage, the update-then-switch chain, the refused-update
path, the Enter guard, the Connect label once a key is typed (in a
classified refusal's note and in a bare one's), the fall-back to a
failed test's note once a typed key supersedes a refusal, and that a
connected row's unrelated failure draws no key field.

Known trade-offs, left as is on purpose:

- A key saved on a row that is off is stored before the switch proves
it. That update path was already ungated for a keyless configured row;
this change reaches it from every non-live openai row and follows it
with the switch, which is the gate. A rejected key therefore sits in
config, disabled, until replaced.
- A key typed beside an unrelated refusal (a description edit that
failed on a row that is off) supersedes that retry: the refused edit is
not sent again, the button says Connect, and the refusal leaves the
sheet's head and note. The card keeps showing it until the key is
pressed, since typing is not a write.
- There is still no clear-key control, and a connected openai row cannot
rotate its key from the web; the TUI hub can. Both are follow-ups, not
part of this fix.

## Type

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

## Verification

```
cd ui-web && npm ci
npm run gen:check && npm run lint && npm run type-check && npm test
npm run build && python3 build.py && node scripts/check-page.mjs && node scripts/check-css.mjs && node scripts/check-class-namespace.mjs
npx vitest run src/features/extAgents/
```

Result: gen:check, lint (0 errors), type-check, build and the three page
checks exit 0; the full suite passes (210 files, 3078 tests); the
extAgents feature passes on its own (205 tests). Mutation check:
reverting the field predicate to `!row.enabled` or to `shown !== 'on'`,
dropping the stale exclusion, letting the key stage claim a keyless
stale row again, letting `stale` pre-empt `unauthorized`, dropping the
Enter guard, dropping `!row.enabled` from the chain, dropping the
drafted description from a keyed connect, dropping the typed-key branch
of the button label, keeping a superseded refusal on the line, hiding
the failed-test line behind a superseded refusal, or dropping the
`configured` guard from the stale stage each turns only the matching new
tests red.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (no new
strings; `gui.agent.key_set` already existed in both languages)

## Risk

- User-visible: the API key field now appears on every openai row that
is neither live nor stale, including one whose stored key is fine but
merely switched off. It renders empty with the "already set"
placeholder; leaving it empty keeps Connect exactly as before.
- Saving a key on a row that is off is two writes (the update, then the
switch), so the page re-probes the roster twice for that one press.
- Rollback: revert the commit. No config, wire or server change.

- [x] Security impact considered (the key travels the same
`subagents.update` / `subagents.add` calls as before; a refused write
keeps the typed key in page state for Retry, which is the pre-existing
shape)
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-24 21:03:32 +08:00
xfng-sd
711f262d79
fix(ui-web): route dag edges around the layers they skip (#761)
## Summary

The task board's DAG layout centred every layer on the graph's midline
and drew each edge as a single curve between box centres. An edge that
skips a layer therefore ran straight through the box centred in that
layer. In a real research-to-deck run (`ppt_build` depends on
`ppt_outline` and on the three research nodes `ppt_outline` already
depends on), the `research_rl_algo -> ppt_build` edge was drawn exactly
under `ppt_outline` and its own edge, so it could not be seen at all.

- `graph.ts`: `layout()` now uses `@dagrejs/dagre` (about 48 KB
minified, synchronous) for in-layer ordering and edge routing, and
returns an `edges` list of routes alongside the node positions.
- Layers stay depth-by-longest-path, forced through each edge's
`minlen`, so a root always sits on the first layer instead of drifting
down beside the one node it feeds.
- An edge that skips a layer bends through the gap dagre leaves in that
layer, clear of every box.
- Edges meeting one face of a box get their own ports, sorted by the
direction they head off in, instead of all landing on the midpoint.
- dagre often returns a fan-out mirrored; the layout flips it back when
that reads closer to the server's node order (mirroring changes no
crossing).
- `DagGraph.tsx`: draws each route as flow-axis curves through its
points. Arrowheads and classes are unchanged.
- `Board.tsx` (pan/zoom) and `TasksPage` are untouched. React Flow was
considered and rejected: it does no layout itself, and would replace the
working viewport without fixing this.
- The offline tasks fixture gains this graph on session `c`, so the
board can be checked with `?stub=1`.

## Type

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

## Verification

- `npm run type-check`: clean
- `npx eslint src/features/dag src/rpc/fixtures/tasks.ts`: clean
- `npx vitest run`: 2947 passed, 1 failed. The failure is
`scripts/gates/settings-drawer-css.test.mjs`, which builds a malformed
Windows path (`D:\D:\...`) and is unrelated to this change.
- Every existing layout test passes unedited. New tests, in both flows:
- no segment of any edge route passes through a box, for this graph and
for a mixed one; removing the bends makes 4 of them fail
  - edges into and out of one box land at distinct ports
  - a root that feeds only a deep node stays on the first layer
- `npx vite build`: succeeds
- Eyeballed on the stub data: open session `c` -> Tasks tab -> "Survey
recent RL progress and build a slide deck"

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

## Risk

- [x] Security impact considered (a new client-side layout dependency
only)
- [x] Backward compatibility considered (`DagLayout` gains a field; no
caller reads it besides `DagGraph`)
- [x] Rollback path is clear for risky changes (revert this one commit)

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-24 20:23:26 +08:00
arelchan
96ce7afa7b
fix(ui-web): say a failed connect or test under the agent, not instead of it (#785)
## Summary

The agent connector (Settings > Agent connections, and the onboarding
agents step) is reworked around what goes wrong on it. Frontend only: no
RPC change, and every word drawn comes from fields `subagents.*` already
sends (`data.detail` and `data.remedy` on a refused write, `last_test_*`
on a row).

**A failure is said under the agent, not instead of it.** A refused
connect or a failed test used to replace the line about the agent with a
red sentence, and a card or sheet grew to fit it. Now:

- Every card is one fixed shape: the name, two lines of room for what
the agent does, and a slot that always speaks. With nothing wrong the
slot is a quiet grey word for the row's state (connected, available, not
installed, a caveat, and when a passed test passed). A refused write or
a failed test fills it with a single-line clay strip: one word for what
failed, a short reason read off `remedy.kind` (every kind, including the
ones #779, #786 and #781 added), or "see why" when there is none. A
write in flight fills it in amber. Cards measured at one height across
every state.
- The press that answers a strip is the card's corner control, where
connect and install already live (retry after a refusal, retest after a
failed test on a connected row). The strip carries no button.
- The sheet keeps its fixed 520x500 box. Its head says only which state
(the dot and line read #773's `healthOf`); the why and the how are a
note at the top of the body that scrolls with it: a title per remedy
kind, `FIX_SAY`'s sentence, the command (or #779's two numbered steps
when `remedy.then` is set), and the server's sentence folded under it.
Without a remedy the server's sentence is shown as it came, since it is
the only reason there is.
- The wizard's rows open no sheet, so their second line carries the
step: the short reason, then the command as code, with `then` as a
second piece of code; "run it to see why" for `network`, `silent` and
`config`; and "open it in a browser" for a `plan`, whose command is the
page that sells one.

**Waiting.** Before the first roster arrives the grid draws one
placeholder card per catalogue entry (the catalogue is the roster on
every machine), with the settings sections' shimmer; the tab counts wait
as bars rather than showing 0. The shimmer gate now covers these bars
too.

**Agent marks in the dark theme.** Every mark now sits on a light plate
in both themes, as the app icon does, and no filter reaches a mark.
Inverting `hermesagent.svg` gave its negative, and the hue rotation that
put qoder's green back landed on a different green (#2ADB5C -> #008203).
The plate is a token (`--mark-plate`) declared by every theme block, and
the embedded `color-scheme` is pinned light on the tile, so `raven.svg`
and `miromind.svg` draw their light selves on it.
`agent-mark-css.test.mjs` is rewritten to pin that: no filter on a mark,
the plate token in every theme path, the scheme pinned on the tile and
not on `:root`.

**Copy.** The general settings' language hint now says it picks the
interface's language rather than Raven's.

Rebased onto #773, #779, #786 and #781, which touch the same files.
#773's `healthOf` stays the one verdict for the dot and the sheet's
head; the card's footer and corner, and the sheet's note, are this
change's. #773's rule that an off row wears no dot for a failed test is
kept; its footer still says so. #779's `FIX_SAY` table and step labels
feed the note, with #786's remedy passed through so the `runtime`
sentence names both Node.js versions; a `runtime` fix sent without them
reads as a launch that quit in the title and on the card too (`kindOf`),
as `FIX_SAY` already says it; its row sentences (`bad_run*`,
`bad_retry`, `bad_open`) and the `fix_unknown_*` keys have no caller
left and are removed.

**Earlier decisions this changes, for their authors to confirm:**

- Dark-theme agent marks (@LivXue's filters, @0xKT's gate in #478, whose
note says neither filter may become a blanket rule): the filters are
gone and every mark sits on the plate instead. This reaches every
`.agent-mark` tile on the page, not only the connector.
- A refusal with no remedy (@Handsome-wzw, #730 / #754): the server's
sentence was folded because, shown first, it was a red English
paragraph. Here it is shown as it came when there is no remedy, since it
is then the only reason there is; with a remedy it stays folded.
- An off row whose last test failed (@0xKT, #773): it still wears no
dot, but the card's footer says the test failed.
- Where the fix is said in the sheet (@Handsome-wzw #730, @0xKT #773):
moved from the head's status line to a note at the top of the body. The
head's caveat line for a connected row is unchanged, and still folds the
probe's words under it.
- The card and wizard-row failure text (@Handsome-wzw, #754 / #779 /
#781): the line about the agent stays and the failure is a footer under
it; the row's commands are code inside the sentence. The sentences keep
#779's content. One change of reading: a `config` row says to run `kimi
doctor config` to see where the file is wrong (as #781's sheet sentence
does), where #781's row said to run it and retry.

**Review follow-up.** The failed-test note named Test for every row that
was not connected, but the sheet's bar offers Test only to an
unauthorized row; a row whose test has since cleared its handshake, and
an endpoint still waiting on its key, show Connect alone. The note now
reads its press from the same branches as the bar (`testPress`), and a
test walks every state a failed test can leave a row in and checks the
note names a button the bar renders. The endpoint test that expected
Test for a row waiting on its key now expects Connect.

## Type

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

## Verification

After the rebase onto `main` at `05cac1f1`:

- `npx vitest run --maxWorkers=4` in `ui-web` -- 210 files, 3055 tests
passed; the extAgents suites and page gates alone (`npx vitest run
src/features/extAgents scripts/gates`) 385 tests
- `npx tsc --noEmit -p .` and `npm run lint` in `ui-web` -- 0 errors
(the 4 warnings `main` already has)
- `node scripts/check-css.mjs`, `node
scripts/check-class-namespace.mjs`, `npm run build && python3 build.py
&& node scripts/check-page.mjs` in `ui-web` -- OK
- `npm run gen:check` in `ui-web` -- generated.ts matches the contract
- `npm run gen:i18n` and `npm run lint:i18n` in `ui-tui` -- the
generated table is up to date
- `uv run pytest tests/test_ui_agent_marks.py -q` -- 7 passed
- Real browser (Playwright on the Vite dev page, zh and en, light and
dark), with failure states injected from backend-shaped fixtures
(sign_in, setup, api_key, download, and model with a `then` step; the
unit tests take every kind): all 11 cards 149px tall across healthy,
testing and failed states and in the placeholder grid; the sheet 520x500
for 7 rows in different states; a click on the corner retry does not
open the sheet
- Against a live gateway (Vite dev server proxying `/auth` to it): the
real 18-row roster renders with the new footer and plate

- [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 describe the agent cards.

## Risk

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

User-visible: the card and sheet layout for failures, the corner control
now also retries and retests, the waiting grid, and every agent mark
sits on a light plate in the dark theme (a visible change to all mark
tiles there, including the sub-agents card and pane headers that share
`.agent-mark`). No RPC, config or stored-state change; reverting the
squash commit restores the previous page.

## Related Issues

N/A

---------

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
2026-09-24 20:23:12 +08:00
arelchan
05cac1f17d
feat(ui-web): hold the onboarding wizard to its model and search steps (#784)
## Summary

The web onboarding wizard now asks for a model and, optionally, a search
tool, then enters. The agents and data-sync steps are held back until
they are ready to ship.

- **Two steps on the strip.** `visibleSteps()` in
`ui-web/src/features/onboard/store.ts` reads a `SHOWN` list of `model`
and `search`. The agents and data-sync bodies, verbs and tests all stay;
bringing the steps back means widening that one list. Their existing
tests put all four steps back on the strip through a test-only hook, so
the held-back code stays covered.
- **No work for hidden steps.** Opening the wizard loads only the shown
steps' bodies and runs the importer scan only when the sync step is
shown, so a first run no longer probes every local agent or scans the
importer in the background.
- **Search is optional.** Its step is always done and has no Skip: Start
chatting takes the reader in whether or not a search tool is set. The
model step still has no Skip and still needs a chat model. The held-back
steps keep their Skip.
- **Step strip.** With two steps the strip read as two labels a hair
apart. It is now a 480px track, centred in the header, whose connectors
stretch to fill it and fill from the left once the step before is behind
the reader.

## Type

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

## Verification

- `npm test --prefix ui-web` - 210 files, 3033 tests pass
- `npm run type-check --prefix ui-web`, `npm run gen:check --prefix
ui-web` - pass
- `npm run lint --prefix ui-web` - 0 errors, 4 pre-existing warnings
- New tests: the shipped wizard shows two steps, loads neither the
agents body nor the importer scan, has no Skip on search, and enters
from search with nothing set
- Mutation checks: showing all steps, loading every body, always
scanning, gating search on its body, or giving search a Skip each fails
a test
- `npx commitlint --from github/main --to HEAD`,
`scripts/check_commit_messages.py`, `check_large_files.py`,
`check_source_language.py` - pass
- Walked the two-step wizard in a real browser against a fresh
`RAVEN_HOME`: connect a provider, pick a chat model, Next, leave from
the search step with search unset, landing on the chat page. After the
Skip change, checked in the browser that the strip is centred and its
connector fills once the model step is done; the Skip-less search step
is covered by the page tests above

- [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 describe these screens.

## Risk

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

Frontend only. A first run no longer offers to connect local agents or
import their data from the wizard; agents stay reachable from Agent
Connector in the navigation. The page has no other import entry, so
until the sync step returns an import runs from `raven import` on the
CLI. Rollback: revert the squash commit.

## Related Issues

N/A

Co-authored-by: arelchan <204152633+arelchan@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-24 18:54:38 +08:00
Handsome-wzw
bc8c26795d
fix(*): a refused Kimi Code connect says why and names the fix (#781)
## Summary

Connecting Kimi Code from the agents page told the reader to sign in for
nearly every failure, or showed Kimi Code's English refusal. Measured
2026-09-24 against Kimi Code 2.1.0 with a stand-in model endpoint
answering
each status, and against a real signed-in account whose plan does not
include
Kimi Code: the sheet said "sign in to Kimi Code first", and signing in
again
changed nothing.

The cause is how Kimi Code reports a failure over ACP. A provider
refusing the
credential (401, 403) arrives as `-32000 Authentication required:
<status>
<the provider's message>`. A session it cannot start at all -- never
signed
in, no model, a provider with no key, a config file it cannot parse, a
default
model that is not configured -- arrives as a bare `-32000 Authentication
required`. Everything else a provider says is swallowed: an expired
sign-in,
402, 404, a spent quota all end the turn with no content and nothing on
stderr. The general reading takes "Authentication required" for a
missing
sign-in and passes an empty turn through as English.

- `raven/agent/subagent/kimi_code.py` reads Kimi Code's own words where
they
carry the reason, and where they carry none it asks Kimi Code once more
the
way a reader in a terminal would: `kimi -p` with the connect's own
prompt,
in the environment the ACP launch gets, in a fresh directory, capped at
20 s.
Print mode says why (`error: failed to run prompt: ...`) within a second
for
every failure Kimi Code does not retry. "No model configured" is also
what a
  config file that does not parse reads as, so that one is checked with
  `kimi doctor config` before it is told as a sign-in.
- It runs only for the `kimi_code` preset launched by its shipped
command. A
row whose command was edited keeps the general reading, and its
executable
  is not run a second way.
- It is called from the connect ping (`ping_agent`, after the ping's
pool is
closed) and from the Test button's handshake refusal (`_test_acp`), so
the
  two buttons name one failure one way.
- Kimi Code joins the three preset tables the general reading already
uses:
  `SIGN_IN_HINTS` (`kimi login`, which its `initialize` names too),
`MODEL_SWITCH_HINTS` (`kimi`, then `/model`, whose picker saves the pick
as
`default_model`) and `DIAGNOSE_HINTS` (`kimi -p hi`). What Kimi Code
retries
-- 5xx, a 429 with backoff, an unreachable or refused host, a reply it
cannot
read -- outlasts the connect's 60 s and prints its reason only when it
gives
up, after about 150 s; that is the existing `silent` verdict, now with a
  command.
- `_NO_ACP_FLAG` also reads commander's "unknown command 'acp'" (Kimi
Code's
  CLI) and click's "No such command 'acp'" as the too-old verdict.
- Two remedy kinds: `plan` (the signed-in account's plan does not
include the
agent; `command` is the page that sells one, which a wizard row does not
tell the reader to run) and `config` (`kimi doctor config` names the
line).
- Two shared sentences are corrected for Kimi Code: the `silent` sheet
says
the reason prints "within a few minutes" and lists a provider outage,
and the
  `upgrade` sheet adds that another program may go by the agent's name.

What each failure now comes to:

| Failure, as Kimi Code reports it | Verdict | Command |
|---|---|---|
| never signed in, no provider (`kimi -p`: "No model configured") |
sign_in | `kimi login` |
| sign-in expired and not renewed (empty turn; "authorization grant is
invalid") | sign_in | `kimi login` |
| signed in, plan does not include Kimi Code (403) | plan | the pricing
page |
| API key refused (401) or a provider with no key | setup | `kimi`, then
`/provider` |
| model not found (404) or a default model not configured | model |
`kimi`, then `/model` |
| out of credit (402), balance or quota spent | billing | `kimi`, then
`/model` |
| rate-limited (429 with a short Retry-After) | quota | `kimi`, then
`/model` |
| config file does not parse | config | `kimi doctor config` |
| 5xx, unreachable or refused host, TLS, dead proxy, no answer | silent
| `kimi -p hi` |
| `kimi` does not know `acp`, or never finishes the handshake | upgrade
| none |

A 400 and a content-filter refusal get no kind; their fold now holds
Kimi
Code's own reason instead of "ended its turn with no content".

`rpc-schema/openrpc.json`, `raven/rpc/models.py` and both generated
clients
carry the two new kinds. The TUI renders no remedy and changes only in
its
generated files.

## Type

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

## Verification

Real Kimi Code 2.1.0, one stand-in home per scenario (config and sign-in
shaped
the way `kimi login` writes them, with fake tokens; a stand-in endpoint
for the
provider statuses; nothing read from or written to a real Kimi home),
connected
through this branch's `ping_agent`: 35 scenarios, each verdict as in the
table
above, the control ones connected.

Real browser, on an isolated gateway running this branch (its own home
and
ports, channels off, the Kimi Code row given a stand-in `HOME`): Connect
and
Retry pressed through never signed in, a refused key, a plan without
Kimi Code,
a withdrawn model, out of credit, a rate limit, a broken config, an
expired
sign-in, a `kimi` without `acp`, a start that never finishes its
handshake and
an unresolvable host. Each sheet showed its sentence with the command,
or the
two steps, on their own lines, and each card its one-line verdict.

- `uv run pytest --ignore=tests/integration` after `uv sync
--all-extras` --
26317 passed, 111 skipped, 1 failed:
`test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
which fails the same way on main on this machine (it empties PATH to
stand
in for a host without LibreOffice, and this one has it in /Applications)
- `uv run pytest tests/test_subagent_kimi_code.py` -- 35 passed
- `ui-web`: `gen:check` clean, `type-check` clean, `eslint .` 0 errors
(the
same 4 warnings as main, in other files), `npm test` -- 210 files, 3038
  tests passed; build and both boot snapshots match their goldens
- `ui-tui`: `lint:rpc`, `lint:i18n` and `type-check` clean; `npm test`
-- 144
  files, 2111 tests passed
- Twenty mutations, each reverting one part of the change, each turning
a test
red: the plan, key, expired sign-in and spent-balance readings; the
config
check; asking about a bare refusal and about an empty turn; the
unfinished
handshake; the shipped-command gate; the ask's time cap; the connect and
the
Test button calling it; the too-old regex; each of the three preset
entries;
the sheet's plan sentence, the wizard row not running a URL, the card's
plan
  line, and the page keeping a `config` remedy
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and
`scripts/check_large_files.py` (as CI runs them, on the merge base), and
the
  prospective squash header through `commitlint` -- all clean

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

No user-facing docs describe the connect sheet's messages.

## Risk

Behaviour changes only for the `kimi_code` preset row launched by its
shipped
command. For every other agent `kimi_code.explain` returns before doing
anything, and the ping and Test reach the same verdicts as before.

On a failed Kimi Code connect, Raven now runs `kimi -p` once, and
`kimi doctor config` in one case: up to 20 s more on a failure Kimi Code
does
not retry (measured under a second, ten for a short rate limit). A
failure it
retries times out before the ask and is not asked about. The ask runs
only the
preset's own executable name with the connect's prompt; no row-supplied
argument reaches it. If the failure has passed by then, the ask is one
prompt
on the agent's account, which the connect would have spent anyway.

On the wire, two values are added to an existing optional object. An
older
page drops a remedy of a kind it does not know and shows the generic
line with
the English sentence folded, as before; an older server drops a
remembered
remedy of an unknown kind the same way. Rollback is a plain revert.

- [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-24 18:53:34 +08:00
Handsome-wzw
df77c26d57
fix(*): a Qwen Code on an old Node.js names it, and its model fix runs /auth (#786)
## Summary

Qwen Code is a Node.js script (`#!/usr/bin/env node`), so it runs on
whichever `node` comes first on the PATH it is launched with, not the
one it was installed with. On a machine whose PATH puts an older Node.js
first (an nvm default left on 18, a Homebrew formula nobody upgraded), a
Connect or Test used to end in "Qwen Code quit as soon as it started",
with the reason folded under it as English that names no Node.js at all.

Measured on Qwen Code 0.24.4 with official Node.js builds:

| Node.js on PATH | What qwen does | What the sheet says now |
| --- | --- | --- |
| 18.20.8 | Exits 1 at import: `SyntaxError: The requested module
'node:fs' does not provide an export named 'openAsBlob'` | It needs
Node.js 22 or newer and this machine started it with 18.20.8, plus the
upgrade command when the installer is recognisable |
| 20.20.2 | Runs | Connects, as before |
| 22 | Runs | Connects, as before |

The verdict is read off facts, not off that sentence, which changes with
every release and names no version anyway:

- `raven/agent/subagent/node_runtime.py` (new): resolves the interpreter
from the agent's shebang the way `env` would, on the launch's own PATH
(the row's, else the login shell's), runs `node --version`, and reads
the floor from the agent's own `package.json` `engines.node` (`>=22.0.0`
for qwen). Any missing fact means no verdict, so Node.js is never named
on a guess. The upgrade command is given only where the installer shows
in the path: `nvm install 22 && nvm alias default 22` under
`~/.nvm/versions/node/`, `brew upgrade node` under `Cellar/node/`;
anything else (a pinned `node@18`, an installer package) gets nodejs.org
and no command.
- `presets.py`: `NODE_RUNTIME_PRESETS` holds the presets measured to die
this way, Qwen Code only.
- `probe.py`: a launch that quit is checked only for such a preset, and
only after the `--acp` check; the check runs `node --version`, so
Connect and Test reach it through `asyncio.to_thread`.
- `probe_state.py`, `rpc/models.py`, `rpc-schema/openrpc.json`:
`SubagentRemedy.kind` gains `runtime`, with optional `needs` and `found`
(both sent for `runtime`). Both generated clients were regenerated.
- ui-web: the sheet says both versions and shows the upgrade command on
its own line, or points at nodejs.org when there is none; a `runtime`
remedy that arrives without its versions reads as a launch that quit.
The card says "Qwen Code's Node.js is too old". zh/en strings in
`i18n/messages.json`. The offline fixture library keeps its Qwen Code
row on the two-step model fix, so `needs` and `found` join `UNSENT` with
the reason.

Why the stderr sentence is not the trigger: Raven keeps the last 400
characters of stderr in the error it reports, and the `SyntaxError` line
sits 642 characters from the end of qwen's output, so the Test path
never sees it.

Also in this PR: the fix for a model its provider no longer serves
(404), no credit (402) and a rate limit or spent quota (429) now says
`/auth`, not `/model`. `/model` only picks among the models already
registered in `~/.qwen/settings.json`, and qwen 0.24.4's own OpenRouter
preset registers exactly two free models, both since withdrawn from
OpenRouter's free tier (each answers 404 "unavailable for free",
measured 2026-09-24). So anyone set up the default way was sent to a
list offering only dead models. `/auth` re-runs the provider setup,
whose "Model IDs" step takes any id the provider serves; the sheet's
three sentences now say to enter a working model at that step
(`MODEL_SWITCH_HINTS` in `presets.py`, `gui.agent.fix_model` /
`fix_billing` / `fix_quota`).

## Type

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

## Verification

- `python -m pytest --idle-ceiling-strict` over every test file that
touches sub-agents, the ACP client or the RPC layer: 6423 passed, 1
failed. The failure is
`tests/test_rpc_files.py::test_a_host_without_libreoffice_says_so`,
which fails the same way on `main` on this machine.
- `tests/test_subagent_node_runtime.py` (new, 13 tests): the verdict,
the installer-specific commands, the floor as declared, an absolute
shebang, every missing fact, Connect through the thread, and Test.
Removing the classification call in `probe.py` fails the three
Connect/Test tests.
- `ruff check raven tests` and `ruff format --check raven tests`: clean.
- `python scripts/coverage_gate.py --coverage-json coverage.json diff
--base-ref origin/main --threshold 90`: 100.00% (120/120 executable
changed lines).
- ui-web: `npm run type-check` clean; `npm run lint` 0 errors (4
existing warnings in files this does not touch); `npm run gen:check` in
sync; `npx vitest run` 3035 passed.
- ui-tui: `npm run lint:rpc` and `npm run lint:i18n` in sync.
- Live, real Qwen Code 0.24.4 through `ping_agent` and `run_test`, with
official Node.js 18.20.8, 20.20.2 and 22 first on the launch PATH: 18
gets `runtime` (needs 22, found 18.20.8) on both buttons within a
second; 20 and 22 connect. The 20 Qwen Code cases from #779 were re-run
and give the same results as before, except that the model and billing
cases now name `/auth`.
- The rendered sheet was checked in a browser against the offline
fixture library, zh, both with and without an upgrade command.

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

No user-facing doc describes these refusal messages; the new sentences
live in `i18n/messages.json`.

## Risk

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

The check runs `node --version` on the resolved interpreter, only after
a Qwen Code launch has already quit, and with a 5 s bound, off the event
loop. Nothing is read or sent beyond the agent's own `package.json`.

`runtime`, `needs` and `found` are additive. A page that predates them
drops a kind it does not know and shows its generic "could not connect"
text; a stored verdict carrying them reads back as no remedy on older
code.

Rollback: revert the squash commit; there is no migration.

## Related Issues

N/A

Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
2026-09-24 18:36:57 +08:00