The loader reads a null skillForge or skill_forge section as an absent
one, and skill block and unblock now agree. The settings writer did not:
_write_raw_key walked the dotted path with setdefault, which hands back
the stored null, and raised "blocked by non-object", so the settings
page could not change the skill blocklist of such a config.
A null section on the way to the key is now written as an empty object
under the spelling the file already uses. A section that is neither an
object nor null is still refused, and left as it is.
## Summary
The loader accepts a null skillForge section, but block/unblock either
crashed or created a second section under the other spelling. Treat null
as an empty section for a write, retain the existing spelling, and
refuse other invalid section types without overwriting them.
The CLI regression checks block/unblock, case-insensitive idempotence, a
loadable result and an absent unblock that leaves the original bytes
unchanged. The unblock output must not name a key the write did not use.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Native Windows, Python 3.12. PYTHONUTF8=1; the existing environment was
selected through UV_PROJECT_ENVIRONMENT, and PYTHONPATH pointed at this
checkout.
```text
uv run --no-sync pytest -o addopts= tests/test_config_update.py tests/test_cli_skill_commands.py -k "null_section or invalid_section or skill_unblock_removes" -q --tb=short --show-capture=no
```
Result: 10 passed in the targeted selection. The broader two-file
selection previously produced 89 passed and 4 failed at the pre-existing
POSIX permission assertions in config-update tests. Those failures were
reproduced in the main audit; the affected permission-writing code is
unchanged. The relevant-tests box remains unchecked for the broader
selection.
Whole-branch gates:
```powershell
$changed = @(git diff --name-only origin/main...HEAD -- '*.py')
$production = @($changed | Where-Object { $_ -like 'raven/*' })
uv run --no-sync ruff check @changed
uv run --no-sync ruff format --check @changed
uv run --no-sync ty check @production
uv run --no-sync lint-imports
uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --no-sync python scripts/check_source_language.py origin/main...HEAD
uv run --no-sync python scripts/check_large_files.py origin/main...HEAD
git diff --check origin/main...HEAD
```
All listed gates passed. The whole-branch review covered callers,
ownership, guard boundaries, failure paths, regression strength,
architecture and compatibility. No screenshot change applies; directly
affected code documentation is updated where needed. The full repository
suite and Linux/macOS execution were not run locally; the local Docker
Linux engine was unavailable.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Only an absent or null selected section is initialized. Other invalid
types fail without rewriting the file. Existing dictionaries, spelling
precedence and no-op behavior remain intact. Revert the squash commit to
roll back.
## Related Issues
#500
## Summary
A reused tool-call ID could pin unrelated results or a superseded skill
fetch. Pin each fetch's parent and results using the same positional
pairing as HistoryTrimmer, retaining sibling results and only the latest
fetch per skill.
Manifest group labels now use that same parent relation. Separate
exchanges that reuse a call ID get separate labels, while a parent and
all its results share one label. Unpaired messages have no group label.
Remove the unused raw-ID parent map and update the pinning docstring to
describe whole-group trimming.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux, Python 3.12, on the latest main base:
```text
uv run --frozen --python 3.12 --no-sync pytest tests/test_curator_context_engine.py tests/test_history_trimmer.py -q -n 0 --tb=short
uv run --frozen --python 3.12 --no-sync ty check raven/context_engine/curator.py
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
```
Results: 43 tests passed; type checking, applicable hooks and all listed
gates passed. Four manifest regressions failed before the label fix.
Coverage checks reused and distinct call IDs, sibling results, unpaired
and malformed records, latest-fetch pinning, selection closure and saved
manifest labels. 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
The affected code documentation is updated; no user-facing controls
changed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Manifest group labels are recomputed from message positions each turn,
so previously saved labels need no migration. Histories with reused IDs
retain the intended pinned exchange without unrelated results. Revert
the squash commit to roll back.
## Related Issues
#885
<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>
## Summary
First of a series of changes that let an ACP sub-agent run on a machine
in the
machine registry (`connections.json`), reached over ssh, so one turn can
dispatch work to agents on several machines at once.
The approach was measured first, on two registered Linux machines and
without changing code: raven's own `AcpClient`, started on an `ssh`
line,
already drives a remote `claude-agent-acp` and `qwen --acp` (handshake,
`session/new`, `session/cancel`, 10 connections at once), and a remote
agent exits once the local ssh is killed -- idle within 15 s, and mid
tool call within 2 s, its child command included. What breaks is
everything that assumes the agent shares this disk; the first of those
is that an agent refuses a `cwd` that does not exist where it runs
(`-32602 cwd does not exist on the machine running the agent`).
This change adds the pieces only a remote agent needs, with nothing
calling them yet:
- `raven/acp_client/remote.py`
- `machine(id)`: the registered ssh machine. Refuses an unknown id, an
unreadable registry, an entry with a blocking problem, and a local
row, each in one sentence. Looked up in the caller, the way the
machine channel looks one up, since main keeps the registry's
readers to what its callers need.
- `launch_command()`: the ssh line, as the one string the pool and
`AcpClient` already take as a command (`shlex.join`, so their
`shlex.split` gives back the argv). Built from the registry at
launch and never stored, so no address, port or key path reaches a
config file, log line or model. The agent starts in the machine
user's login shell (`$SHELL -lic`): measured, agents installed
through nvm or into `~/.local/bin` are on that PATH and no other.
The remote command is one argv element after `--`, quoted once per
shell that reads it -- the hand-written form
`ssh host -- bash -lic 'qwen --acp'` loses `--acp` to the far
shell's re-parse and hangs to the initialize timeout.
- `ssh_log_path()` / `read_ssh_log()`: ssh's own messages name the
address ("connect to host <ip> port <n>", and on a first connect
"Permanently added '[<ip>]:<n>'"). The launch line sends them to an
owner-only log per agent (`ssh -E`) instead of to stderr, which the
connection journals and quotes in its errors; they are read back
only to classify a failure. Measured: with `-E`, stderr carries the
far side's output and nothing of ssh's.
- `session_dir()`: `<root>/<handle>` made on the machine and resolved
to an absolute path in one round trip (0.17 s measured). A directory
the machine will not make is reported with the machine's own last
word -- measured on a registered machine whose disk had filled, "No
space left on device" -- skipping any line that carries the address.
- `explain()`: one sentence for an ssh-level failure (timed out,
unreachable, login refused, host key changed, agent not installed),
naming the machine and never its address.
- `raven/ops/transport.py`: the ssh options move into `ssh_argv()` and
the row's address into `ssh_target()`, so the one-shot runner and a
remote agent share one spelling. The runner sends the same argv as
before; a new test pins it.
- `docs/specs/2026-08-11-acp-local-agent-mesh-design.md`: its "remote
agents" non-goal carries a dated amendment pointing at `remote.py`.
ACP still runs over stdio only; the local process is ssh.
The next change (#897) wires this into the ACP backend behind a
`machine`
field on an agent's entry. Later changes add a small Raven process on
each registered machine that
reads and writes files there for this one, so the main agent can read a
remote file's lines without copying the file; scp-style remote paths for
the file tools; and `machine` on `subagents.add`.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run pytest tests/test_acp_remote.py tests/test_ops_transport.py
tests/test_ops_connection_add.py tests/test_shell_machine_channel.py
tests/test_ops_connections.py`
-- all passed. The quoting cases run the remote command through real
shells here (`sh -c` standing in for sshd, `$SHELL -lic` for the login
shell, `HOME` in a temp dir): the agent's own arguments arrive intact,
a variable valued ``a b 'c' "d" $HOME `id` \e`` arrives unexpanded,
a `~` root with a space in it is made and entered, a relative root
comes back absolute from the login's home, and an agent on the PATH
only a login shell's `.profile` sets is found.
- The same generated command run under dash on a registered Linux
machine: same argv, cwd and value.
- Real machines, through `remote.py` and raven's `AcpClient`, against a
scratch registry (not `~/.raven`): the session directory was made and
resolved on the machine, `claude-agent-acp` answered `initialize` and
accepted `session/new` in that directory; a machine that does not
answer, an unregistered id, a wrong key and an agent that is not
installed each came back as one sentence with no address in it. The
remote test directory was removed afterwards and no process was left.
- `uv run pytest --ignore=tests/integration --idle-ceiling-strict` --
27800 passed, 119 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.
- Diff coverage over the changed lines: 99% (the gate asks for 90).
- Twenty mutations, each reverting one part of the change, each
turning a test red: the machine's reason dropped, the line carrying
the address kept, the inner command not quoted for the outer shell,
the variable assignments not quoted, `-T` dropped, `--` dropped, the
extra options placed after the destination, the runner's host-key
option dropped, ssh's own words passed on, the host-key failure not
recognised, an unsafe handle kept without its digest, a slash allowed
in a handle, a local row accepted as a remote machine, an entry with a
blocking problem accepted, the session directory echoed instead of
resolved on the machine, a failed `mkdir` taken as success, a `~` root
quoted so the shell cannot expand it, the agent not started in the
root, a bad variable name let through, and the agent started outside
the login shell
- `scripts/check_source_language.py`, `scripts/check_commit_messages.py`
and `scripts/check_large_files.py` on the branch range, and the
prospective squash header and the commit 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
Nothing user-facing changes yet: no entry can name a machine until the
next change.
## Risk
No behaviour change. `remote.py` has no caller yet, and the one-shot
ssh runner sends the same command line as before, pinned by a test. The
launch line carries the machine's address, which is why it is built at
launch and held only in memory; variables travel on that line too, so
the design keeps secrets off it (no lent keys for a remote agent).
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>
## Summary
System-store upgrades passed both certificate-variable names to uv,
causing a deprecation warning on releases that warn even when the
replacement variable is present. Ask the uv used for installation for
its version and add `UV_NATIVE_TLS` only for releases before 0.11 or
when the version cannot be read. Explicit user settings remain intact.
- Keep certificate-store handoff in a fresh private directory, remove it
from the helper's import path after loading, and test both properties.
- Pin ordinary sub-agent connection failures as `network_error`,
distinct from certificate refusals.
- Let `security.tls.system_ca_in_use()` own the query of the actual
injected SSL factory. Upgrade and integration fixtures use the public
switch rather than duplicating its implementation.
- Cover a timed-out `uv --version` in the real helper orchestration. The
existing 30-second timeout falls back to the legacy certificate
variables so installation and relaunch can continue. Removing the
`SubprocessError` catch now fails this test.
This completes review follow-ups to the system-store change. The timeout
follow-up adds coverage without changing the existing fallback or its
duration.
## 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
Linux, Python 3.12, after rebasing onto current main:
```text
uv run --frozen --all-extras pytest tests/test_security_tls.py tests/test_updates_upgrade.py tests/test_updates_install_guard.py tests/test_cli_subagent_setup.py tests/test_cli_system_ca.py tests/test_cli_onboard_commands.py tests/test_cli_provider_commands.py tests/test_config_update_providers.py -q -x --tb=short
uv run --frozen --all-extras pytest tests/integration/test_cli_upgrade_real_uv.py -o addopts= -n 0 -q --tb=short
```
Results: 894 passed and 3 passed, respectively. The real upgrades cover
library roots and handed-over system roots. Two existing idle-ceiling
warnings were reported by the integration tests.
Native Windows, Python 3.13:
```text
uv run --frozen --extra dev pytest tests/test_updates_upgrade.py -k older_than_system_certs -n 0 -q -x --tb=short
```
Result: 6 passed, including `subprocess.TimeoutExpired`. An isolated
mutation removing `subprocess.SubprocessError` from the version probe's
catch failed exactly the timeout case; the production source was then
restored and checked against Git.
Additional checks passed:
```text
uv run --frozen --extra dev pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen --all-extras ty check raven/security/tls.py raven/updates/upgrade.py
uv run --frozen --all-extras lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
Import-linter kept all 10 contracts. The full repository suite and
native macOS were not rerun for this follow-up. No user-facing
documentation change is needed for the additional timeout test. Existing
integration fixtures can use the user's upgrade cache, and some helper
tests reach GitHub before exercising a fallback; these predate this
follow-up.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
An older or unrecognized uv still receives both certificate-variable
names, preserving compatibility behind a TLS-inspecting proxy. An
explicit legacy setting may still produce uv's own warning. The version
query is bounded, and its failure does not prevent an upgrade attempt.
No certificate verification is disabled.
Rollback: revert the squash commit, restoring the previous warning and
unpinned handoff behavior.
## Related Issues
#878, #637
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
When a long history exceeds its token budget, every dropped group causes
another estimate of nearly the same prompt. Re-encoding all retained
text repeatedly dominates the remaining trim time. Reuse unchanged
tokenization within one synchronous history trim while preserving its
selected messages, IDs, warning sequence, and estimates.
- Split text only at newline-to-non-whitespace boundaries that the fixed
cl100k tokenizer cannot cross. Per-message token counts are not
independently additive, so subtracting whole messages would change
estimates at some joins.
- Count the first prompt with one whole-payload encoding. Reuse an
identical estimate directly; build fragment costs and multiplicities
only when a later prompt differs. A trim that already fits pays no
per-line encoding overhead. Then subtract removed fragments and encode
new fragments or changed joins, retaining only current fragments.
- Scope the cache to one trim, restore enclosing scopes, and release it
on errors. Empty prompts and tokenizer failures clear cached state while
preserving the existing whole-payload fallback. Custom provider counters
keep their existing call path.
- Keep the cl100k encoding name beside its boundary rule and pin a
counterexample that fails if the encoding is changed without revisiting
the split. Test that estimates outside a trim retain no state, and that
empty or failed estimates release the initial unsplit prompt too.
- Correct the indexed group-sweep test's stale explanation.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
Performance improvement.
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Linux, Python 3.12, on current main:
```text
uv run --frozen pytest tests/test_token_estimation.py tests/test_history_trimmer.py tests/test_curator_context_engine.py tests/test_context_engine_factory.py tests/test_default_context_engine.py -q -x --tb=short
```
Result: 125 passed. Tests compare cached and uncached whole-trim results
and real-tokenizer counts, including whitespace, repeated fragments,
reasoning, tool definitions, images, special-token fallback, nested
scopes, exceptions, custom builders, and provider counters. A
performance guard measures characters sent to the encoder rather than
relying on wall-clock timing. The tested source files were verified
against their committed Git blobs.
Full-trim benchmark with the production estimator: 1,200 messages, 123
removed, median of three alternating runs. The control disables only
tokenization reuse; both paths include the group-index optimization
already on main. Returned messages, IDs, warnings, and estimates were
identical.
| Measurement | Uncached tokenization | Scoped reuse |
| --- | ---: | ---: |
| Median trim time | 1.577 s | 0.422 s |
| Python allocation peak, measured separately | 3.462 MiB | 3.308 MiB |
This workload was 3.74 times faster. Prompt construction and structural
selection still run normally, so this is a measured improvement for this
workload, not a constant-time guarantee.
First-estimate control, about 2 MB of unique lines, median of three
alternating runs in one process. All token counts matched:
| Line width | Whole encoding | Previous eager fragments | Deferred
first estimate |
| --- | ---: | ---: | ---: |
| 15 characters | 0.188 s | 0.549 s | 0.184 s |
| 40 characters | 0.111 s | 0.256 s | 0.108 s |
| 80 characters | 0.108 s | 0.183 s | 0.110 s |
| 200 characters | 0.171 s | 0.203 s | 0.158 s |
Four additional isolated mutations were caught: a shared default cache
outside trims, changing only the encoding to o200k, restoring eager
splitting, and leaving the initial prompt behind after clear. The last
mutation exposed a missing test, which was added before publication.
Native Windows token/history/curator tests passed 62 cases before the
two final clear cases; both final cases then passed separately.
Additional checks passed:
```text
uv run --frozen --python 3.12 --extra dev pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen ty check raven/context_engine/history_trimmer.py raven/utils/tokens.py
uv run --frozen lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
Import-linter kept all 10 contracts. The full repository suite and
native macOS were not rerun locally. No user-facing documentation or
screenshot applies.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
The split relies on the fixed cl100k token-boundary property and is
checked against the real encoder. Text is retained only inside the
current trim; no cache persists across requests. No dependency,
configuration, or persisted-format changes.
Rollback: revert the squash commit.
## Related Issues
#886
## Summary
Workspace-local pipelines could lose the preceding directory state and
be refused, while mixed OR/AND chains could incorrectly assume a skipped
directory change had executed. Track successful and failed paths
separately, evaluate pipeline members from their entry directory and
retain both lastpipe and pipefail possibilities.
Preserve flow operators after group terminators so grouping cannot hide
a branch or pipeline. Inspect shell payloads carried by command runners,
and refuse payloads beyond the shared inspection bound in both the
workspace fence and builtin policy, including the policy's find
-exec/-execdir path.
The workspace fence now explicitly refuses unmodelled conditional/loop
control flow, previous-directory operands and unrecognized directory
options. Update its contract and directory-walk documentation
accordingly.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Linux, Python 3.12, after rebasing onto main:
```text
uv run --frozen --python 3.12 --no-sync pytest tests/test_agent_loop_session_stamps.py tests/test_shell_policy_reasons.py tests/test_shell_workspace_fence.py tests/test_shell_comments.py tests/test_shell_command_writes.py tests/test_shell_file_removals.py tests/test_shell_background.py tests/test_shell_machine_channel.py tests/test_rpc_shell.py tests/test_permissions_gate.py tests/test_permissions_session.py tests/test_permissions_judge.py tests/test_acp_permissions.py tests/test_shell_approval.py -q -n 0 --tb=short
uv run --frozen --python 3.12 --no-sync ty check raven/agent/tools/shell.py raven/permissions/shell_policy.py raven/permissions/builtin.py
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
```
Results: 1113 tests passed; one test skipped because this host's OpenSSH
does not support -P tags. Type checking, applicable hooks and all listed
gates passed. The current changes were verified locally on Linux.
Regression tests reproduced the grouped-operator, nested-policy and
previous-directory gaps before each fix. Separate mutation checks fail
when either lastpipe/pipefail state is discarded or the fence's nesting
bound diverges from the policy. All mutations were restored. Security
payloads were classified as strings, never executed. Independent
read-only security review confirmed the reported gaps were closed. The
file-event fixture uses a valid harmless command so the real fence can
admit the mocked executor; all event, diff and persistence assertions
are retained.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The affected code contracts are updated; no UI controls were added.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
With workspace restriction enabled, even harmless unsupported
conditionals/loops, cd - and unrecognized directory options are refused.
Supported literal directory operands, ordinary local pipelines and
bounded runner payloads remain usable. Excessive nesting is refused by
builtin policy even for harmless payloads. The textual fence retains its
documented command-substitution limitations; sandbox execution provides
the runtime boundary. Revert the squash commit to roll back.
## Related Issues
#527
---------
Co-authored-by: Codex <noreply@openai.com>
## Summary
raven-research reports were written for a grader: fixed `## Answer` /
`## Findings` / `## Limitations` headings, HTTP codes beside links, and
a
chat reply that drifted from the file saved with `write_file`. This
branch
ships them in a reader layout and closes the gaps that product runs on
DeepSeek showed between the brief, the reply and the saved file.
Reader layout (`finalShape.reportLayout = "reader"`, on for
raven-research):
- The report opens with the answer as a blockquote, with no label or
bold
lead-in. Anything the brief asks the report to open with (a retrieval
date, the kinds of sources) follows in the blockquote. Delivery facts
the
brief asks back (path, counts) go on its last line, which the chat reply
keeps and the saved file leaves out.
- The body sits under its own `##` headings, using the brief's section
names word for word, numbering included, when it gives them. The last
section names what could not be verified (`## Limitations` in English;
the reply's language otherwise, with no English word in that heading).
The shape gate reads the last `##` section as the limits when no word it
knows names them, since no word list covers every language, and when
only the first heading has such a word with no body above it (a body
heading on export limits is body, not limits). The audit reads it the
same way and counts a body written as prose under the answer.
- Prose cites through markdown links, with no fetch status beside them.
A
brief that asks for link checks gets one table before the limits,
listing
every cited URL as fetched, with its status, marked blocked where the
site blocked the fetch.
- The layout is derived from the deep clause, so the evidence rules stay
one text. The shape gate, its reminder, rewrite prompt and interrupted
fallback, and `scripts/research_report_audit.py` read it as the same
three parts. A test pins the audit's limits matcher to the gate's.
Chat and file are one text: at turn end the delivered reply is written
over
the report file the turn wrote. Which file that is:
- A markdown file the turn wrote whole, or appended to or edited when
the
turn wrote it whole first or it still holds exactly what an earlier turn
of the session left in it. The session record keeps the sha256 the
session left in each report file, checked at turn start before any tool
runs. Any other file (a log the user keeps, a report the user changed
between turns) holds someone else's text, so it is never the report. A
later turn that only edits a report nobody else touched still syncs it.
- Whose `##` headings are at least half the reply's. On the
reader-layout
product runs a report draft shared 75-100% of its headings with the
reply, and a notes file saved beside the report shared none, so a notes
file or a source index is never overwritten, alone or beside the report.
- Of several such files, the one the reply names; when it names none or
more than one, every file is left alone.
The file keeps its `#` title when the reply has none. It is also left
alone
when the reply is not a report, or when the reply is under 80% of the
file's length, so a summary reply never replaces the report. The path is
read from the first line of the tool's result only, matched against the
tool's whole fixed wording, and the file tools now
refuse a path that carries a line break or other control character: they
echo the path into their results, so such a path could forge a second
result line naming a file outside the workspace.
Length and counts, measured rather than estimated:
- Every markdown write or edit gets a `[report length: ...]` line on its
tool result, carrying:
- CJK characters and other words, with prose and tables apart;
- the same counts per `##` section;
- the number of distinct URLs cited, extracted the way the research
trail extracts them.
- The report checks a brief's length against that line, and takes any
count it states (sources included) from it.
- `write_file` now reports bytes. Its success line said "N bytes" and
counted characters, so a Chinese report was sized at about a third of
its real length.
Fetch status and the research trail:
- The research fetch tool reports the target's own status from the Jina
reader's header instead of the reader's 200, and marks a CAPTCHA wall as
`blocked`.
- The trail counts such pages as refused by the site, not as read, per
fetch: a page refused once and read on a retry counts as read. When a
thin page is re-read at another address, each address keeps its own
status: the stub its own, each fallback the one in its own header.
- The trail drops click-tracking parameters (`utm_*`, `srsltid`,
`gclid`,
`fbclid`, `msclkid`) before matching a citation.
- Its `<details>` folds are now plain labelled lists, since a terminal
shows the tags raw.
- `scripts/research_report_audit.py` reads the refused-page clause and
note. It also reads the reviewer verdict when the trail names the
reviewing model. That second break predates this branch: a model id
carries `/` and `-`, so the verdict read as missing on every product
trail.
Other:
- The research reviewer now runs on DeepSeek in thinking mode. That
provider refuses a named `tool_choice` with HTTP 400, so every review
failed open and each report shipped unreviewed. The gate retries with
`tool_choice=auto`.
- `measuredGuidance` is off in the shipped config. Its numbers were
measured on a short-answer benchmark and pull a long report toward a
terse answer.
- The appendix twin's guard names the twin's lead over the frozen dr@3.5
record instead of requiring the two to be equal: 4 added and 5 changed
definitions, with `ResearchTrail` compared member by member so its
untouched members stay pinned. The record itself is unchanged from
`main`.
- The product label moves to the `-reader` suffix. Its digest was
re-stamped several times on this branch only; `main` never shipped an
intermediate digest.
Checked and deliberately not changed here:
- The main agent's own `web_fetch` (`raven/agent/tools/web.py`) also
reads through Jina and still reports the reader's 200 for a target
error. It is a separate module, not a twin of the research tool, so it
needs its own change.
- `fetch_result_ok` is unchanged, so a page the site refused still
releases the fetch gate, counts toward the evidence floor and enters the
conversation memo as a source. Changing it would move when the gate
releases.
- The report sync writes the file directly, not through `write_file`, so
it
emits no file-change event and a client's diff panel does not show it.
raven-research runs with no write approval, so no approval is bypassed.
- Every CAPTCHA flag in 36 local fetches that carried a reader warning
was
on a page of 862 characters or fewer. Target errors appear on pages of
up to 18k characters, and each one checked was a real error page. No
false positive was found.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run after rebasing onto the current `origin/main`. The range-diff
against
the pre-rebase branch is `=` for all 15 commits.
- `uv run pytest tests/test_agents_research_*.py
tests/test_research_*.py tests/test_filesystem_write_modes.py
tests/test_agent_tools_web_fetch.py tests/test_history_trimmer.py
tests/test_context_engine*.py -q`: 1070 passed.
- Full suite before the rebase, `uv run pytest tests -q`: 27745 passed,
118 skipped, 12 failed. None of the 12 were introduced by this branch:
- 11 fail identically in clean worktrees of `origin/main` and of the
branch head. They are environment-bound: proxy redaction, NAT64
addresses, the node path.
- `test_agents_ppt_launcher` passes in the clean branch worktree and
failed only because of an uncommitted local edit to
`agents/raven-ppt/subagent.json`.
- Mutation checks: each of these, reverted alone, turns its new tests
red:
- the target-status override;
- the refused-page split;
- the ledger classification;
- choosing the named report file (3 tests fail with `paths[-1]`);
- the audit's refused clause;
- the audit's ` via ` terminator.
- After the second review round:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py -q`:
1238 passed. Each fix, reverted alone, turns its new test red: the
control-character refusal, the first-line read, the append rule, the
last-section limits (gate and audit apart), the fallback verdicts, and
the URL count, the per-fetch refusal, the draft-heading filter and the
session-wide edit rule. The twin guard fails on an undeclared definition
and on a
stale lead entry.
- After the third review round, on the rebased head:
`uv run pytest tests/test_agents_research_*.py tests/test_research_*.py
tests/test_filesystem_write_modes.py tests/test_filesystem_tools.py
tests/test_deliver_files_tool.py tests/test_rpc_files.py
tests/test_rpc_turn_send.py tests/test_tool_registry_execute.py
tests/test_tools_workdir.py tests/test_agent_tools_web_fetch.py
tests/test_history_trimmer.py -q`:
1278 passed. Mutants each turn the new tests red: the unanchored
unchanged-file match; the control-character guard narrowed to LF, or to
`Cc` only; each of the four success lines reworded in the real tools;
a twin-only change to an untouched `ResearchTrail` default.
- After the fourth review round, same command: 1288 passed. Mutants each
turn the new tests red: held files taken without the digest check, the
digest never recorded, held files ignored, the first-heading rule
reverted in the gate and in the audit apart, the gate's body-above
condition dropped, and the audit's prose-body count dropped.
- `make lint-python`, `make lint-imports`, `make lint-deps`,
`make lint-types`: all pass.
- `scripts/check_commit_messages.py origin/main..HEAD`,
`scripts/check_source_language.py origin/main...HEAD`,
`make check-large-files`: all exit 0.
- Product runs through the TUI host, on reports about personal agents,
AI
glasses, AI coding agents, office agents and edge AI:
- The saved file equals the reply, less the delivery line, with its
title kept.
- The stated length and source count match the `[report length]` line.
- The link-check table has one row per counted URL.
- A Gartner 403 and an HBS 405 behind a CAPTCHA came through with their
real status.
- [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:
- raven-research replies and saved reports change form: an answer
blockquote, no fixed headings, no HTTP codes beside links, and a single
link-check table.
- The report file a research turn wrote is overwritten with the
delivered
reply at turn end, except in the cases above.
- `read_file`, `write_file`, `edit_file`, `list_dir`, `deliver_files`
and
the RPC file reads refuse a path containing a line break or other
control
character (they share `resolve_path`).
Existing installs keep the contract they seeded into
`agent_memory/profile/agent.md`. The new layout reaches them only after
that file is deleted; until then the gate still accepts the old
three-heading replies. The changelog says so.
Not covered by this branch:
- The research subagent pins `contextWindowTokens` to 65536. On a host
model with a 1M window, the budget note reaches 80-136% early and cuts
research short. Left as is on purpose; it is a separate decision.
- Post-delivery behaviour of the host agent is unchanged. It may recount
or edit the report after delivery.
Rollback: revert the squash commit. To keep the code but drop the
layout,
set `finalShape.reportLayout` to `"sections"` in
`agents/raven-research/config.json`.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: userName20260323 <270284818+userName20260323@users.noreply.github.com>
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## 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>
## Summary
- `raven upgrade` syncs the tool environment to the release's
requirement set, so a boxlite the sandbox advice (#640, #822) installed
into it is gone after the upgrade and a configured boxlite backend fails
to start. This carries it across, along the lines outlined in the issue
discussion.
- Detection is parent-side, before the handoff: `_boxlite_installed()`
reads importlib.metadata against the running environment, because the
helper runs under `-I` with the base interpreter and cannot see the tool
environment's packages. The fact crosses as `RAVEN_UPGRADE_KEEP_SANDBOX`
in the env dict `_handoff_upgrade` already builds, rather than a seventh
positional argument.
- In the helper, when the flag is set, each rung is preceded by its
sandbox-carrying variant (`raven[channels,sandbox]` / `raven[sandbox]`),
the plain rung stays behind it as the fallback, and a warning names the
loss when the sandbox variant did not land. The `sandbox` extra keeps
its existing platform gate, so where boxlite never installs the flag
reads 0 and the ladder is exactly today's.
- The warning texts follow the existing lost_channels / lost_engines /
lost_plugins pattern.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally: `uv run pytest
tests/test_updates_upgrade.py` -> 160 passed (five new or extended:
first rung carries the extra when boxlite is present; fallback to the
plain rung with the warning; exactly today's rungs without the flag; the
handoff env carries 0 and 1); `uv run pytest
tests/test_cli_upgrade_commands.py` -> 14 passed
- [x] The new tests fail on current main: stashing only the `raven/`
changes -> 3 failed, and the without-flag test passes both sides as it
pins today's ladder
- [x] Relevant lint / type checks pass locally: `ruff check` + `ruff
format --check` on the two files; `ty check` at the pre-change baseline
(18 platform-only diagnostics on Windows, no new)
- [ ] User-facing docs or screenshots are updated when needed: the
warning string is the user-facing surface and follows the existing
pattern
## Risk
- [x] Security impact considered: the flag is set from a local package
lookup and only selects between requirement strings the helper already
installs
- [x] Backward compatibility considered: the env var is absent on an old
parent or a direct helper run -> the ladder is today's, pinned by a test
- [x] Rollback path is clear: plain revert; the upgrade either carried
the extra or left the install exactly as before
## Related Issues
Fixes#844
## Summary
A direct chat runs on an instance lane, while permission modes and
session grants belong to its parent conversation. Looking up the lane
lost the conversation's settings; splitting at the first `#` instead
merged distinct separator-named conversations. Carry the original parent
key across the request and use it at each permission entrance.
- `PermissionTurn.session` supplies the conversation for both mode
lookup and session-grant reads/writes. Ordinary conversation IDs remain
verbatim.
- Normal sends, injected direct turns, and instance-addressed cron wakes
carry `TurnRequest.parent_session`. `session_key_for` is the shared
resolver used by RPC, Gateway, and one-shot CLI permission bindings.
- Older internal requests without the new field remove their known
complete target suffix, preserving `#` in both the parent and handle. A
declared parent remains authoritative.
- The real direct-chat execution path uses the same parent for instance,
record, and working-directory lookup. Registered RPC direct-chat events
preserve that parent when routing; completion and error events use the
target captured before lane cleanup.
- Record the conversation-wide mode/grant contract in `CONTEXT.md`. A
grant in a direct chat covers its parent and sibling instances in that
conversation, without covering another conversation that shares a
textual prefix.
The a2a entrance constructs no direct request and keeps its ordinary
conversation identity. The main-agent-only configuration tool continues
to read the main conversation directly. Approval questions retain their
lane identity for correlation; the permission policy reads the original
session separately.
## 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
Linux, Python 3.12:
```text
uv run --frozen --all-extras pytest tests/test_permissions_*.py tests/test_spine_*.py tests/test_rpc_spine.py tests/test_rpc_turn_send.py tests/test_core_cron_stack.py tests/test_gateway_spine.py tests/test_cli_one_shot_spine.py tests/test_agent_loop_session_model.py tests/test_agent_loop_run_emit.py tests/test_agent_playbook_delegate.py tests/test_subagent_direct_chat.py -q -x --tb=short
```
933 passed. Native Windows, Python 3.12:
```text
uv run --frozen pytest tests/test_permissions_gate.py tests/test_spine_turn.py tests/test_rpc_turn_send.py tests/test_rpc_spine.py tests/test_gateway_spine.py tests/test_cli_one_shot_spine.py tests/test_core_cron_stack.py tests/test_subagent_direct_chat.py -n 0 -q -x --tb=short
```
631 passed before the final ordinary-session cases; the final six-case
ordinary/direct entrance matrix passed on Windows and Linux. After the
final entrance/comment cleanup, the following selection passed 5 cases
on each platform (with `--all-extras` on Linux):
```text
uv run --frozen pytest tests/test_rpc_turn_send.py tests/test_core_cron_stack.py -k "separator_named_permission or wake_naming" -n 0 -q -x --tb=short
```
Before the fix, the real `turn.send` request passed through each of the
three runners ignored the parent's `ask` mode and returned `Allow` from
the default. The regressions now verify that mode, grant inheritance,
and isolation from a sibling separator-named session. Producer tests pin
the carried parent on ordinary sends, injects, and cron wakes. The real
AgentLoop direct branch and final RPC events retain the full parent too.
Fourteen isolated mutations were caught: three additional cases split
ordinary session IDs at the entrances, plus each permission entrance
reverting to the first separator, each of the three producers dropping
the parent, ignoring the declared parent, truncating the legacy
fallback, using a truncated key for the direct-chat record, and losing
the captured target separately at completion and error. Sources were
restored and compared with the committed blobs.
Whole-branch pre-commit, type checks on every changed Raven Python
module, import-linter (10 contracts kept), commitlint, the Python
commit-message checker, source-language and large-file gates, and `git
diff --check origin/main...HEAD` passed. The full repository suite and
native macOS were not rerun. Runtime contracts are updated; there is no
visual UI change requiring screenshots.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Direct chats intentionally inherit their conversation's permission mode
and session grants. This also means an approval granted in one instance
is shared with other turns of that same conversation. Separator-named
conversations retain distinct scopes. The new request field is internal;
no RPC schema, persisted format, or lane spelling changes. Legacy
unannotated string-only routing outside these request paths is not
redesigned.
Rollback: revert the squash commit.
## Related Issues
Fixes#905
## Summary
Skill descriptions written as YAML continuation lines, block scalars, or
nested mappings were truncated or replaced by the registry's line
parser. Read frontmatter as YAML while retaining the legacy line
fallback for unsupported input.
- The registry and SKILL importers share one parser in
`raven.utils.text`, including alias rejection, the 16,384-character
limit, and string fallback for `name` and `description`. Metadata and
body are returned from the same split: complete three-dash delimiter
lines allow trailing spaces, while longer horizontal rules are ordinary
content.
- Bound composition to 32 nested nodes, returning the line fallback
before Python's recursion limit. The character cap alone is not a
CPU-time guarantee.
- Accept nested metadata only as a mapping or JSON string. Binary YAML
metadata is ignored rather than allowing one file to abort the entire
registry and eager catalog construction.
- Document YAML coercions: `always: on` and nonzero numeric values are
true; whitespace-prefixed unquoted `#` starts a comment, including in
`description` and `inject`. Quote literal text accordingly.
- Preserve full multiline descriptions and collapse their whitespace for
display. Pin numeric, boolean, null, and sequence descriptions to their
source spelling.
- Preserve an invalid leading YAML block in imported memory notes. The
legacy line fallback is explicit for SKILL readers; generic memory
readers retain the original text on parse failure, so rules inside an
invalid block are not silently removed.
## 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
Linux, Python 3.12, after rebasing onto current main:
```text
uv run --frozen --all-extras pytest tests/test_cli_skill_commands.py tests/test_skill_forge_loader_parity.py tests/test_importer_* -q -x --tb=short
```
405 passed, 2 skipped because chmod cannot deny the root test user
access. The selection covers registry/catalog construction, the skill
CLI, importer readers and installation.
Before the fixes, two binary-metadata cases raised UnicodeDecodeError,
four importer/registry parity cases disagreed, and both depth-limit
regressions composed more than 240 nodes before fallback. Four isolated
mutations were caught: removing the metadata type guard, removing
description normalization, accepting YAML aliases, and removing the
composition depth limit. Seven additional mutations pin strict delimiter
recognition, use of the parsed body, body whitespace, retention of
invalid memory text, and the fallback at each actual Claude Code,
Hermes, and installed-skill reader. All were caught, and sources were
restored afterward.
Windows, Python 3.12: the registry and import suites excluding the
POSIX-only Hermes file passed 181 cases during the boundary and memory
follow-up; focused shared-reader, boundary, memory-retention, and depth
cases passed 10, and the final body-whitespace matrix passed 4. The
wider Windows selection cannot collect the existing Hermes tests because
they call `os.geteuid()` at import.
Checks passed:
```text
uv run --frozen pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen --all-extras ty check raven/utils/text.py raven/memory_engine/skill_local/registry.py raven/importer/skills/claude_code.py raven/importer/skills/hermes.py raven/importer/skills/installer.py
uv run --frozen lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
All 10 import contracts kept. Full repository tests and native macOS
were not rerun. The skills README records the parsing rules and limits.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Valid YAML follows YAML scalar/comment semantics, which can differ from
literal line reading. Multiline requirements are now honored, and longer
descriptions can change skill retrieval. SKILL importers use the
registry's guarded line fallback on invalid or oversized frontmatter.
Memory-note imports preserve the complete original text when the header
cannot be parsed; valid YAML metadata keeps its existing interpretation.
Aliases and excessive nesting remain text under that fallback. No stored
format is migrated.
Rollback: revert the squash commit.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
ACP replies and live output need the same message boundaries. A steer
arriving during a report must not drop its earlier half, and a held
prompt's heartbeat must not split that report. Return the last nonblank
message while retaining narration in the transcript.
- A tool opening, terminal or status-less tool update, or plan opening
ends a message. Updates marked `pending` or `in_progress` do not;
Raven's held-prompt heartbeat can arrive mid-report.
- A steer stays inside its message with one separator. That separator
spends the message's budget when it is inside returned text; a separator
between messages does not.
- Leading whitespace remains visible but spends no capped-message budget
because `reply` strips it. Blank chunks and repeated steers before the
first nonblank text no longer silently truncate a reply that fits.
Whitespace inside substantive message text still counts.
- Preserve the distinct closing transcript row and document the
intentional report/save/sign-off behavior. Code comments and the ACP
parsing design name both nonterminal statuses explicitly.
## 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
Linux, Python 3.12, after rebase onto current main:
```text
uv run --frozen --all-extras pytest tests/test_subagent_acp.py tests/test_acp_methods.py tests/test_subagent_turn_rows.py tests/test_subagent_history.py tests/test_rpc_dag.py tests/test_rpc_subagent_calls.py tests/test_subagent_openai_steps.py tests/test_subagent_openai_backend.py -q -x --tb=short
```
618 passed. Coverage includes the real held-prompt heartbeat, tool/plan
boundaries, persisted replies, transcript rows, and downstream DAG
consumers.
Native Windows, Python 3.12:
```text
uv run --frozen pytest tests/test_subagent_acp.py -k "blank_prefixes or steered_message or steer_inside or a_steer_sets" -n 0 -q -x --tb=short
```
23 passed. Nine blank-prefix cases failed before the fix; the final
matrix also covers prefixes after a tool boundary and explicitly
preserves visible whitespace. Four isolated mutations were caught:
charging stripped whitespace, treating every chunk as leading, ending
the leading-prefix state on a blank chunk, and dropping visible leading
whitespace. Sources were restored after each run.
Checks passed:
```text
uv run --frozen pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen ty check raven/acp_client/acp_agent.py raven/agent/subagent/backends/base.py raven/agent/subagent/history.py
uv run --frozen lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
All 10 import contracts kept. Full repository tests, native macOS, and
the TUI suite were not rerun for this follow-up. The full ACP subprocess
selection ran on Linux; Windows verification covers the collector
directly.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
ACP callers receive the last nonblank message, so a report followed by a
save step and "Saved." returns the sign-off; the earlier report remains
in the transcript. Leading display-only whitespace and separators
between messages can make the raw stream longer than the
returned-message cap. Internal separators and substantive text remain
capped together. No stored format or configuration changes.
Rollback: revert the squash commit.
## Related Issues
#889
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
A stale `serve.json` can name a PID recycled to an unrelated process.
Liveness alone then prevents `raven web` from starting and lets `raven
web --stop` signal the wrong process. Check the instance lock and the
recorded process's command line before treating that PID as a Raven
resident.
- Preserve resident, foreign, and unknown identities. An unavailable
argv probe keeps a live process's record and prevents duplicate startup;
stopping requires positive identity evidence.
- Read Linux argv directly from `/proc/<pid>/cmdline`, retaining
argument boundaries when rendering spaces. Fall back to untruncated
GNU/BSD `ps -ww`; Windows uses CIM. Decoding uses UTF-8 with
replacement. Recognize module and console-script launches of `serve`,
`web`, and `gateway`.
- Examine every console-script candidate. An earlier directory such as
`Raven copy` or a Windows profile named `Raven Smith` no longer hides
the actual executable and causes removal of a live resident's record.
- Return exit 1 when any resident stop is refused or fails, including
partial stops. The CLI no longer reports "nothing to stop" after
retaining live records. Unknown-identity refusals name the exact
serve.json, web.json, or viewer.pid record. Restore process access, or
remove that record only after confirming it is stale; the warning no
longer suggests signalling an unverified PID.
- Share the platform reader with the tracing viewer. Recognize `nodejs`
and versioned Node names as well as `node`/`node.exe`. An unreadable
live viewer keeps its record, cannot be signalled, and prevents a second
viewer from starting; a dead or proven foreign process can still be
cleared. Recognize unquoted spaced executable paths from POSIX ps as
well as quoted paths.
## 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
Linux, Python 3.12, after rebasing onto current main:
```text
uv run --frozen --all-extras pytest tests/test_cli_serve_commands.py tests/test_utils_processes.py tests/test_cli_tracing_commands.py tests/test_cli_gateway_commands.py tests/test_cli_gateway_health.py tests/test_cli_gateway_page.py tests/test_rpc_serve_control.py -q -x --tb=short
```
Result: 328 passed, 1 skipped (the native Windows CIM case), using the
default four workers. The live procfs regression now waits for a bounded
child readiness signal before its single identity assertion, eliminating
the transient empty-cmdline startup race reported in review. The
container uses an init process to reap children from the real
process-group tests.
A follow-up CI run exposed two assertions that assumed Rich would not
wrap viewer.pid inside a long path. The assertions now tolerate display
line breaks. Re-running the entire tracing CLI test file with the
CI-shaped temporary path
(`--basetemp=/tmp/pytest-of-runner/pytest-0/popen-gw3`) passed all 40
tests.
Native Windows, Python 3.12:
```text
uv run --frozen pytest tests/test_cli_serve_commands.py::TestAnUnreadableIdentity tests/test_cli_serve_commands.py::TestARecycledPid tests/test_cli_serve_commands.py::TestAStopThatLosesItsTarget tests/test_cli_serve_commands.py::test_web_stop_reports_a_refused_or_partial_stop tests/test_cli_serve_commands.py::test_a_resident_below_a_raven_named_directory_keeps_its_record tests/test_utils_processes.py tests/test_cli_tracing_commands.py -n 0 -q -x --tb=short
```
Result: 102 passed, 7 Linux/POSIX-only skips. The Linux selection
includes a real child identified with ps absent from PATH. Tests force
the ps fallback when measuring its behavior, pin lowercase Raven
directories and uppercase executable names separately, and drive the
public viewer stop for an unquoted spaced Node path. Both new
spaced-path regressions failed before the viewer fix.
Four additional isolated mutations were caught: skipping procfs,
dropping the ps fallback, restoring first-match resident parsing while
removing case-insensitivity, and truncating the Node path at its first
space. The sources were restored and compared with the committed Git
blobs.
Additional checks passed:
```text
uv run --frozen pre-commit run --from-ref origin/main --to-ref HEAD
uv run --frozen --all-extras ty check raven/utils/processes.py raven/cli/serve_commands.py raven/cli/tracing_commands.py
uv run --frozen --all-extras lint-imports
uv run --frozen python scripts/check_commit_messages.py origin/main..HEAD
commitlint --from origin/main --to HEAD
uv run --frozen python scripts/check_source_language.py origin/main..HEAD
uv run --frozen python scripts/check_large_files.py origin/main..HEAD
git diff --check origin/main...HEAD
```
Import-linter kept all 10 contracts. The full repository suite and
native macOS were not rerun locally. No new command, setting, or visual
UI requires a screenshot or user guide; the affected code contracts and
this description are updated.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
A live process with an unreadable identity deliberately blocks
replacement and cannot be stopped through these commands. Restore the
process reader, or confirm the state record is stale before removing the
exact file named by the command. Scripts now receive failure for refused
or incomplete stops instead of a misleading success. Process recognition
remains a command-line heuristic, and the check and signal do not hold a
single OS process handle; this does not eliminate PID-reuse races.
Rollback: revert the squash commit, restoring the previous PID-based
behavior and its recycled-PID risk.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## Summary
Stored Windows launch commands were parsed with POSIX rules, which
removed backslashes from unquoted interpreter and launcher paths. Launch
consumers now share platform-aware parsing and quoting, while retaining
compatibility with single-quoted absolute paths saved by older callers.
- Read legacy single-quoted drive, UNC, and absolute POSIX path tokens
on Windows, including path values after `=` and the quote concatenation
emitted for apostrophes inside a path. Decode only that token so
neighboring native Windows arguments keep their backslashes and literal
apostrophes. Launch and readiness use the same compatibility decoder.
- Preserve quoted paths in discovery and stale-row checks. Escaped
quotes, CR/LF separators on POSIX, and arguments made only of
backslashes no longer hide or merge a launcher path.
- Share substitution across discovery, registration, scaffold smoke
checks, generated installers, and all five shipped installers. Older
Raven versions without the resolver refuse unsupported spaced command
paths before registration, while keeping plain paths and separately
passed working directories supported.
- Quote Raven's own ACP executable and forwarded config path for the
launch platform. Resolve bare programs on the child's PATH in directory
order, preferring executables within each directory. ACP may resolve
configured batch shims; prompt-bearing CLI and Kimi calls retain their
lookup restriction.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Checked on native Windows using an existing uv environment, with the
source imported from the reviewed checkout and `PYTHONUTF8=1`.
```text
uv run --no-sync python -m pytest tests/test_utils_commands.py tests/test_subagent_vendored_agents.py tests/test_subagent_builtin_agents.py tests/test_subagent_registry.py tests/test_subagent_third_party.py::test_cli_backend_preserves_stored_windows_path_quotes tests/test_subagent_host_env.py::test_acp_launch_preserves_stored_windows_path_quotes tests/test_subagent_probe.py::test_windows_probes_find_a_legacy_single_quoted_program -q -x -n 0
```
Result: 292 passed. This covers a real CLI child launched through the
backend, ACP spawn arguments, CLI/ACP availability probes, and
existing/missing launcher checks, with both legacy and native quoting
controls.
The final 25 added cases were also run in an isolated process with the
previously published parser: 12 failed and 13 passed. Four isolated
mutations were caught: disabling compatibility (8 failures), removing
the launch quote guard (1), removing the readiness quote guard (1), and
using POSIX parsing for the entire Windows command (15). A seeded
50,000-case check through the native producer and both consumers
reported no argv or readiness-token mismatches.
Whole-branch checks:
```powershell
$prFiles = @(git diff --name-only origin/main...HEAD -- '*.py')
uv run --no-sync ruff check @prFiles
uv run --no-sync ruff format --check @prFiles
$production = @($prFiles | Where-Object { $_ -notlike 'tests/*' })
uv run --no-sync ty check @production
uv run --no-sync lint-imports
uv run --no-sync pre-commit run --from-ref origin/main --to-ref HEAD
uv run --no-sync python scripts/check_commit_messages.py origin/main..HEAD
uv run --no-sync python scripts/check_source_language.py origin/main...HEAD
uv run --no-sync python scripts/check_large_files.py origin/main...HEAD
git diff --check origin/main...HEAD
```
All passed: 24 Python files passed Ruff checks; production type checks
passed; all 10 import contracts were kept. The pinned commitlint CLI
also passed over the full branch range. The final documentation-only
follow-up changes no executable behavior.
Limits: a broader Windows selection stopped after 283 passing tests at
`test_cli_probe_reports_the_resolved_absolute_path`, whose bare POSIX
shell fixture is not resolved as a Windows executable. This is not
counted as a passing suite. The ACP regression checks the arguments
delivered to process creation; it does not claim to verify the existing
POSIX-only process-group shutdown path on Windows. The local Docker
daemon was unavailable, so no new local Linux or macOS run is claimed.
The full repository suite and a live WebUI dispatch were not run locally
for this revision.
The pre-submit sweep covered the complete branch diff, all command
producers and consumers, native/legacy quoting boundaries, installer
fallbacks, failure paths, test strength, layer contracts, repository
gates, and these disclosed verification limits.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No screenshot update applies. Parser docstrings describe the legacy-path
compatibility and how to preserve literal quotes.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Compatibility applies to single-quoted absolute path tokens, including
path values after `=`; it does not enable general POSIX shell syntax on
Windows. Non-path apostrophes remain literal. To preserve literal single
quotes around path-looking data, quote the entire argument with native
double quotes. Existing stored path tokens are read compatibly without
rewriting configuration; newly generated commands keep native quoting.
POSIX launch parsing is unchanged. Readiness preserves foreign
absolute-path spellings and checks launcher existence; it is not a
general command validator. Older installers reject paths their Raven
version cannot represent before changing the roster.
ACP batch shims execute configured server arguments through cmd.exe.
Prompt-bearing CLI and Kimi calls do not opt into batch lookup. A CLI
agent installed only as an npm shim still needs an explicit executable
path. Reverting the squash commit restores the prior behavior.
## Related Issues
#880
---------
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
Co-authored-by: Codex <noreply@openai.com>
## Summary
After a conversation switches its model, a direct chat with a built-in
sub-agent
instance in that conversation still ran on the default binding while the
main agent
and the sub-agents it spawned used the session's choice; with a dead
default
credential the direct chat alone failed with the provider's 401. The
spawn-side
instance of the same miss is #281, fixed by #282 and #284; this is its
direct-chat
entry point.
`run_turn` takes `req.conversation` as the session key. For a direct
chat that value
is the instance's lane, `{session}#{agent}/{handle}` (`direct_lane`),
and
`binding_for_session` looks up `_session_bindings` by that exact key. A
session's
switch is stored under the bare session key (the TUI's `/model` and the
web page's
picker both send the session id), so the lookup always missed and the
turn fell back
to the default binding.
The fix wraps the `binding_for_session` call in `session_of` (imported
through
`raven.agent.loop._shared`, which re-exports it from
`raven.spine.turn`), the same
normalization the direct-chat record path (`turn_path.py:3065`) and the
rpc spine
(`rpc/spine.py:360`) already apply to lanes. A main-agent lane carries
no `#`
separator, so `session_of` is the identity there and every other entry
resolves
unchanged. A red-to-green test switches a session's binding and asserts
that a
direct-lane turn runs on it
(`test_a_direct_chat_turn_runs_on_its_session_model`).
Checked and deliberately not changed, same path:
- `_resolve_playbook_turn` treats a `direct_target` as an explicit no-op
(`wiring.py:879-880`) -- no binding lookup there to normalize.
- `_release_dag_runs` is guarded off for direct chats on purpose: a
direct chat owns
no graph, so its end must not release the main turn's runs
(`main.py:1001-1006`).
- persona and tools-scope lookups on the same path are separate behavior
questions,
not this binding miss.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
All commands run with `timeout`, on this branch's head `9c5a0c55` with a
clean tree,
dependencies via `uv run --frozen --all-extras`.
- Red first: `timeout 420 uv run --frozen --all-extras pytest
tests/test_agent_loop_session_model.py::test_a_direct_chat_turn_runs_on_its_session_model
-x -q` -> 1 failed (`assert ['boot/model'] == ['vendor-a/model']`).
- Green, file: `timeout 300 uv run --frozen --all-extras pytest
tests/test_agent_loop_session_model.py -q` -> 36 passed.
- Related subset: `timeout 420 uv run --frozen --all-extras pytest
tests/test_subagent_direct_chat.py tests/test_agent_loop_model_switch.py
tests/test_rpc_config.py tests/test_rpc_turn_send.py
tests/test_rpc_spine.py -q` -> 280 passed.
- Full suite, stop on first failure: `timeout 600 uv run --frozen
--all-extras pytest tests -q -x --ignore=tests/manual` -> 6614 passed, 1
failed (`test_a2a_interop`; reproduced identical red on the clean tree
via `git stash`, pre-existing).
- Full suite, no `-x`, excluding that pre-existing failure: 27862
passed, 116 skipped, 3 failed (`test_rpc_files` libreoffice /
`test_simulation_scenario` / `test_simulation_suite`; each reproduced
identical red on the clean tree via `git stash`, pre-existing
environment failures).
- Lint: `timeout 120 uvx ruff@latest check raven/` -> All checks passed;
`timeout 120 uv run --frozen --all-extras ruff check tests/ raven/` and
`ruff format --check` over the touched files -> pass.
- Commit gates: `npx @commitlint/cli --config commitlint.config.cjs`
over the HEAD message -> exit 0; character-by-character ASCII scan of
the commit message -> OK.
Not run: the build/tui/bridge segments of `make ci` (pure Python change;
not run, so not claimed).
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs change: no document quotes where `run_turn` resolves its binding
from.
## Risk
User-visible change is confined to direct chats with built-in instances:
they now run
on their session's binding instead of the default. Nothing outside that
one lookup
moves; the main agent, spawned sub-agents, ACP and CLI agents are
untouched.
- [x] Security impact considered
The change re-points one lookup key; no new content, route or path is
introduced.
- [x] Backward compatibility considered
`session_of` is the identity on every key without a lane separator, so
main-agent
turns and every stored session key resolve exactly as before.
Instance-level model
overrides are a different layer and are not touched.
- [x] Rollback path is clear for risky changes
Rollback is a revert of the single commit; nothing persists and no
format changes.
## Related Issues
Fixes#888
Related: #281 (spawn-side instance of the same miss, fixed by #282 and
#284).
Co-authored-by: Claude (GLM-5.3-Flash) <noreply@anthropic.com>
## Summary
- New `raven/mcp/paging.py` walks a paginated list verb page by page
with `params=PaginatedRequestParams(cursor=...)`, stopping on an absent
or a repeated cursor (the rule #825 introduced for `tools/list`). The
public surface is one typed walker per verb (walk_tools / walk_resources
/ walk_resource_templates / walk_prompts), so the items a caller loops
over carry their real SDK type rather than the Any a session yields at
these call sites; the page shape stays behind one private engine.
- The three remaining verbs now walk through it: `resources/list` and
`resources/templates/list` in `raven/mcp/resources.py`, and
`prompts/list` in `raven/mcp/prompts.py`. Each site keeps its existing
`_with_timeout` around the whole walk, so a server that never stops
paging fails visibly instead of stalling the turn.
- The `tools/list` loop from #825 in `raven/mcp/client.py` collapses
onto the same helper, so all four verbs share one implementation.
- Design note, for the author to settle: the module exposes one typed
walker per verb over a single private engine, rather than one generic
helper. Typed returns give the items their real SDK type (IDE
completion, and future-proof the day an attribute rule switches on);
under the repo's current ty config, a call-correctness gate with
unresolved-attribute off, both shapes pass identically, and collapsing
the wrappers into one generic helper is a small change if that reads
better.
- Single-page behaviour is unchanged: existing tests pass without
modification beyond the fakes accepting the `params` argument the walker
always passes.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally: `uv run pytest
tests/test_mcp_resources.py tests/test_mcp_prompts.py
tests/test_mcp_client.py tests/test_mcp_manager.py` -> 88 passed,
including four new tests (multi-page resources, multi-page templates,
repeated cursor, multi-page prompts)
- [x] The new tests fail on current main: stashing only the `raven/`
changes and running them -> 4 failed; restoring the fix -> pass
- [x] Relevant lint / type checks pass locally: `ruff check` + `ruff
format --check` on the touched files; `ty check` at the pre-change
baseline (18 platform-only diagnostics on Windows, no new);
`lint-imports` -> 10 contracts kept, 0 broken
- [ ] User-facing docs or screenshots are updated when needed: not
needed, no user-visible copy changes
## Risk
- [x] Security impact considered: reads more of what a server already
serves; no new inputs, credentials or surfaces
- [x] Backward compatibility considered: single-page servers answer one
request exactly as before, and the repeated-cursor stop rule is the one
#825 already shipped for tools
- [x] Rollback path is clear: plain revert restores the single-page
behaviour
## Related Issues
Fixes#855
## Summary
With a `MemoryBackend` plugin wired, memory lives in the plugin's store
and reaches the
turn as the `# Memory` section. The identity block still named two files
under agent home,
so "remember this" became an `edit_file` against
`user_memory/profile/user.md`. On a
non-interactive turn that write is refused at the ask tier, and the
agent reported the
refusal as the memory system having failed -- while the backend had
already stored the
turn and recalled it in the next session.
`identity_text` takes a `has_memory_backend` flag, threaded from the one
place each caller
already holds the backend: `build_context_engine`, and `AgentLoop` for
the
token-estimation prompt in `ContextBuilder`, which must render what the
turn renders.
With a backend the two file lines become one:
```
- Agent home: <home> -- your own skills, not a place for user artifacts.
- Memory is not yours to write: what is relevant is recalled into the `# Memory`
section each turn, and the host persists the conversation after it ends. You
cannot observe that write, so never report it to the user as done or as failed.
- Custom skills: <home>/skills/{skill-name}/SKILL.md
```
Three clauses, three jobs. Do not write it. It is being saved, so stop
looking for a place
to put it. You cannot see that write, so do not narrate it.
The last clause is the other half of the same defect, and the third item
issue 440 asks to
separate. `backend.store` is dispatched after the turn ends, so a claim
either way is one
the agent never checked -- and whatever it claims is extracted into
long-term memory next
turn as if it were an observation of the system. The issue's own repro
produced exactly
that: an episode titled `Memory Save Failure for Green Brompton Bike
'Pickle' Noted on
2026-09-16`, whose content was right and whose narrative was wrong.
Filtering that
server-side is not available from here, so the prompt is where it is
addressed.
Without a backend the rendered prompt is unchanged, byte for byte.
Whether the episodic
log earns its line at all is issue 122's question, and answering it on
this branch would
couple the two.
The approach is AmirF194's, from the closed PR #216. That branch cannot
be reopened: it
predates the history linearization, so it shares no merge base with
`main`
(`git merge-tree` refuses unrelated histories), its six files no longer
apply, and it did
not allow maintainer edits. It is reimplemented here against current
`main`, with the
author credited as co-author on the commit.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on this branch's head, rebased onto `main` at c3d282130, Python
3.12, `--extra dev`.
- `pytest` over the 17 test files that construct `ContextBuilder`,
`IdentitySegmentBuilder`,
`build_context_engine` or call `identity_text` (the `git grep -l` list):
756 passed, 0 failed.
`SERPER_API_KEY` is unset for the run; with it set,
`test_agents_code_launcher.py::test_the_products_tool_face_is_the_forks_config_intent_minus_the_ledger`
fails on an extra `web_search` in the tool face, on this branch and on
the base alike.
- The three new tests were each watched failing without the change, by
neutering the
behaviour in place rather than the signature, then restoring the file
and confirming it
byte-identical by checksum:
- forcing the backend branch off reddens
`test_identity_with_a_backend_names_no_memory_file`;
- dropping the flag from `ContextBuilder._get_identity` reddens
`test_identity_with_a_backend_matches_the_estimation_prompt`;
- `test_identity_without_a_backend_still_names_both_memory_files` pins
the unchanged half.
- The no-backend claim is measured, not argued: the whole identity block
rendered from the
base and from this head is 3341 bytes on both sides and `diff` is empty.
- `make lint-python`, `make lint-types`, `make lint-imports`, `make
check-large-files` -- all exit 0.
- `RANGE=github/main..HEAD scripts/check_source_language.py` -- exit 0.
- `commitlint --config commitlint.config.cjs` on the commit body and on
the prospective
squash header -- both exit 0.
Driven against a live EverOS after this description was first written.
All three
symptoms issue 440 describes reproduce on the merge base and none
reproduce here: on
`main` turn 1 calls `read_file` then `edit_file` on
`user_memory/profile/user.md` and
grows it to 897 bytes, at the ask tier that write is refused and the
agent reports the
save as failed, and EverOS extracts that false report into four durable
memory entries.
On this branch turn 1 makes no tool call, agent home is untouched, and
the same grep over
the store returns nothing. Both sides recall the fact in a fresh
session. Full method,
verbatim output and teardown in a comment on this PR.
One run per cell, not a distribution. The host still dumps `user.md`
into `# Memory` with
a backend wired, which is unchanged here and out of scope below.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
No docs change: the only user-facing text is the system prompt itself,
and no document
quotes this block.
## Risk
User-visible change is confined to installs that have a memory backend
wired. There, three
prompt lines become three different ones; nothing else in the prompt,
and no behaviour
outside prompt assembly, moves. Installs without a backend render a
byte-identical prompt,
which is the measurement above.
`has_memory_backend` defaults to `False` on all four signatures it is
added to, so every
call site not updated here renders what it rendered before. The three
updated call sites
are the only ones that hold a backend.
Rollback is a revert of the single commit. Nothing persists and no
format changes.
Checked and deliberately not changed:
- `MemorySegmentBuilder` still calls `get_memory_context()`
unconditionally, so `user.md`
content reaches `# Memory` with a backend wired. Turning that off is the
question of
whether two memory mechanisms should coexist, which is larger than this
issue and which
four comparable systems answer by keeping both.
- The episodic log line, under the default no-backend configuration. It
belongs to issue 122.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#440 -- items 1 and 3 of the three the issue asks to separate,
both reproduced on
the merge base and verified gone here. Item 2 landed in #544.
#122 -- untouched, deliberately.
---------
Co-authored-by: gloryfromca <23442919+gloryfromca@users.noreply.github.com>
Co-authored-by: Amir Fathi <amirfathi.me@gmail.com>
Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
## 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>
## 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
## 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>
## Summary
An ACP sub-agent's result joined every `agent_message_chunk` of its
turn, so the notes a model writes beside its tool calls ("Three
confirmed. Now the research repos.", "All 10 repos confirmed. Now
verifying benchmark numbers and ecosystem framing.") reached the host as
part of the answer: in a spawn announcement's `Result:`, in a DAG node's
`out.md` (what a later task reads through `{{ ref:@nodes/<id>.out.md
}}`, and what a terminal node's output inlines), and in a direct chat's
record. The in-process raven loop already returned only its final
response, and the openai lane returns one message; the acp lane was the
one that joined.
The collector's new `reply` is the run's last message: what it said
after its last tool call or steer, which is the existing `closing_text`.
A turn that ended on a step said nothing after it, so its reply is the
message before that step: still one message, and not an empty result for
a run that finished its work. Whitespace after the last step counts as
nothing said. The narration stays where it already was, on the step rows
of the run's transcript and in the live stream a direct chat renders.
Two consequences ride with it. The live stream's `maxOutputChars` budget
is now renewed per message: spent across the turn, narration would use
it up and cut the report short on screen with no notice, because the
reply itself fits and is never capped. The break between two messages is
raven's own text and goes through the unbounded delta callback, as the
partial-turn notice does, so it spends neither message's budget. And the
span's `answer_chars` measures the reply, as the cli lane's
`len(output)` does.
Existing tests whose meaning changed, on purpose: three assertions
encoded the old rule that the caller receiving the run's answer wants
all of it, and are flipped
(`test_two_messages_in_one_turn_are_kept_apart`,
`test_narration_lands_on_the_step_it_preceded`,
`test_a_steer_reaches_the_running_turn_and_is_written_where_it_was_said`);
the answer-row test gains an `out.md` assertion. A second commit
corrects texts the change falsified: two RPC readers and three test
docstrings that said the output repeats the narration, and a stream-cap
test renamed for the per-message cap it checks
(`test_a_streamed_message_is_capped_like_the_reply`). `CONTEXT.md`'s
Closing Message and Reply Streaming entries are rewritten to the new
rule.
Left as is, deliberately:
- A turn's thoughts and tool calls were never in the reply, and still
are not.
- Raven-Research's research-trail appendix is appended to its final
message, so it stays in the reply. Whether it should is a separate
decision, made in that agent's `finalShape.processAppendix`.
- `closing.md` now repeats `out.md` in the common case. It is left in
place, since removing it reaches the two context reads and the RPC.
- For a turn that ended on a step, the two context reads still draw
`out.md` as the answer row while the instance log draws none. That
predates this change, which shrinks the repeat from every message to
one.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- Red before green: the seven new or flipped tests that hold the rule
failed first for the expected reason (the joined reply returned,
`answer_chars` 27 against 13, the live stream cut to `let me look.` and
one character of the report), then passed. The blank-burst test was
checked by mutation instead: without its whitespace guard it fails with
`'' == 'found it.'`.
- Single-construct mutants on `raven/acp_client/acp_agent.py`, each run
against `tests/test_subagent_acp.py` and each killed: ignoring the cap
(1 failed), not renewing it per message (1), counting the joined text in
the span (1), dropping the trailing-step fallback (2), returning the
joined text (7).
- Review round one: the break between messages spent the renewed budget,
so at a cap of exactly the reply's length the screen showed `it is a
rep` while the reply was `it is a repo.` (caps 13, 14 and 15 lost two
characters, one, and none). The per-message test now runs at that cap,
and failed with `it is a rep` before the fix. Mutants on the fix, each
killed: counting the break against the budget (1 failed), not renewing
the budget (1), not streaming the break (2), ignoring the cap (1).
- `uv run --frozen --all-extras --python 3.12 pytest -q -p no:randomly
tests/test_subagent_acp.py tests/test_rpc_dag.py
tests/test_rpc_subagent_calls.py tests/test_subagent_history.py`: 406
passed.
- `uv run --frozen --python 3.12 --all-extras pytest -q -p no:randomly`
(the `make test-python` command) on the branch head: 27705 passed, 8
failed, 119 skipped. Seven of the failing IDs fail identically on
`origin/main`, run the same day through the same interpreter, so none is
introduced: five proxy tests in `tests/test_config_update_providers.py`,
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`,
and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`.
The eighth,
`tests/test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`,
passed when re-run alone; across the three full runs of this branch it
failed in two and passed in one.
- Replay: a recorded Raven-Research turn (ACP frame journal, 2026-09-19;
10 message chunks, 26 tool calls, 827 thought chunks) fed through the
new collector returns 14,814 chars where the old rule returned 15,565.
The 749 dropped are exactly the eight progress notes, and the reply
equals `closing_text`.
- Gates: `scripts/check_commit_messages.py`,
`scripts/check_large_files.py` and `scripts/check_source_language.py`
over `origin/main..HEAD`, `ruff check` and `ruff format --check` over
the `make lint-python` targets, `lint-imports` (10 kept, 0 broken), and
`ty check` over the `make lint-types` targets: 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 docs describe what a sub-agent's result contains;
`CONTEXT.md` is updated.
## Risk
What changes for a reader: the host's spawn announcement, a DAG node's
`out.md` (and so `{{ ref }}` and terminal outputs downstream), and a
direct chat's record now carry only the agent's last message. An agent
that put a needed fact only in a progress note, and not in its final
message, no longer hands that fact to the host; the full turn is still
in the run's transcript and frame journal. Every ACP agent is affected:
the five shipped agents and any third-party one.
The live stream of a direct chat can now show more than `maxOutputChars`
in total, at most that much per message; every streamed message is also
stored on the transcript.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Security: the reply is one message of the same turn the joined text
carried, and it travels the same routes, so no new kind of content
reaches the host and no path to a secret changes. Rollback: revert the
squash commit; nothing on disk depends on the new shape.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## 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>
## Summary
Two costs in `HistoryTrimmer.trim` grew with the number of tool-call
groups in the session. `trim` runs synchronously inside context
assembly, on the event loop, so on a long session the whole process
waited on them.
Choosing a budget drop (`_choose_drop`) re-closed the selection for
every candidate group before taking the first clean one, and each
re-closing (`canonical_ids`) is a pass over the session, so every drop
cost one pass per group. Candidates are now re-closed one at a time, in
the order they could go -- unprotected groups in selection order, then
protected ones -- and the search stops at the first clean one. Which
group goes is unchanged, including the last resort that takes the first
candidate when none goes cleanly.
`tool_group`, which pairs by position since #885, rebuilt that pairing
for the whole session on every call, and the closing sweep
(`_offenders`) asks it for the group of every call in the selection, so
even a trim that drops nothing cost one pass per call group; this was
raised in the review of #885. `trim` now builds the group index once
(`_group_index`) and hands it to the drop choice and the sweep.
`tool_group` answers from the index and builds it only when a caller
passes none, so pairing still has a single source. Each group is frozen
once and shared by its members, so the index stays linear in memory
however many results one parallel call has.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
- `uv run --frozen --python 3.12 --all-extras pytest -q
tests/test_history_trimmer.py tests/test_curator_context_engine.py`: 38
passed.
- Each new test was seen failing before its change: the drop choice
re-closed 356 times where 11 are expected (one for the selection, then
one per drop); a trim that drops nothing paired the session 21 times
with 20 call groups against 11 times with 10; and behind a protected
head of six tool turns each drop paired the session more often than
behind two. The last two also fail when the index is left out of the
drop choice or out of the sweep. A fourth test caught the index keeping
a separate copy of a group for every member: 21 copies of one 20-call
group.
- Differential tests against the previous implementations, ids reused
across turns included: the lazy drop choice against the eager one on
`main`, 8000 random `_choose_drop` calls and 2000 whole trims, 0
differences (a variant with the tiers swapped produced 6230); the
index-backed `tool_group` against the per-call one, 315360 lookups and
5000 whole trims, 0 differences, and another 31628 lookups on the final
code, 0 differences.
- Memory of the index: one assistant with 1,000 parallel calls keeps a
single shared copy of its group, peaking at 0.14 MiB while the index is
built; a copy per member would hold 1,001 copies and peak at 31.6 MiB.
- Mutation of the drop choice: four of five mutants turn a test red (the
eager form restored; protected groups never tried; protected groups
tried first; the anchor check skipped). The fifth, a last resort that
keeps the last unclean candidate instead of the first, stays green and
is equivalent for `trim`, the only caller: the selection `trim` passes
always opens on a user message and only the group holding that message
can fail the anchor check, so the last resort never has two candidates.
Under it, 0 of 2000 whole trims differ; its 129 differences in 8000
direct calls all come from selections `trim` never builds.
- Full suite, `uv run --frozen --python 3.12 --all-extras pytest -q`:
27710 passed, 3 failed, 119 skipped. Two of the failures,
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`,
fail the same way on an untouched copy of the base on this machine (an
`npm` elsewhere on PATH, and root reading a mode-000 file). The third,
`tests/test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`,
is intermittent on this machine and passed 10 of 10 when run alone on
the same tree; an instrumented failing run of it makes no call into the
trimmer.
- `ruff check`, `ruff format --check`, `lint-imports` (10 contracts
kept) and `ty check` pass; `scripts/check_commit_messages.py`,
`scripts/check_source_language.py`, `scripts/check_large_files.py` and
`commitlint` pass over the range.
- Cost of one trim, message-count estimator, median of three, same
messages kept in every column:
| Trim | before #885 | main | this PR |
| --- | --- | --- | --- |
| 100 of 300 messages dropped | 1,142 ms | 850 ms | 9.6 ms |
| 100 of 1,200 messages dropped | 23,777 ms | 18,358 ms | 42.7 ms |
| nothing dropped, 2,000 messages | 66.2 ms | 124.3 ms | 2.2 ms |
| nothing dropped, 10,000 messages | 1,694 ms | 3,511 ms | 12.7 ms |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none
apply: no user-facing text changes)
## Risk
- Which messages a trim keeps does not change, which the differentials
above cover for whole trims; only the time a trim holds the event loop
does.
- `tool_group` gains an optional `index` argument; two-argument calls
behave as before.
- No new input, surface, setting or dependency.
- Rollback: revert the squash commit; nothing persistent is involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## 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>
## 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>
## Summary
`HistoryTrimmer.trim` can loop forever when a tool-call id is reused
within one session. The budget loop drops a tool call and its results as
one group, then re-closes the selection, and the two halves paired a
result with its call differently: closure (`canonical_ids`) took the
last assistant that declared the id, while the group (`tool_group`) took
every later result carrying one of the call's ids. Once a later turn
reused an id, re-closing put back the group the drop had just removed,
the selection stopped shrinking, and the loop never exited. `trim` runs
synchronously inside context assembly (the segments are awaited with
`asyncio.gather` in `raven/context_engine/assembler.py`), so the spin
holds the event loop of the whole process, not one conversation.
Both now derive from one positional map, `_tool_parents`: a result
answers the nearest earlier assistant that declared its id. Groups then
partition the session, closure only adds whole groups that still have a
selected member, and every drop strictly shrinks the selection. Sessions
whose ids are unique pair exactly as before.
The closing sweep (`_offenders`) also asks `tool_group` once per group
rather than once per selected message: every member gets the same group
back, and each answer is a pass over the session.
How reachable the trigger is: nothing makes an id unique across a
session. The streaming accumulator keeps whatever id the upstream sent
(`raven/providers/streaming.py`, then `openai_tool_call`, then the
session, with no remapping), and the Anthropic parser falls back to a
fixed `toolu_unknown` for a tool-use entry that carries no id. No
production occurrence has been observed; the path is reachable, not
measured.
Left as they are, both older than this change: an assistant whose result
never reached the session still ships with an unanswered call (a
cancelled turn already gets a synthesized `[interrupted]` result), and a
tool exchange whose ids are empty strings is still swept as unpaired.
A companion PR makes the drop choice lazy; the two change different
methods and apply in either order.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --python 3.12 --all-extras pytest -q
tests/test_history_trimmer.py tests/test_curator_context_engine.py`: 34
passed.
- Each new behaviour test was seen failing before its code existed:
`tool_group` returned `{1, 2, 8}` where `{1, 2}` is right; the reused-id
trim stopped shrinking (its bounded estimator raised after 45
estimates); the closing sweep asked 40 times over 20 groups. A fourth
test, on the order of the two closure steps, passes on the old code as
well; swapping the steps leaves sibling results out, and it goes red.
- Mutation at the head: 8 mutants (first declaration wins; the closure
steps swapped, or either one removed; a group without its results; the
old closure alone; the old group alone; the sweep skip removed) each
turn at least one test red, the group-without-results one by failing the
group test and then hanging a later trim test; the unmutated control is
14 of 14 green.
- Differential test of the closing sweep against the per-message
version: 20000 random selections and 5000 whole trims, ids reused across
turns included, 0 differences; a deliberately wrong skip produced 1728.
- Full suite, `uv run --frozen --python 3.12 --all-extras pytest -q`:
27691 passed, 3 failed, 119 skipped. Two of the failures,
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`,
fail the same way on an untouched copy of the base on this machine (an
`npm` elsewhere on PATH, and root reading a mode-000 file). The third,
`tests/test_agents_research_tools.py::test_a_thin_dataset_card_falls_back_to_the_metadata_the_table_needs`,
is intermittent on this machine: run alone it failed in clusters (19 of
the first 39 runs, then 0 of the next 20 in the same checkout), it
passed 40 of 40 from clean exports of this commit and of the companion's
with either environment, and an instrumented failing run made no call
into the trimmer, which it only imports with the package.
- `ruff check`, `ruff format --check`, `lint-imports` (10 contracts
kept) and `ty check` pass; `scripts/check_commit_messages.py`,
`scripts/check_source_language.py`, `scripts/check_large_files.py` and
`commitlint` pass over the range.
- Cost of one trim that has to drop 100 messages, message-count
estimator, median of three, same messages kept in every column:
| Session | main | this PR | with the companion PR |
| --- | --- | --- | --- |
| 300 messages | 1,113 ms | 847 ms | 14.9 ms |
| 1,200 messages | 22,782 ms | 17,419 ms | 98.4 ms |
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed (none
apply: no user-facing text changes)
## Risk
- Which messages a trim keeps changes only for sessions that reuse a
tool-call id, where the old code could not finish; sessions with unique
ids pair and trim exactly as before, which the differential above covers
for whole trims as well as for the sweep.
- No new input, surface, setting or dependency.
- Rollback: revert the squash commit; nothing persistent is involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#291, whose fix introduced the group drop this change corrects.
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
On the LiteLLM chat route a DeepSeek tool loop dies with a 400, "The
`reasoning_content` in the thinking mode must be passed back to the
API". DeepSeek's thinking mode requires each tool-call message to carry
`reasoning_content` when a request continues from a tool result. A step
the model took without thinking comes back with none, the assistant
message is stored without the key, and the API's own fallback
(recovering the reasoning by tool-call id) never fires, because request
assembly rewrites every tool-call id to a 9-character hash. DeepSeek
V4.1 Flash, which `deepseek-v4-flash` now routes to, returned no
reasoning on 13 of 14 simple tool-routing calls, so on this route the
failure is common rather than rare.
Requests bound for a DeepSeek model now send `reasoning_content: ""` on
each tool-call message that lacks the key or holds null. Reasoning that
is present rides unchanged, no other message gains the key, other models
are left as they were, and the stored session is not touched. The fill
sits in `LiteLLMProvider._sanitize_messages`, which both `chat()` and
`chat_stream()` use, so it covers the main loop, sub-agents and the
Curator's own tool loop. A DeepSeek model is recognised by the last
segment of its Wire Model, so one served by another provider on this
route (for example `huggingface/deepseek-ai/DeepSeek-V4-Pro`) is covered
too.
Measured against DeepSeek's API on 2026-10-09 (deepseek-flash and
deepseek-v4-pro gave the same answers), changing one thing at a time on
a continuation whose tool-call message lacks the key:
- the tool-call id DeepSeek issued: 200
- the id rewritten the way this route rewrites it: 400
- the rewritten id plus `reasoning_content: ""`: 200
- the rewritten id, with a user message after the tool result: 200
Not changed here, each its own decision:
- The Responses route, DeepSeek's default since v0.2.0, never captures
or replays reasoning. It works because call ids round-trip intact and
DeepSeek recovers the reasoning itself, which still held 40 minutes
after the call.
- The Curator's tool loop never passes its reasoning back. With this
change it no longer gets the 400, but it does not see its earlier
thought either.
- The tool-call id rewrite itself.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `uv run --frozen --python 3.12 --all-extras pytest
tests/test_litellm_provider_reasoning.py -q`: 10 passed. The three
DeepSeek tests failed before the change, each on `None != ''`.
- Mutation pass over the fix, one construct at a time (the fill, the
DeepSeek gate, the tool-call condition, the null case, `.lower()`, the
id-tail match, and the flag at each of the two call sites): 8 of 8
killed, each by the test written for it.
- After rebasing onto main, `uv run --frozen --python 3.12 --all-extras
pytest` over the LiteLLM provider, prompt-cache, agent-loop stream and
rpc model test files: 477 passed. The patch-id did not change in the
rebase.
- Full suite before the rebase, `uv run --frozen --python 3.12
--all-extras pytest -q`: 27677 passed, 7 failed, 119 skipped. The same 7
fail on an untouched base checkout with the same interpreter, so none is
introduced: five proxy tests in `tests/test_config_update_providers.py`
(that file passes 189 of 189 with the proxy variables unset), one that
sees an npm on PATH, and one that fails when run 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`
- Live, through this branch's provider: the main loop's message shape
and the Curator's, each with the key absent, continued over the chat
route on deepseek-v4-pro and deepseek-v4-flash. All four returned 200;
all four were 400 on main.
- End to end: isolated `raven agent` one-shots on
`deepseek/deepseek-v4-flash` with `protocol: chat`, with a prompt that
needs two dependent file reads. On main 2 of 3 runs died with the 400.
On this branch 6 of 6 answered correctly, and every one of the six hit a
tool-call step with empty reasoning.
- Gates: commitlint, `scripts/check_commit_messages.py`,
`scripts/check_large_files.py` and `scripts/check_source_language.py`
over `origin/main..HEAD` exit 0; `ruff check` and `ruff format --check`
over the lint targets, `lint-imports` (10 kept, 0 broken), `deptry
raven` and `ty check` are clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
The docs box is left blank: no user-facing document describes how
requests are assembled.
## Risk
- Behaviour change: on the LiteLLM chat route, a tool-call message bound
for a DeepSeek model now carries `reasoning_content: ""` when it had
none. DeepSeek's own API accepts it, measured above. Other providers
serving DeepSeek models on this route were not measured; they already
receive this field whenever the reasoning is non-empty, so only the
empty value is new to them.
- Trajectory recordings are unaffected: their spans record the caller's
messages before request assembly.
- `_sanitize_messages` keeps its old call shape; the new parameter is
keyword-only with a default.
- Rollback: revert this commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#297
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
On Windows the sub-agents page and the launches read the environment the
gateway started with, so an agent installed after it started stayed "not
on the login shell PATH" until a restart. This reads the PATH a freshly
opened terminal would get from the registry, takes it again on Check
again, Connect and Test, and starts a bare program from it.
- `login_shell_env` and `refresh_login_shell_env` both go through
`_capture_now`: the registry on Windows, the login shell elsewhere. A
refresh on Windows used to look for a login shell, find none, and keep
the first capture.
- `_capture_windows` returns raven's own environment with only `PATH`
rebuilt: the machine and user stores' `Path`, `%VAR%` references
expanded, followed by the live PATH. The stores' other values are not
copied over raven's: they are what Windows builds an environment from
(`ComSpec` and `TEMP` unexpanded, the machine's `USERNAME=SYSTEM`).
- The capture keeps the upper-case names `os.environ` has on Windows,
which is the spelling `probe._login_path` and the other readers ask for,
so an agent already on the gateway's PATH stays found beside the ones
the stores add.
- A stored reference expands with raven's own values first (they are
this logon's, and the child carries them), then user over machine for a
variable an installer added after raven started.
- `resolve_program`: CreateProcess looks a bare name up on the gateway's
own PATH and never on the env block it is handed, so on Windows the acp
launch, the cli launch and the Kimi Code ask look it up on the child's
PATH instead, by CreateProcess's own rule that a name with no extension
means `.exe`. Only an `.exe` or `.com` is put in: CreateProcess never
turns a bare name into a `.cmd` or `.bat`, and doing it here would put a
cli prompt through cmd.exe's parser.
- On Windows no shell is driven, including the Git for Windows bash that
`SHELL` can name there: its MSYS environment carries a `:`-joined POSIX
PATH and no `SystemRoot`.
Left out on purpose: splitting the command line. The probe keeps
splitting a command the way both launchers do; a Windows rule for the
probe alone (`posix=False`) keeps the quotes `shlex.quote` and a Program
Files path carry and disagrees with the launch. #864 routes the probe
and the launchers through one parser (`raven/utils/commands.py`), so the
backslash mangling of a `{PYTHON}` command is closed there. Once both
land, #864's `launch_argv` (a PATHEXT lookup on the gateway's PATH) and
`resolve_program` here want to become one lookup on the child's PATH;
whichever lands second folds them.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `python -m pytest tests/test_subagent_host_env.py
tests/test_subagent_probe.py tests/test_subagent_third_party.py
tests/test_subagent_kimi_code.py tests/test_rpc_subagents.py
tests/test_cli_agents_commands.py -q` (project venv, all extras, this
tree on `PYTHONPATH`): 620 passed, 1 skipped.
- Full suite, `python -m pytest -q` the same way: 27683 passed, 119
skipped, 8 failed. Seven fail on this host at main too: five
`test_config_update_providers.py` proxy cases that read the host's proxy
variables,
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
under root, and
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
with an npm on PATH.
- The eighth,
`test_subagent_kimi_code.py::test_a_kimi_that_does_not_know_acp_is_told_to_upgrade`,
is a load race at main as well: with the stand-in forced to exit before
the host's first `_send`, main and this branch both answer "stdin is
closed" with no remedy.
- Mutation check: 13 single-construct mutants (refresh routing, the PATH
spelling, the expansion order, the overlay, the union with the live
PATH, folding store names, matching references without case, each of the
three launch call sites, the `.exe` rule, the `.cmd` refusal, the first
capture's platform switch), each caught by the test written for it.
- Windows is simulated on Linux: a fake `winreg` holding the stock store
values (REG_EXPAND_SZ unexpanded), `os.environ` with upper-case names,
and `;` as the path separator for the probe test. Not run on a Windows
host.
- `ruff check` and `ruff format --check` over CI's targets,
`lint-imports` (10 kept, 0 broken), `ty check` on the touched modules,
and `scripts/check_large_files.py` and
`scripts/check_source_language.py` over the change: all clean.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
Windows only. On POSIX `_capture_now` is `_capture` and
`resolve_program` returns the argv it was given, so behavior matches
main. On Windows a child gets raven's environment with PATH rebuilt
registry-first, and a bare program found as an `.exe` or `.com` on that
PATH starts from there; anything else is left to CreateProcess's own
search, as before. Not changed here: a bare name that exists only as a
`.cmd` shim (npx and other npm installs) still does not start on
Windows, and a `%PATH%` reference inside a stored Path stays unexpanded.
Rollback: revert the squash commit.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#864
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## 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>
## Summary
Resuming an acp instance sends `session/load`, and every
`AcpRemoteError` from it was read as "the agent pruned this id": the
binding was dropped, a fresh session was opened, and only a warning was
logged. GitHub Copilot refuses a load of a session its own process still
holds with `-32602 Session <id> is already loaded`. That session is live
and keeps its context, so the instance lost the conversation the caller
asked to continue, while the result handed to the parent model still
said it could continue the same conversation.
This treats that one refusal as proof the session is live.
`_open_session` keeps the binding, skips `_relearn_modes` and
`_note_session_model` (they read the load result, and there is none),
still puts the requested mode and model on the session as every resume
route does, and returns `(session_id, True)`. Any other refusal keeps
the old recovery.
The refusal is matched on both the code (`-32602`) and the words
("already loaded"), so a pruned id, the right words under another code,
and the right code under other words all behave as before.
Measured on GitHub Copilot CLI 1.0.88 (`copilot --acp`) on this machine,
over plain ACP stdio:
- `session/new`, `session/prompt` ("remember the code word"), then
`session/load` of that id on the same process: `-32602 Session <id> is
already loaded`. A second `session/prompt` on the same id answered with
the code word, so the session was live with its context.
- A second `copilot --acp` process started while the first was alive
loaded the same id without any error. So the refusal comes only from the
process that holds the session; this is not a lock across processes, and
reusing the id cannot hand a caller a session the process does not have.
Scope: `raven/acp_client/acp_agent.py` and `tests/test_subagent_acp.py`.
Grok accepts a load of an open session and is unaffected.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Base is origin/main 2ab065885; this branch is one commit on top of it
(477d64bc4). It was rebased once from b92afe133 after the new main
commit; the figures below are from the rebased head.
```
uv run pytest tests/test_subagent_acp.py -q -k "still_holds or any_other_refusal or load_fallback or pruned or resume"
10 passed
COLORTERM=truecolor make coverage && COVERAGE_BASE_REF=origin/main make coverage-diff
3 failed, 27596 passed, 112 skipped; Diff coverage: 100.00% (12/12 executable changed lines), threshold 90
```
The 3 failures also fail on an untouched checkout of origin/main
(2ab065885), so they are not caused by this change; all three read the
machine rather than the code:
- `tests/test_rpc_files.py::test_a_host_without_libreoffice_says_so`
(LibreOffice is installed here)
-
`tests/test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
(`user.md` and `USER.md` collide on a case-insensitive filesystem)
-
`tests/test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`
(child process returned -15)
Revert-to-red: restoring `acp_agent.py` from origin/main with the new
tests kept turns
`test_a_session_the_agent_still_holds_is_continued_not_replaced` red
(its log line is the symptom: "resuming ... failed (Session held-session
is already loaded); starting a fresh session"). The three
`test_any_other_refusal_of_a_load_still_starts_a_fresh_session` cases
pass both ways by design; they are the controls for the old recovery.
Mutation matrix, one mutant per guard, over the resume tests of
`tests/test_subagent_acp.py`:
```
M1 drop the error-code guard 1 failed
M2 drop the message guard 1 failed
M3 never set the mode on the reuse path 1 failed
M4 report the reused session as not resumed 1 failed
M5 read the missing load result anyway 10 passed (equivalent: _relearn_modes and read_session_current_model treat a missing result as nothing to learn; the guard states the intent)
CONTROL stop unbinding a pruned id 3 failed (the run reaches this code)
```
Lint and gates, all clean at this head: ruff check, ruff format --check,
`make lint-imports`, `make lint-deps`, `make lint-types`, `git diff
--check origin/main...HEAD`, `scripts/check_source_language.py
origin/main...HEAD`, `make check-commits`, `make check-pr-title`, `make
check-large-files`, and `git merge-tree --write-tree HEAD origin/main`
(clean).
Not run in CI: the two Copilot measurements above need a signed-in
`copilot` and cannot run there. The unit tests drive `_open_session`
with a fake client that raises the observed refusal; they were not run
against a live Copilot through Raven's own client.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
A resume that Copilot refuses as "already loaded" now continues the
earlier session instead of opening a new one, so the sub-agent keeps its
context; before, it started over. The reuse relies on the refusal
meaning this process holds the session, which the second-process
measurement above supports for Copilot 1.0.88; an agent that used the
same words for another reason would be reused wrongly, and its next
prompt would fail visibly rather than silently losing context. Rollback
is a plain revert of this 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-sonnet-5-5) <noreply@anthropic.com>
## 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>
## Summary
Native Windows installs fail from the shell Windows ships with. Both
commands the README gives for Windows break under Windows PowerShell
5.1:
- `irm https://raven.evermind.ai/install.ps1 | iex` stops with `(308)
Permanent Redirect`. PowerShell 5.1 follows 301, 302 and 307 redirects
but not 308, which is what that URL answers with. This is the error #148
reported; the README already offered the direct URL for it.
- The direct URL downloads the script, which then stops at "Could not
resolve the latest Raven release wheel from GitHub".
`Resolve-RavenLatestVersion` requests the release page without following
the redirect and reads the Location header off the exception that
raises. Only PowerShell 7 attaches the response to that exception.
PowerShell 5.1 returns the unfollowed redirect as the response and
reports `MaximumRedirectExceeded` as an error with no response, so the
lookup always came back empty. This came in with #299 and has been on
main since.
Changes:
- `install.ps1`: the release-page request uses `-ErrorAction Ignore`
instead of `-ErrorAction Stop`, so PowerShell 5.1 reads Location from
the returned response. PowerShell 7 still raises regardless of
`-ErrorAction` and goes through the existing catch. The Location is
still matched against the same stable-tag pattern.
- CI: the installer job ran `install.ps1` under `pwsh` only, which is
how this shipped. It now also runs the piped install under Windows
PowerShell 5.1 (`shell: powershell`), into its own tool, bin and home
directories, sharing the uv cache.
- Docs: README, README.zh-CN, the docs-site quick start (en, zh) and the
release notes template now say that Windows PowerShell 5.1 stops on the
short URL with `(308) Permanent Redirect` and to switch to the direct
URL when that appears. The short URL's redirect itself is unchanged.
- Tests: tripwires for the lookup (`-ErrorAction Ignore`, catch kept)
and for the CI gate (both shells, and separate tool, bin and home
directories, since the version check runs the `raven.exe` in the bin
directory).
Second topic, Windows test hygiene: three tests failed when the suite
ran on a Chinese-locale Windows checkout. CI runs the unit tests on
Linux only, so it never saw them.
- `test_no_workflow_step_enters_the_removed_page_directory` read
workflows in the locale encoding (GBK there) and stopped on the UTF-8 in
`release.yml`. It now reads UTF-8.
- The font and LibreOffice harness tests run `install.sh` code under
`sh`, which on Windows is Git Bash: its curl sits outside `/usr/bin` and
paths mix separators, so two failed and others passed for the wrong
reason (the digest-mismatch test passed because curl was missing). The
ten harness tests now carry the POSIX-only skip the other three
sh-driven tests already had, shared as one `POSIX_SH_ONLY` marker. Linux
runs are unchanged.
#861 merged first, and this branch is rebased onto it. The one conflict
was in `tests/test_install_script.py`. The sh-driven tests #861 added,
its two Node harness tests and
`test_a_download_that_cannot_be_hashed_is_not_installed`, now carry
`@POSIX_SH_ONLY` like their neighbours, so the marker stays the one
spelling of that skip.
Third topic, test infrastructure: Python's locale-dependent text I/O
uses the system code page when no `encoding=` is passed. On a GBK-locale
Windows checkout, any test that reads or writes a file containing
non-ASCII bytes will fail or silently corrupt data. The class of bug was
found above; there are ~790 `read_text()` call sites without `encoding`
in `tests/`. Measured on Linux under a zh_CN.GBK locale, main without
UTF-8 mode is not one test short: 87 tests fail only there, across 25
files, and `tests/test_rpc_schema_match.py` (418 tests) does not
collect, mostly on `UnicodeDecodeError` from reading UTF-8 files.
- Makefile: `export PYTHONUTF8 := 1`, so every recipe runs in UTF-8
mode, `check-core-wheel` (part of `make ci`) included.
- `tests/conftest.py` raises at import time on any interpreter whose
default text encoding is not the UTF-8 codec, telling the caller to set
`PYTHONUTF8=1` or use `-X utf8`. It compares codecs rather than names,
so Windows with the system-wide UTF-8 option, which reports `cp65001`,
passes. `uv run pytest`, which AGENTS.md documents and which does not
read the Makefile, now stops here on a GBK checkout, as does an IDE
runner that does not set the variable. CI's `--noconftest` self-upgrade
job (its tests all name `encoding` explicitly) is unaffected.
`tests/test_conftest_utf8_guard.py` pins the codec comparison and drives
the refusal in an ASCII-locale child.
- CI sets `PYTHONUTF8` in no job. The jobs that load `tests/conftest.py`
run on ubuntu-latest, where the locale is UTF-8 already, and the `unit`
job gets the variable from the Makefile through `make coverage-shard`.
The Windows self-upgrade job runs its one file with `--noconftest`, and
that file names its encodings. The installer job runs no tests at all:
its steps are raven installing itself and answering `--version`, so the
variable there would only change how raven runs, and that gate exists to
run it the way users do.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on Windows 11 (zh-CN) with Windows PowerShell 5.1.26100 and
PowerShell 7.6.6, before the rebase onto #861 and the second review
round. Every install below was isolated: `UV_TOOL_DIR`,
`UV_TOOL_BIN_DIR` and `RAVEN_HOME` in a temp directory,
`RAVEN_MINIMAL=1`, `RAVEN_NO_LAUNCH=1`.
- Before the fix, under 5.1: `irm https://raven.evermind.ai/install.ps1`
fails with `(308) Permanent Redirect`; `irm
https://raw.githubusercontent.com/EverMind-AI/Raven/refs/heads/main/install.ps1
| iex` stops at `Could not resolve the latest Raven release wheel from
GitHub`.
- `Invoke-WebRequest
https://github.com/EverMind-AI/Raven/releases/latest -MaximumRedirection
0 -UseBasicParsing -ErrorAction Stop`: 5.1 throws
`InvalidOperationException` (`MaximumRedirectExceeded`) with no
`Response`; 7.6.6 throws `HttpResponseException` whose
`Response.Headers.Location` is the tag URL. With `-ErrorAction Ignore`,
5.1 returns the 302 with Location set, and 7.6.6 still throws into the
catch.
- Redirects under 5.1, via httpbin `redirect-to`: 301, 302 and 307 are
followed; 308 is not.
- After the fix, `Get-Content install.ps1 -Raw | Invoke-Expression`
under 5.1 and under 7.6.6, with `uv tool update-shell` disabled in a
temp copy of the script to leave the user PATH alone: both resolved
v0.2.4, installed raven with everos-memory, design-engine and
ppt-engine, and `raven.exe --version` printed `Raven v0.2.4`.
- `uv run pytest tests/test_install_script.py
tests/test_release_plugin_list.py
tests/test_constraints_export_contract.py` plus the six installer tests
in `tests/test_cli_onboard_commands.py`, on Windows: 48 passed, 13
skipped (before: 55 passed, 3 skipped, 3 failed). The two new tripwires
fail against the previous `install.ps1` and `ci.yml`. With the UTF-8
gate added, a bare `uv run pytest --co -q tests/test_install_script.py`
on the GBK checkout raises RuntimeError naming `PYTHONUTF8=1`, while the
same invocations with the variable set pass (45 passed, 13 skipped).
- `uv run ruff check` and `uv run ruff format --check` on both test
files pass; `ty` does not cover `tests/`, the only Python this changes.
`PYTHONPATH=. uv run python scripts/check_source_language.py
origin/main` exits 0.
Run on Linux (Ubuntu 22.04, Python 3.12.13) at this head. A zh_CN.GBK
locale compiled into a private `LOCPATH` gives a non-UTF-8 interpreter
(`locale.getpreferredencoding(False)` is `GBK`, UTF-8 mode off).
- Full suite, `uv run --frozen --python 3.12 --all-extras pytest -q`: 7
failed, 27567 passed, 119 skipped. On main the same command gives 7
failed, 27556 passed, 119 skipped with the identical 7 failing IDs, this
machine's local baseline (five proxy tests, a root-only permission test
and an npm found on PATH), so 0 introduced; the 11 extra passes are this
PR's new tests.
- Main under GBK without UTF-8 mode: 86 failed, 27059 passed, 119
skipped, 11 errors. 87 IDs fail only there, and
`tests/test_rpc_schema_match.py` does not collect. One of the 87, a
non-ASCII file name, is specific to Linux, where GBK also becomes the
filesystem encoding.
- This head under GBK: a bare `uv run pytest --co -q
tests/test_install_script.py` stops at the conftest RuntimeError naming
`PYTHONUTF8=1`. `make test-python`, which exports it: 7 failed, 27567
passed, 119 skipped, the same 7 IDs as under UTF-8. `make
check-core-wheel`: 1 passed, where with the per-target exports it exited
2 at the guard.
- The harness tests marked `@POSIX_SH_ONLY` run on Linux in the full
suite above.
- Mutations: with the old name tuple back in the guard's predicate, only
the `cp65001` case of `tests/test_conftest_utf8_guard.py` fails; with
the guard deleted, its end-to-end refusal test fails. Giving the 5.1
step pwsh's `UV_TOOL_BIN_DIR`, or its `RAVEN_HOME`, now fails the CI
gate test naming the shared variable, where before it passed.
- `make lint-python` passes, and the commit-message, source-language and
large-file gates exit 0 over `origin/main..HEAD`.
- [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: the one-line Windows install works again from Windows
PowerShell 5.1 through the direct URL. The short URL still answers with
a 308 there, and the docs now name that error. `install.ps1` is served
from main, so the fix reaches users on merge, and reverting the squash
commit rolls it back the same way. The resolved Location is still
matched against the same stable-tag pattern before anything is
downloaded. The installer CI job gains one Windows install, which reuses
the uv cache.
Developer-visible: on a Windows checkout whose code page is not UTF-8, a
pytest run that loads `tests/conftest.py` without UTF-8 mode stops at
import with a message naming `PYTHONUTF8=1`; the `make` targets set it,
and Linux and macOS runs are unaffected. On Windows the sh-driven
harness tests report as skipped: the ten this PR marks and
`test_a_download_that_cannot_be_hashed_is_not_installed`, beside the
five that already skipped there.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#148
---------
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
On claude-sonnet-5.5 every call that forces a tool is refused with a 400
("tool_choice: type "tool" and "any" are not supported for this
model."). The research verify gate forces `review_verdict`, so on both
deep-research runs of 2026-09-30 its reviewer returned an error, the
gate failed open, and the reports shipped marked "shipped unreviewed".
The same gate returned real verdicts earlier (acp.log of 2026-09-18:
"draft rejected (4 unsupported claim(s))").
`rewrite_on_400` already repairs the other complaints a vendor can make
about a request and retries once. This adds one more: when the 400 names
`tool_choice` and the request forced a tool (`tool` or `any`), the
choice becomes `auto` and the request is sent again. The tool stays on
offer; a model that declines it answers in plain text, which the verify
gate already parses. Both call sites (`chat` and `chat_stream`) reach
the repair through their existing 400 handling.
Why here and not in the gate: the refusal is a property of the model and
the wire, and any caller that forces a tool meets it. A repair in the
transport needs no model list and no assumption about which models
think. The cost is one refused round trip per forced call on a model
that refuses; nothing is remembered between calls.
Scope: only the repair table in
`raven/providers/anthropic_messages_provider.py` and its tests. Nothing
under `agents/` changes, so the research flow label, the stamped prompts
and the twin-parity tests are untouched.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Base is origin/main b92afe133; this branch is two commits on top of it
(the fix, then a comment and docstring rewording). The suite and
coverage runs below were taken on the first commit; the second changes
one comment and one docstring, and the provider test file was rerun
after it.
```
uv run pytest tests/test_provider_protocol.py -q -k "forced_tool_choice"
3 passed
uv run pytest tests/test_provider_protocol.py tests/test_provider_prompt_cache.py tests/test_provider_catalog.py tests/test_providers_first_byte_budget.py tests/test_providers_stream_idle_budget.py -q
262 passed, 7 skipped
COLORTERM=truecolor uv run --frozen --python 3.12 --all-extras pytest -q
3 failed, 27570 passed, 112 skipped
uv run pytest tests/test_provider_protocol.py -q (after the rewording commit)
106 passed
COLORTERM=truecolor make coverage && COVERAGE_BASE_REF=origin/main make coverage-diff
make coverage exits 1 only because of the same 3 failures; coverage-diff: Diff coverage: 100.00% (4/4 executable changed lines), threshold 90
```
The 3 failures also fail on an untouched checkout of origin/main
(b92afe133), so they are not caused by this change; all three read the
machine rather than the code:
- `tests/test_rpc_files.py::test_a_host_without_libreoffice_says_so`
(LibreOffice is installed here, the test expects 503 and gets 500)
-
`tests/test_simulation_scenario.py::test_a_fresh_trial_refreshes_the_subagent_homes_before_it_runs`
(`user.md` and `USER.md` collide on a case-insensitive filesystem)
-
`tests/test_simulation_suite.py::test_a_stopped_run_is_marked_in_its_record_and_finished_with_its_evidence`
(child process returned -15)
Revert-to-red: restoring
`raven/providers/anthropic_messages_provider.py` from origin/main with
the new tests kept turns all 3 new tests red; restoring the fix turns
them green.
Mutation matrix, one mutant per guard, run against the whole of
`tests/test_provider_protocol.py`:
```
M1 drop the "tool_choice" in text guard 1 failed
M2 drop the forced-type guard 1 failed
M3 rewrite to "none" instead of "auto" 2 failed
M4 return no repair name 2 failed
CONTROL break the ceiling repair's name 1 failed (the run reaches this file)
```
Lint and gates, all clean at this head: ruff check, ruff format --check,
`make lint-imports`, `make lint-deps`, `make lint-types`, `git diff
--check origin/main...HEAD`, `scripts/check_source_language.py
origin/main...HEAD`, `make check-commits`, `make check-pr-title`, `make
check-large-files`, and `git merge-tree --write-tree HEAD origin/main`
(clean).
Not run: a live request to OpenRouter, so the verify gate's handling of
the plain-text reply it will now get on this model has been read in
`research_flow/gates/verify.py` (it falls back to `_parse_verdict`) but
not exercised against the real model. The refusal text and the provider
class were taken from the recorded failing span of 2026-09-30 (audit
span `llm.call`, status ERROR) (`AnthropicMessagesProvider`, `thinking:
adaptive`, `output_config.effort=low`); the retry is exercised against a
mocked transport on both the streaming and the non-streaming path.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
A caller that forces a tool and cannot cope with a reply that has no
tool call would now see such a reply on a model that refuses forced
calls. Before this change the same call failed with an error, so no
working path is affected. The research verify gate is the known caller
and parses a text verdict. Rollback is a plain revert of this 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-sonnet-5-5) <noreply@anthropic.com>
## 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>
## Summary
Follow-up to #841, which lets an agent inherit an OAuth-backed host
model. Since #841 a launcher refuses when the host's selected model
cannot authenticate, but the refusal still said the host config had no
provider key to inherit from. That is untrue in the case #841 made
reachable: the host holds an OpenRouter key while its selected model is
OpenAI Codex with no sign-in.
- `inherit_refusal(config, host)` in `raven/config/product_render.py`
returns the `MissingCredentialsError` summary for the binding
`inherit_llm` checks, or `""` when it would inherit. `inherit_llm`
keeps answering a refusal with `""`, the value every launcher branches
on, scaffolded copies outside this repository included. Both now run
on two private helpers, so the inherited binding is composed in one
place. A non-string `agents.defaults.model` with no provider now
reaches `Config` validation instead of `split_model_id`, so
`host_can_lend_a_key` answers False where it raised `AttributeError`
past its except clause.
- The four keyed launchers and the `raven agents new` template print
that reason and keep the `<KEY> is not set` prefix the scaffold smoke
check matches; raven-design appends it to its own sentence. All six
look `inherit_refusal` up with `getattr` and, on an older raven that
lacks it, refuse with the same sentence without the reason: a folder
the template generates is never refreshed when raven changes
version, and a home tree a newer wheel copied out also serves an
older checkout.
- An agent is spawned with the login shell's environment, and with
raven's own environment only when that shell cannot be captured, so
a `CHATGPT_TOKEN_DIR` or `CHATGPT_AUTH_FILE` set only in the host
process does not normally reach it. This PR documents that rather
than forwarding the variables: the spawn path adds the host's
`RAVEN_HOME` when one is set, and with it unset both sides normally
resolve `~/.raven`, so the default token location is shared; a
custom override can live in the login profile or the agent's stored
row `env`. `agents/README.md` and the `host_can_lend_a_key` and
`host_config` docstrings say so, and the `host_can_lend_a_key`
docstring says why setup can still offer an inheritance the launcher
refuses -- the agent's environment and config are not the host's --
and names the routes, among them a `RAVEN_HOME` from the login
profile or from the agent's stored row. Three older texts in files
this PR edits, which said the launcher inherits `RAVEN_HOME`, say
instead that it normally shares the host's home.
- CHANGELOG records the clearer refusal.
Checked and deliberately left as is:
- `inherit_llm`'s docstring moved below the new helpers verbatim, apart
from the pointer to `inherit_refusal`, so it keeps its older wording;
`git diff --color-moved` shows the move.
- The smoke check in `raven agents new` still matches the old "no
provider key to inherit from" text, because scaffolded copies in
users' homes keep printing it.
- `MissingCredentialsError.remedy` is not appended: every summary this
check raises carries its own command or is answered by the launcher's
closing "configure a provider in the host raven", and the generic
remedy is multi-line.
- A malformed host provider section still ends a launcher with a
validation traceback, exactly as before; the call that raises it
moved into a helper unchanged.
- The same unconditional `RAVEN_HOME` claim also sits in
`raven/agent/subagent/role.py`, twice in `CONTEXT.md` and in
`docs-site/docs/oncall.md` with its Chinese twin. None is in a file
this PR edits, and all predate it; they are left for a separate
change.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Targeted, on the head:
```
uv run --frozen --python 3.12 --all-extras pytest -q -p no:randomly tests/test_config_product_render.py tests/test_subagent_vendored_agents.py tests/test_agents_design_launcher.py tests/test_cli_agents_commands.py tests/test_cli_smoke.py tests/test_agent_schemas.py
```
382 passed, 2 skipped. Deleting each construct this PR adds turns that
run red: the non-string guard (2 failed), the empty-summary fallback
(1), `inherit_refusal` reading its `config` (1), and, in each of the
six launchers, the reason and the parentheses around it (1 each; 2
for the template and for raven-design) and the `getattr` lookup (1
each, when replaced by a direct attribute read). The same run passes
(382 passed, 2 skipped)
with provider API keys exported and `CODEX_HOME` and
`CHATGPT_TOKEN_DIR` pointing at a fake sign-in, so the refusal tests
do not depend on the machine lacking credentials.
Full suite:
```
env -u HTTP_PROXY -u HTTPS_PROXY -u http_proxy -u https_proxy -u no_proxy uv run --frozen --python 3.12 --all-extras pytest -q -p no:randomly
```
2 failed, 27580 passed, 115 skipped. Both failures also fail at the
base, 3632e6040, on this machine and touch nothing here:
`test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(an npm elsewhere on PATH leaks past the fixture) and
`test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(the run is root, which reads a file the test made unreadable). The
proxy is unset because five unrelated provider tests fail when the
shell carries this machine's proxy.
Lint and gates: `ruff check` and `ruff format --check` over the twelve
changed Python files, `ty check` over the eight non-test ones, and
`lint-imports` (10 kept, 0 broken) are clean;
`scripts/check_commit_messages.py origin/main..HEAD`, `commitlint
--from origin/main --to HEAD`, `scripts/check_source_language.py
origin/main...HEAD` and `scripts/check_large_files.py
origin/main...HEAD` exit 0.
Rendered refusals, the first from a host with an OpenRouter key and an
unsigned Codex model, the second from `raven agents new demo-agent` in
a home with no key:
```
error: CODE_API_KEY is not set and the host's model cannot be inherited (openai_codex needs a sign-in -- run `raven provider login openai-codex`); put the key in <agent dir>/.env (see .env.example), export it, or configure a provider in the host raven
error: DEMO_AGENT_API_KEY is not set and the host's model cannot be inherited (no provider is configured yet -- run `raven onboard` for guided setup); put the key in <agent dir>/.env (see .env.example), export it, or configure a provider in the host raven
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The refusal wording changes for raven-code, raven-oncall,
raven-research, raven-ppt, raven-design and the scaffold template; a
script matching the old "no provider key to inherit from" text stops
matching for these launchers.
- The launchers and the template now reach `render.inherit_refusal`
through `getattr`, because each can meet a raven that predates it: a
folder `raven agents new` generated is never refreshed, and the
packaged tree is re-copied on a version change only in the wheel
shape, so a home tree a newer wheel copied out also serves an older
checkout. Every other function they call exists back to v0.2.0, and
on such a raven they refuse without the reason.
- No secret reaches the message: a summary names a provider and a
command, never a key value.
- Rollback: revert the squash commit; nothing is stored or migrated.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
#841
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Both installers verify the private Node.js runtime against the
release's SHASUMS256.txt before running it, but each let the download
through whenever the check could not be made. This makes every such
case stop before extraction.
Measured on `main` before this change, running the real functions
against a fake nodejs.org that serves one release at exact URLs:
| Case | install.sh | install.ps1 |
| --- | --- | --- |
| digest matches | installed | installed |
| digest mismatch | aborted | installed ("continuing") |
| SHASUMS256.txt unreachable | installed | installed |
| package not listed | installed | installed |
| no sha256sum or shasum | installed | n/a (Get-FileHash) |
After it, every row but the first stops with its own reason and a
hint to install Node.js >= 22 with npm and re-run; the installer then
uses that Node instead of downloading one.
- `install.sh`: the three warn-and-continue branches become `die`,
each removing the staged download first. Hashing goes through the
existing `sha256_of` helper.
- `install.ps1`: `Fail` raises under the script's
`$ErrorActionPreference = "Stop"`, and the mismatch `Fail` sat
inside the `try` whose `catch` printed "Could not verify Node
checksum; continuing". Only the fetch stays inside that `try` now.
The fetch also passes `-UseBasicParsing`, so Windows PowerShell 5.1
without the IE engine is refused for missing evidence only, never
for a parser it lacks.
- The optional Chinese font for deck preview counted an empty digest
(no hash tool) as a match. It now compares the digest directly, as
the LibreOffice download already did, so an unchecked face is
skipped with the existing warning and the install carries on.
Unchanged and out of scope: the uv bootstrap (astral.sh) and the raven
wheels are not hash-pinned, and SHASUMS256.txt comes from the same
origin as the tarball over HTTPS, so its signature is not checked.
Context: requirement 1 of the external review in
WenyuChiou/awesome-agentic-ai-zh#289.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run in a worktree. The head `902e351` sits on `3632e6040`; the six
commits `main` gained while this branch was in flight touch none of the
three files it changes. The test-first and mutation runs below were
taken before that rebase, on `5be9698a1`; the full suite and the
installer test file (with pwsh) were re-run at the head.
```
uv run --frozen --all-extras pytest tests/test_install_script.py -k "node_download or cannot_be_hashed"
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest tests/test_install_script.py -k windows_node_download
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest tests/test_install_script.py --idle-ceiling-strict
PATH=<pwsh 7.6.5>:$PATH uv run --frozen --all-extras pytest -q
```
- Tests first, against the unmodified scripts: the first command gave
4 failed (install.sh unreachable, not listed, no hash tool; the font
with no hash tool) while the mismatch and matching cases passed. The
second gave 3 failed (mismatch, unreachable, not listed) and 1
passed. After the change both selections pass.
- One-construct mutations of `install.sh` against the new tests:
dropping the no-hash-tool refusal, the not-listed refusal, the
unreachable refusal, the staged-download cleanup, or the font's
direct comparison each turned exactly one test red; a control that
skips extraction turned the matching-digest test red.
- The installer test file under `--idle-ceiling-strict`: 54 passed,
1 failed; without pwsh, 50 passed, 4 skipped, 1 failed. The failure
is `test_resolve_node_dir_answers_each_case_it_exists_for`, which
fails the same way on the base on this machine: its fixture PATH
includes `/usr/bin`, which holds an npm here. It stubs
`provision_private_node`, so this change cannot reach it.
- Full suite at the head, pwsh on PATH: 27560 passed, 7 failed, 115
skipped in 350.94 s. The seven are this machine's standing failures
on `main`: five proxy tests in
`tests/test_config_update_providers.py` (the shell carries a proxy),
the node-dir test above, and one that fails when run as root:
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
- Live network: the extracted `install.sh` functions provisioned
v22.23.3 from nodejs.org, verified it against the published
SHASUMS256.txt, ran it, and left no staged download, in 6 s.
- `dash -n` and `bash -n` on `install.sh`: clean. The PowerShell
parser over `install.ps1` on this branch and on the base: 0 errors
each. `ruff check` and `ruff format --check` on the test file:
clean.
- Not verified here: `install.ps1` has not run on Windows, and
`-UseBasicParsing` matters only to Windows PowerShell 5.1, which no
test exercises. CI does not close that gap: the two installer jobs
find Node v22.23.3 already on their runners, so neither reaches the
private-Node download this change touches.
- [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 checksum behaviour, so none changed.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
A machine without Node.js >= 22 that cannot fetch the release's
SHASUMS256.txt, or that has neither sha256sum nor shasum, used to get
an unverified runtime with a warning; it now gets an error and the
hint above. A system Node >= 22 never downloads anything and is
unaffected. On the build-time path (a system node without npm) the
download was already subshelled or caught, so a refusal there skips
the TUI and page builds with the existing warning rather than ending
the install. The font step changes only on a machine with no hash
tool. Both scripts are served from `main`, so the change reaches new
installs at merge, and reverting this commit rolls it back the same
way.
## Related Issues
N/A in this repository. External:
WenyuChiou/awesome-agentic-ai-zh#289 (requirement 1, once a tagged
release carries this).
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## Summary
Bump the package version from 0.2.3 to 0.2.4 for the next release. Only
pyproject.toml and uv.lock change.
Since v0.2.3, main merged 29 PRs: four features (#817 previews files by
what renders and answers approvals with cmd+enter, #830 moves channels
out of settings beside agents, #833 lets raven read and change its own
configuration, #853 adds reply-style rules to the host prompt), 19
fixes, four docs PRs, one test PR and one chore. None carries a BREAKING
CHANGE footer, so this is a patch bump, the way v0.2.1 and v0.2.3 were
for their features. A v0.2.4-rc1 tag goes first to dry-run the release
pipeline; the stable tag and release notes follow once this lands.
## Type
- [ ] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [x] Other
## Verification
- `uv lock` on a clean worktree cut from origin/main: Resolved 251
packages, Updated raven v0.2.3 -> v0.2.4
- `git diff --stat origin/main..HEAD`: pyproject.toml and uv.lock, 2
insertions, 2 deletions
- `PYTHONPATH=. python scripts/check_commit_messages.py
origin/main..HEAD`: exit 0
- `npx commitlint --from origin/main --to HEAD --config
commitlint.config.cjs`: exit 0
- No test run: the change is version metadata only.
- [ ] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
## Risk
No code change. Rollback is reverting this commit before any v0.2.4 tag
is pushed.
- [ ] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
Co-authored-by: Claude (claude-opus-5-5) <noreply@anthropic.com>
## Summary
Allow all five shipped agents to inherit an OAuth-backed host model,
including OpenAI Codex, by validating the inherited model binding with
the runtime credential check after parent session overrides.
- Reuse the launcher's inheritance decision in setup and update its
English/Chinese message.
- Preserve raw provider settings, routing, reasoning effort and product
limits. OAuth tokens remain in the host credential store.
- Cover OAuth aliases, access/refresh tokens, missing or malformed
credentials, custom token paths, parent bindings and independent agent
keys. Remove the old API-key-only gate exemptions from the auth contract
test.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Selected regression tests: **321 passed, 48 deselected** on Windows with
Python 3.12. The selection focuses on inheritance and excludes untouched
POSIX permission/pruning scenarios.
```powershell
uv run --no-sync pytest tests/test_config_product_render.py tests/test_subagent_vendored_agents.py tests/test_cli_subagent_setup.py tests/test_provider_auth_method.py tests/test_providers_factory.py tests/test_openai_codex_provider.py tests/test_providers_oauth_login.py tests/test_i18n_prompts.py tests/test_i18n_boundary.py -q -o addopts='' -p no:cacheprovider -k '(not test_config_product_render or inherit_llm or launchers_inherit_oauth or launchers_own_keys or secret_slots or env_wins or dig_and_put) and not prune and not backup and not locks_it_down and not test_a_page_sign_in_runs_the_real_driver_and_leaves_the_token_owner_only' --cov=raven.config.product_render --cov=raven.agent.subagent.vendored_agents --cov=raven.cli.subagent_setup --cov=raven.i18n --cov-branch --cov-report=json:C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_final.json --cov-report=term-missing:skip-covered
```
The following checks passed: Ruff across the repository, formatting
(2149 files), relevant type checks, all 10 import contracts, commit
messages, source language and file/asset checks.
```powershell
uv run --no-sync ruff check raven evolver agents plugins-dist tests scripts docs-site
uv run --no-sync ruff format --check raven evolver agents plugins-dist tests scripts docs-site
uv run --no-sync ty check raven/config/product_render.py raven/agent/subagent/vendored_agents.py raven/cli/subagent_setup.py
uv run --no-sync lint-imports
uv run --no-sync python scripts/check_commit_messages.py main..HEAD
uv run --no-sync python scripts/check_source_language.py main..HEAD
uv run --no-sync python scripts/check_large_files.py main..HEAD
```
Changed-line coverage: **100% (22/22 executable lines)** after
normalizing the Windows report's path separators.
```powershell
uv run --no-sync python -c "import json,pathlib; p=pathlib.Path('C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_final.json'); d=json.loads(p.read_text(encoding='utf-8')); d['files']={k.replace(chr(92), '/'):v for k,v in d['files'].items()}; p.with_name('raven_issue809_coverage_posix.json').write_text(json.dumps(d), encoding='utf-8')"
uv run --no-sync python scripts/coverage_gate.py --coverage-json C:/Users/Administrator/AppData/Local/Temp/raven_issue809_coverage_posix.json diff --base-ref main --head HEAD --threshold 90
```
Full local CI remains unverified: `make ci` could not run because make
is unavailable. Existing POSIX file-permission tests fail on Windows.
`uv run --no-sync deptry raven` reports 12 missing optional channel
dependencies in this environment.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
Inheritance now refuses an unavailable selected model even when an
unrelated provider has an API key. API-key and independent-agent-key
paths remain covered. Credential validation only reads stored OAuth
credentials; it does not sign in or serialize tokens. Revert this change
to restore the previous inheritance gate.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#809
---------
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: KT <74288668+0xKT@users.noreply.github.com>
## Summary
A Cron reminder could reply through Spine delivery and then enqueue a
completion event that made Heartbeat send the reminder again. Use
`TurnOutcome.explicit_reply` to skip that redundant event and wake,
including replies without captured readback text.
Successful runs clear their pending failure event; explicit replies also
clear earlier silent completion events for the same job. Silent
completions, failures, missed reminders, and automatic disabling retain
their notification paths. Add a regression using the real Scheduler,
DeliveryHub, event queue, and HeartbeatService, plus event cleanup tests
and updated English/Chinese documentation.
## 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
The delivery regression failed for both readback variants before the
fix. After rebasing onto latest official main, 167 focused tests passed
with 94.90% combined line/branch coverage for `cron_stack.py`; changed
executable lines have 100% coverage.
```powershell
$env:PYTHONUTF8 = '1'
$env:COVERAGE_FILE = Join-Path $env:TEMP 'raven_issue164_coverage'
uv run --frozen --no-sync pytest tests/test_core_cron_stack.py tests/test_core_cron_stack_ledger.py tests/test_event_wake.py tests/test_gateway_spine.py tests/test_spine_delivery.py tests/test_living_docs.py tests/test_docs_site.py -q --cov=raven.core.cron_stack --cov-branch --cov-report=term-missing
uv run --frozen --no-sync python scripts/coverage_gate.py --coverage-json $ravenCoveragePosixJson diff --base-ref FETCH_HEAD --threshold 90
```
`$ravenCoveragePosixJson` is the generated coverage JSON with Windows
path separators normalized for the diff checker.
Broader Cron service/tool/CLI/TUI coverage passed 336 tests after
excluding two failures reproduced on clean official main: Windows
timestamp resolution in
`test_reload_detects_rewrite_within_float_mtime_collision` and terminal
wrapping in `test_run_test_fire_on_recurring_job`.
```powershell
$ravenCronTestFiles = @((rg --files tests) | Where-Object { $_ -match '^tests[\\/]test_cron_service_.*[.]py$' })
uv run --frozen --no-sync pytest tests/test_core_cron_stack.py tests/test_core_cron_stack_ledger.py tests/test_event_wake.py tests/test_gateway_spine.py tests/test_spine_delivery.py @ravenCronTestFiles tests/test_cron_tool.py tests/test_cron_wake_grant.py tests/test_cli_cron_commands.py tests/test_tui_cron_tool_wired.py tests/test_tui_cron_delivered_event.py tests/test_living_docs.py tests/test_docs_site.py -q -k 'not test_reload_detects_rewrite_within_float_mtime_collision and not test_run_test_fire_on_recurring_job'
```
The following passed: Ruff over the full Python tree, all 10 import
contracts, type checking of the changed module, diff whitespace, asset
limits, and source language checks.
```powershell
uv run --frozen --no-sync ruff check raven evolver agents plugins-dist tests scripts docs-site
uv run --frozen --no-sync ruff format --check raven evolver agents plugins-dist tests scripts docs-site
uv run --frozen --no-sync lint-imports
uv run --frozen --no-sync ty check raven/core/cron_stack.py
git diff --check FETCH_HEAD...HEAD
uv run --frozen --no-sync python scripts/check_large_files.py FETCH_HEAD..HEAD
uv run --frozen --no-sync python scripts/check_source_language.py FETCH_HEAD..HEAD
```
`make ci` could not run because this Windows environment has no `make`.
Full-suite collection and wheel smoke testing also encounter existing
Unix-only assumptions (`os.geteuid` and `venv/bin/python`); full
dependency/type checks require platform-excluded `nio`/`boxlite`
packages. Full Linux CI remains to be checked on the PR.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Explicit Cron replies no longer trigger Heartbeat completion follow-ups.
Existing Spine/DeliveryHub delivery and retry handling remains
responsible for those replies; this change adds no transport
acknowledgement or exactly-once guarantee. No schema, permission, or
dependency changes. Revert this PR to restore the previous event
behavior.
## Related Issues
Fixes#164
Co-authored-by: Codex <noreply@openai.com>
## Summary
The host agent answered even a one-line question like a report: headers,
bullet menus, bold labels and emoji. Its identity said nothing about how
to reply beyond "You are Raven, a helpful AI assistant", and the soul
template listed adjectives ("Helpful and friendly", "Concise and to the
point") that no reply can be checked against, so the model fell back on
its own defaults.
`identity_text` now carries a `## How you reply` section after Raven
Guidelines. It tells the model that the reader may not have seen its
tool results or reasoning, to lead with the answer, to answer a simple
question in plain prose with no headers, bullet list or closing recap,
to keep replies short by leaving things out rather than compressing what
is left, to skip stock openers and closers in any language, and to keep
errors, failing test output, security warnings and caveats the user must
act on in full. A format the user asks for overrides it.
Decisions a reviewer may want to check:
- Host only. Every agent under `agents/` except raven-research renders
this identity, and each carries its own conduct for how it reports. The
section renders through `_reply_style()`, which is empty in a process
the host launched, on the `RAVEN_SUBAGENT` signal `_subagent_note()`
already reads; in such a process the identity text is byte-identical to
`main`. The in-process sub-agent builds its own prompt and never renders
this identity.
- One English section for both reply languages. The language directive
above it still names the language, and the section says it does not
decide one.
- One home for the intent rule. Raven Guidelines already says "State
intent before tool calls"; the new bullet names that rule and adds only
that it is one sentence, said once, with no narration of each routine
tool call.
- The soul template now carries stance and voice only (have a view, know
when to stay quiet, ask only when the answer would change what you do,
no corporate filler), so it does not repeat the format rules. The agent
template drops its duplicate "Be concise, accurate, and friendly" line.
Template sync fills only missing files in Agent home, so both changes
reach new installs only.
- `tests/test_agent_loop_token_budget.py`: the `available_history >
127_000` bound had about 70 tokens of slack once the tool surface had
grown, so any host prompt growth tripped it. It moves to 126_000 with
the trade noted beside it, as the `reserved_tools` notes below it do.
System prompt growth still has no bound of its own.
Not covered: an agent under `agents/` started directly rather than by a
host has no `RAVEN_SUBAGENT` and renders the section, the same boundary
`_subagent_note()` has.
Measured with real one-shot turns (`raven agent`) on the default model,
openrouter/z-ai/glm-5.3-flash: six prompts (a simple question, small
talk, a bad idea to push back on, explaining a project, running a
failing check, an English question), three samples each, each sample in
a fresh Agent home with memory writes and outbound tools off. Before is
`main`, after is this branch. Means per reply:
```text
chars headers bullets bold emoji failing-check error kept
before (main) 699 1.8 4.0 5.8 1.9 3/3
after (branch) 490 0.1 2.6 2.6 0.0 3/3
```
Headers and emoji are effectively gone, bold falls by more than half and
bullets by about a third, and replies are 30% shorter. Every
failing-check reply still quotes the failure, `expected 12, got 9`. Two
things did not move. Replies to requests that used tools still end by
offering the next step about as often as before; on the failing check
that is asking before fixing what the user only asked to check.
Narration before tool calls fell on the failing check (341 to 203
characters) but not on the read-only request (51 to 71). Openers could
not be measured: this model used none on either side. One model and
three samples a cell; another model may move differently.
## Type
- [ ] Fix
- [x] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
```text
uv run --frozen --all-extras pytest tests/ -q -p no:randomly
7 failed, 27459 passed, 116 skipped
uv run --frozen --all-extras pytest tests/test_segments.py tests/test_agent_loop_subagent_role.py tests/test_agent_loop_token_budget.py tests/test_security_untrusted_context.py tests/test_i18n_prompts.py -q
108 passed
make lint-python All checks passed; 2161 files already formatted
make lint-imports Contracts: 10 kept, 0 broken
make lint-types All checks passed
make check-commits exit 0
scripts/check_source_language.py origin/main...HEAD exit 0
scripts/check_large_files.py origin/main...HEAD exit 0
pre-commit run --from-ref origin/main --to-ref HEAD exit 0, no file modified
```
The 7 failures are five proxy tests in
`tests/test_config_update_providers.py` (this machine exports an HTTP
proxy),
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`.
The same 7 ids fail with the change backed out on the same base; CI is
the second machine.
The three new tests in `tests/test_agent_loop_subagent_role.py` were
each checked against a mutant of `render.py`: dropping the section
reddens all three, removing the role gate the first, a stray newline on
either branch the second, and deleting the language clause the third.
With `RAVEN_SUBAGENT=1`, this branch's `identity_text` was compared with
`main`'s and is identical.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Docs box left blank: no user-facing document describes the identity text
or the soul template's contents. The Workspace Template entry in
`CONTEXT.md` calls `SOUL.md` the agent persona, which still holds.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
Prompt text only. The untrusted-content rule is unchanged and comes
first; the override clause covers formatting only. The host prompt grows
by about 260 tokens per turn, inside its stable prefix. Existing
installs keep their `soul.md` and `agent.md`, since template sync never
overwrites. To roll back, revert the squash commit; installs created
while it was live keep the new soul and agent files until those two are
deleted and re-seeded.
## Related Issues
N/A
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## 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>
## Summary
- `tools/list` responses may be paginated with a `nextCursor`; the
connection fetched the list once and registered only the first page,
silently dropping every tool beyond the server's page size (#301).
- `_mcp_server_connection` now keeps requesting `tools/list` with the
returned cursor until the server stops paging, and yields the
accumulated tool list. A repeated cursor stops the loop, so a
misbehaving server cannot page forever.
- This is a reimplementation of #302 by @icn5381 against the current
`raven/mcp/client.py` layout. That PR was auto-closed by the 2026-09-12
history rewrite, not by review; the analysis and repro in #301 carry
over unchanged.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on macOS, Python 3.12, on top of a clean checkout of main:
- `uv run pytest tests/test_mcp_client.py
tests/test_mcp_client_transport.py tests/test_mcp_manager.py
tests/test_mcp_bridge.py tests/test_mcp_change_probe.py
tests/test_mcp_endpoint.py tests/test_mcp_naming.py
tests/test_mcp_prompts.py tests/test_mcp_resources.py
tests/test_mcp_session_addressing.py
tests/test_agent_loop_mcp_meta_tools.py
tests/test_agent_loop_mcp_sync.py tests/test_acp_per_session_mcp.py
tests/test_cli_mcp_commands.py tests/test_sandbox_unit.py -q` -> 357
passed.
- The two new pagination tests in `tests/test_mcp_client.py` were each
watched failing before the fix: two pages register every tool; a
repeated cursor terminates paging.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 26998
passed, 109 skipped, 21 failed. The 21 failures are the same set that
fails on unmodified main in this environment (verified by stashing this
change): `test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the four touched
files -> clean.
- `make lint-imports` -> 10 kept, 0 broken.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- No wire or config change. A server that does not paginate
(`nextCursor` absent or None) behaves exactly as before; the
repeated-cursor guard is the only new stop condition, and it only fires
where the old code would have registered one page and moved on.
- Rollback is a straight revert of this commit.
## Related Issues
Fixes#301
## Summary
- The missing-boxlite advice told users to run `pip install
'raven[sandbox]'`, which is wrong twice over: the `raven` name on
package indexes resolves to an unrelated project, and a global pip
install bypasses the uv environment raven actually runs in (#640).
- Added `boxlite_install_hint()` to `raven.sandbox`: it resolves the
pinned boxlite requirement from the installed distribution metadata
(falling back to the bare name when metadata is absent) and renders a
copy-pasteable command targeting the running interpreter, e.g. `uv pip
install --python /path/to/venv/bin/python boxlite==0.9.5`.
- The onboarding screen keeps its translatable line in the zh catalog
and prints the command on its own untranslatable line;
`build_executor`'s ImportError message uses the same hint.
- The two init-failure messages that fire after the boxlite import
already succeeded no longer suggest a reinstall; they keep the platform
bullets naming the actual causes.
## Type
- [x] Fix
## Verification
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots are updated when needed
Commands run on macOS, Python 3.12, on top of a clean checkout of main:
- `uv run pytest tests/test_sandbox_unit.py
tests/test_cli_onboard_commands.py tests/test_i18n_boundary.py
tests/test_i18n_prompts.py -q` -> 467 passed. The new tests
(TestBoxliteInstallHint, TestInitFailureAdvice, one TestBuildExecutor
case, one onboard screen case) were each watched failing before the fix.
- `uv run --frozen --python 3.12 --all-extras pytest -q` -> 27002
passed, 109 skipped, 21 failed. The 21 failures reproduce identically on
unmodified main (verified by stashing this change):
`test_agents_research_tools.py` (13),
`test_agents_research_verbatim_sink.py` (5),
`test_simulation_scenario.py` and `test_simulation_suite.py` (2),
`test_rpc_files.py::test_a_host_without_libreoffice_says_so` (1,
LibreOffice not installed locally). None touch the changed modules.
- `uv run ruff check` and `ruff format --check` on the six touched files
-> clean.
- `make lint-imports` -> 10 kept, 0 broken.
- `make check-source-language` -> pass.
## Risk
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
- User-visible change: three messages read differently (the onboarding
hint, the build_executor ImportError, two executor init-failure
messages). No API, config, or behavior change beyond the wording. The
hint assumes uv on PATH, which every documented install path already
requires.
- Rollback is a straight revert of this commit.
## Related Issues
Fixes#640
## Summary
Follow-ups to #839 in the browser driver, the browser tools and the
real-browser tests.
**The touch note survives the end of an owner's binding (regression from
#839).** #839 had the driver tell the tools' `_acted` store whenever it
dropped an owner's tab binding, and the store then deleted that owner's
last-act stamp. The readback promises `note: the user interacted with
the browser since your last action` until the owner acts again, and the
end of a binding is not the end of the owner: `Browser.release()` has no
production caller, so the listener fired only on a reap after
`OWNER_IDLE_S`, on the owner's tab closing and on the browser closing.
When the reader closed an agent's tab from the panel, or the binding
idled out, the agent's next read lost the note. The listener is removed
and the driver's owner removal is back to its pre-#839 form;
`_ACTED_MAX` still bounds the store.
**A host missing a system library is told so.** The driver now answers
`Chromium is installed but cannot start here: the system library
libatk-1.0.so.0 is missing. Installing system libraries needs root, so
it is the user's step: on Debian or Ubuntu, <python> -m playwright
install-deps chromium`. Before, on x64 the loader's refusal came back as
Playwright's whole launch log, after a throwaway relaunch that could not
help; where Playwright's own dependency check runs (its linux-arm64
Chromium builds), its report suggests `playwright install-deps`, which
the driver read as "Chromium is not installed". The message says whose
step it is because tool results reach the model too.
**Only failures a fresh profile cannot fix skip the throwaway
relaunch.** The relaunch was gated on the substring "profile", and every
Playwright launch failure quotes the command line,
`--user-data-dir=<home>/.raven/browser-profile` included, so every
failure relaunched and logged "profile is busy". Every failure is still
retried once except a missing system library, Playwright's host check
and a missing executable, and the warning says the launch failed rather
than that the profile is busy. Matching Chromium's lock words instead
would be narrower and wrong under another locale: with
`LANG=zh_CN.UTF-8` a second headful launch on a held profile prints its
line in Chinese, Playwright's English rewrite of it does not fire, and
the error says only "Target page, context or browser has been closed".
**The profile path is read at launch.** `PROFILE_DIR` was computed at
import, before `tests/conftest.py` gives each test its own HOME, so the
real-browser tests used the developer's own `~/.raven/browser-profile`,
with parallel workers opening it at once; the cookie
`test_browser_real_web.py` sets turned up in a developer's own cookie
jar. `_profile_dir()` now resolves the path on each launch.
**The real-browser suites skip on a host that cannot load Chromium.**
`tests/_browser_cache.py` gains `chromium_launch_failure()`: one bare
headless launch per process, with Playwright alone. When it fails for a
missing system library, both
`tests/integration/test_browser_*real_web.py` modules skip with the
library named: the twelve `libatk-1.0.so.0` launch failures reported on
#839 become twelve skips. Any other launch failure, such as an older
build left in the cache or a timeout under load, is not a reason to
skip, and the suites fail on it as before.
`docs/browser-and-desktop.md` said a second process would get a
throwaway profile. The headless shell takes no profile lock, so a second
headless Chromium opens the same profile; the sentence now says so.
Not in this PR:
- `url_for` still predicts the landing page before the permission
prompt, so whatever moves while a person decides moves the call (the
binding-generation idea in the #600 discussion).
- Two headless Ravens share one profile with no lock; documented above,
not changed.
-
`tests/integration/test_browser_tools_real_web.py::test_two_owners_two_tabs_and_neither_takes_the_other`
hung in 2 of 73 runs of both real-browser files on main's tree -- both
times with one profile shared by every worker, never in the 24 runs with
a profile per test -- and in none of 78 runs on this branch or 240 runs
of that test alone. The cause is unknown, and counts this small cannot
credit any change here with a fix. One of the first 45 branch runs, made
before the profile change, also failed one test outright; it was not
seen again and is not explained.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Python 3.12, the repo environment with all extras, run from this tree.
- `python -m pytest tests/test_browser_driver.py
tests/test_browser_tools.py tests/test_browser_cache.py -q`: 129 passed.
With `raven/browser/driver.py` and `raven/agent/tools/browser.py` taken
from origin/main, 15 of them fail: the touch-note test for a reader's
close and for an idle binding, the launch-time profile test, the four
host-library cases, the empty-message retry, and the seven probe tests,
which call a helper main lacks.
- Each guarded construct was mutated on its own (14 mutations, among
them: no stamp after a close, a stamp pruned on a tab close, each of the
three no-retry clauses dropped, the host-library check moved after the
not-installed one, the profile path fixed at import, the probe skipping
on any failure, the probe launching on the caller's loop); each turns at
least one test red.
- Full suite, `python -m pytest -q`: 27482 passed, 116 skipped, 2
failed. Both failures are local to this box and touch nothing this
branch changes:
`tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`
(an npm elsewhere on PATH leaks past the fixture) and
`tests/test_subagent_node_runtime.py::test_what_cannot_be_read_names_nothing`
(the suite runs as root, which reads the file the test makes
unreadable).
- `python -m pytest tests/integration/test_browser_real_web.py
tests/integration/test_browser_tools_real_web.py -q` with a real
Chromium: 12 passed in each of 3 runs. A guard around `_profile_dir()`
logged 39 resolutions, none under the real home, and no file under
`~/.raven/browser-profile` changed during the runs.
- Report shapes: the host-library fixtures follow real launches against
a binary built to need an absent library, with Playwright's dependency
check both skipped (the loader's refusal) and forced (both of its Linux
reports). Two headless launches on one profile: the second starts. Two
headful launches on one profile under `xvfb-run`: with
`LANG=en_US.UTF-8` the error says the profile "is already in use"; with
`LANG=zh_CN.UTF-8` it carries none of Chromium's English lock words.
- `ruff check`, `ruff format --check`, `lint-imports` (10 kept), `ty
check raven`, `scripts/check_source_language.py`,
`scripts/check_large_files.py`: all pass.
- [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: the touch note is reported again after the reader closes
an agent's tab or the binding idles out; a launch that fails for a
missing system library reads as one line naming it, with no throwaway
relaunch; every other launch failure still gets one throwaway relaunch,
under a different warning.
- [x] Security impact considered: the new message names a root command,
and it is worded as the user's step because tool results reach the
model.
- [x] Backward compatibility considered: `Browser.on_owner_released`
(added in #839) and the module constant `PROFILE_DIR` are removed; `git
grep` finds no reader of either outside the two files changed here.
- [x] Rollback path is clear for risky changes: revert the squash
commit; nothing persisted changes shape.
## Related Issues
Follows up #839; refs #600.
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
## 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>
## 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>
## Summary
Fixes the three defects #600 reports in the browser tools, and the test
fixture that failed six real-browser tests on Linux.
**A permission key could name a site the call would not act on.** The
acting tools write the site into the call before the gate reads it, and
took it from `url_for(owner)`, which fell back to the front tab for an
owner with no live binding. When another owner held that tab, the call
opened a blank tab of its own instead: a person approved `bank.test` for
a key press that landed on `about:blank`, and banked a grant that any
later click, type or press on `bank.test` presents, since the three
verbs share one key per site.
`url_for` now reports the page `_page_for` will bind, through one rule
both use (`_landing`): the owner's live tab, else the front tab unless
another live owner holds it, else nothing. In the last case the call
opens a tab of its own, which no site describes yet, so no site is
written and the grant is keyed on the call itself.
The issue offered two directions, and neither is taken as written. An
empty answer for every unbound owner fixes the reported case but breaks
one that worked: with the front tab the reader's own, the call lands on
it while the prompt names no site, and its per-call grant can then be
presented by an identical call on whatever front tab comes next.
Resolving the site after binding would make `cast_params` asynchronous,
and that hook is part of the contract every tool shares.
**`_BrowserTool._acted` was never pruned.** Keyed by `run:<uid>`, it
kept one entry per delegated run for the life of the process: 50,000
runs left 50,000 entries and 6.6 MiB after `gc.collect()`. The driver
now ends every binding through one `_drop_owners` (a reap, a release,
the owner's tab closing, the browser closing) and tells a listener the
tools register on their first stamp. The map also keeps only the 512
owners that acted most recently, for owners whose binding is never
dropped. The same 50,000 runs now leave 512 entries.
**`browser_tabs` did not say that close refuses a tab nobody holds.**
Such a tab is the user's and may hold a login they were asked to
finish, and the listing marks it neither `yours` nor `held`. The
description now says so, as does the browser guide in both languages.
**`test_browser_real_web.py` aimed Playwright at the macOS cache on
every platform.** The suite redirects `HOME`, and Playwright resolves
its cache from the home directory, so the fixture points it back at the
login's cache, but only at `~/Library/Caches`. The look-up now lives in
`tests/_browser_cache.py`, shared by both real-browser suites, and
mirrors playwright-core's `registryDirectory`: XDG_CACHE_HOME on Linux,
LOCALAPPDATA on Windows, `PLAYWRIGHT_BROWSERS_PATH=0` for an install
inside the package, and a relative path. Both suites skipped only when
the package was missing, so a missing browser failed them; they now
check for the browser. The driver called that failure "not installed"
even when the browser sat where the process did not look; the message
now quotes the path it looked for and names PLAYWRIGHT_BROWSERS_PATH,
on one line.
Known gaps, left as they are:
- `url_for` is a prediction made before the prompt. Anything that moves
while a person decides (the reader switches tabs, another owner takes
the front tab, the binding idles past ten minutes) moves the call with
it. Closing that needs the gate to see the binding the call will use;
the issue thread sketches one shape.
- The skip checks for a Chromium directory, not the revision this
Playwright needs. A cache holding only an older build still fails the
launch, and the message then names the path it looked for.
- `browser_tabs` stamps an owner after closing that owner's own tab;
that stamp leaves through the cap rather than through a release.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run with the project environment's interpreter (all extras installed):
- `python -m pytest` over `tests/test_browser_cache.py`,
`tests/test_browser_driver.py`, `tests/test_browser_tools.py`,
`tests/test_browser_policy.py`,
`tests/integration/test_browser_real_web.py` and
`tests/integration/test_browser_tools_real_web.py`: 172 passed. CI
does not collect `tests/integration/`, so those two files ran here
only.
With PLAYWRIGHT_BROWSERS_PATH pointed at a directory that does not
exist, all 12 skip with the new reason instead of failing.
- The `url_for` table, one case per branch of the landing rule, fails
against main in the two cases where another owner holds the front
tab, and against the empty-answer direction in the three where the
front tab is free.
- Deleting each of the 22 constructs that carry this change, one at a
time, turns at least one test red.
- `python -m pytest -q -p no:randomly`: 27132 passed, 7 failed, 116
skipped. The same 7 IDs fail on a complete tree of origin/main: five
provider-proxy tests that read this machine's proxy settings, and two
Node-runtime tests that depend on its node install and on root
ignoring permission bits.
- `ruff check` and `ruff format --check` on the changed files,
`lint-imports` (10 kept, 0 broken), and `ty check raven evolver agents
plugins-dist scripts` (the `make lint-types` set): all pass.
- `scripts/check_source_language.py` and `scripts/check_large_files.py`
over origin/main...HEAD, and `scripts/check_commit_messages.py` and
commitlint over origin/main..HEAD: all pass.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
An acting call that would open a tab of its own is no longer keyed on
the front tab's site: its prompt names no site, and a session grant for
it covers only an identical call, so that state prompts more often. A
call landing on the user's front tab keeps the site key it had. The
browser-unavailable message the panel shows is reworded; nothing parses
it. No config, schema or stored state changes, and reverting the squash
commit restores the previous behaviour.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
Fixes#600
---------
Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>